Quick tutorial on how to update a HydePHP site

Introduction

In this quick post, I'm going to go over my process for updating an existing HydePHP site to a new HydePHP version. If you don't have a Hyde site yet, you may want to check out my other tutorial "Creating a new Hyde site from scratch"!

This guide is written while HydePHP is still in beta, and as such we are deviating slightly from semantic versioning as backwards compatibility is not guaranteed while in the 0.x series range. Everyone's projects will be different, and the methods used in this post for this specific site may not work for your project. Please see the general update guide for more information.

Background

Today I released Hyde version 0.30, which adds a new cool feature that lets you use Laravel Blade within your Markdown files. HydePHP.com is of course built with Hyde, but is currently on version 0.29.3, so let's update it!

Quick primer

First, a primer on the structure of HydePHP.

It's split into two packages. First, we have hyde/hyde which is like laravel/laravel and binds everything together. When you create a new Hyde project, you will be using this package.

The bulk of the Hyde logic, however, is in the hyde/framework package.
Which is equivalent to laravel/framework. Having the logic separated here makes it much easier to update existing projects as patches can be installed by simply updating the hyde/framework package.

But since this specific release adds some changes to the files in hyde/hyde we'll need to update them both. Let's get started!

Update the HydePHP.com site

Since the HydePHP.com site was created using the installer for hyde/hyde it's very easy to update.

Step 1: Syncing with Git VCS

The source code for the site is located in the GitHub DocsCI repository. Whenever we push to the main branch the static site will be compiled by a GitHub Action and then deployed to GitHub Pages.

First, we want to make sure we are up to date with the DocsCI repository.

git pull origin master

Now we can download the latest hyde/hyde version. I like to do this using Git so I can take care of any merge conflicts that might arise. To do this I have set up an extra Git remote called package which points to the hyde/hyde repository.

# Refresher on adding a remote, you only need to do this once
git remote add package git@github.com:hydephp/hyde.git

Now we can pull the package files:

git pull package master

Step 1B: Handle any merge conflicts

You'll probably have some merge conflicts at this stage. In my case, I had two. The first one is for the composer.lock, and since I'll be updating dependencies later I don't care about that so I'll just keep the one from the master.

Next, I have a conflict in the config/markdown.php file. This is because this release adds a new config option to this file. And since I want to be sure that I have the latest config version, while not losing my custom changes I'll open it up in VSCode and inspect the changes.

As we can see, this is a simple change and there is no real conflict so I'll accept the incoming change and save the file, taking one extra look to make sure nothing looks broken. Once I feel confident that the merge is good to go I'll commit it.

Step 2: Updating dependencies

To make sure we are up to date with everything I'm updating both NPM and Composer dependencies.

npm update
composer update

Then I'll commit the lock file changes if there are any.

Step 3: Building the site to verify the install

Next, to prevent any surprises in the CI it's best to compile the static site and build any assets to catch any issues before deploying to production.

First, run the hyde build command.

php hyde build

Then since this project uses Laravel Mix to compile frontend styles, we'll run the prod command for that.

npm run prod

Now I'll open up the site in Chrome

start chrome file://H:/DocsCI/_site/index.html

And I'll take a look around. Right away I see that the scrollbar is now dark, which is a new addition. And all page types seem good to go.

Finishing up

So I'm happy with the result of the update, so I'll go ahead and push the changes to the DocsCI repository! Then after a minute or two, the updated site will have been deployed to HydePHP.com, so I'll take a quick look there as well to make sure the production deployment went smoothly as well.

Please share any feedback you have with me on this post, I'd love to hear from you! Do you have any questions? Ideas on how to improve this workflow? Let me know!