Upgrading

Upgrading PHP Draft 2.2 or higher using Deployer

Seamlessly deploy new versions of PHPDraft using Deployer.

Server requirements can be found in the install instructions (Yarn, Node, etc.)

1. Download the latest release from the project releases page, extract it to a temporary local folder
2. Open a terminal window and navigate to the temporary local folder.
   • Note here that every call to the Deployer binary (vendor/bin/dep) will include local at the end. This corresponds to the value specified in your deploy.php file for stage. If you never changed this, continue using local, but if you have multiple environments you deploy to, you may find it helpful as an extra check before you accidentally deploy the wrong settings to the wrong environment.
3. Run vendor/bin/dep import local and provide the settings importer with the location of your settings backup.
   • Alternatively, if you have no settings backup you should run the PHP Draft setup wizard by running vendor/bin/dep setup local. After completing the wizard, it is recommended you back your settings up by running vendor/bin/dep backup local
   • Pay attention to changelogs and release notes when upgrading. Occasionally, you will need to re-run the setup wizard in order to generate new settings as breaking changes occasionally make their way into these files. As a rule, I will always bump up the minor version number (the middle one) when new settings must be generated, but updates to the patch number (the last one) will suggest you needn't update them.
4. Run vendor/bin/dep deploy local to begin the deployment process.
5. Optional: If using php-fpm, you will need to restart the service as the deployment process uses symlinks, and PHP will still be using the previous release of code.
6. Important! Be sure to wipe your browser's cache before reloading your install (in Chrome, open the Developer Tools, then you can right click on the Refresh button and select "Empty Cache and Hard Reload") and verify that the upgrade worked before finishing.

Upgrading PHP Draft 2.1 to 2.2 using Deployer

In addition to adding Deployer deployments, version 2.2 also added Phinx database migrations in favor of hand-coded SQL files. Now, database updates are done automatically via the deployment process for a cleaner, more consistent deployment experience.

1. Back up your site database and files so that in the event that something goes wrong, you can restore PHP Draft.
2. Download the latest release from the project releases page, extract it to a temporary local folder
3. First, prepare your webserver to point to a symlink called current from within the current base directory. If your site is currently being served from /var/www/example.com/html, move all of that code into a folder called /var/www/example.com/html/releases/0 and create a symbolic link current that points to the 0 folder (so /var/www/example.com/html/current).
4. Ensure your webserver correctly serves and runs PHP Draft with the symlink in place before continuing.
5. Also ensure that the current user on the computer you intend to publish upgrades from has an SSH key setup with the web server that your current instance of PHP Draft runs on. Deployer utilizes SSH tunnels to connect and upload files as well as run scripts such as Phinx to update the database with any changes. Need help? Follow this guide to generate an SSH key and install it on your webserver.
6. Next, grab the /db/scripts/2.1_to_2.2_Upgrade.sql script and run it against your PHP Draft database. In addition to changing charsets over to utf8, this also adds the necessary Phinx table to track database changes in the future.
7. Open a terminal window and navigate to the temporary local folder (see above).
8. Run the PHP Draft setup wizard by running vendor/bin/dep setup local. After completing the wizard, it is recommended you back your settings up by running vendor/bin/dep backup local
9. Run vendor/bin/dep deploy local to begin the deployment process.
10. Optional: If using php-fpm, you will need to restart the service as the deployment process uses symlinks, and PHP will still be using the previous release of code.