Upgrading MPOS

Preparation

This guide will help you to upgrade your existing PHP-MPOS instance to the latest version. Keep in mind that PHP-MPOS is heavily relying on git so make sure you cloned properly.

Checking for Changes

Check the local version to see if it needs upgrading. This is done from the folder which contains CHANGELOG.md:

git log -1

The output will look like this:

commit 971006b7a2ddf8315ed69c5a4a530da3d77d9b23
Author: *commit author and email*
Date:   *commit date*

   *change log*

This is the local version. The string in the commit line 971000...9b23 can be used to compare a local copy to the master version on GitHub. Copy the commit string and access GitHub at the following address to see what has been changed:

https://github.com/TheSerapher/php-mpos/compare/YOUR_COMMIT_STRING_HERE...master

This will show all the changes between the local copy and what's available in the repository.

Maintenance Mode

Enable the maintenance mode in PHP-MPOS from the web interface (Admin Panel -> Settings). This will notify site users of an update in progress. It is also advised to disable any cronjobs set in the crontab during an update to avoid errors, though during the upgrade crons will be disabled anyway (with error) if any manual steps are required.

Enable Admin Checks

If you have disabled the first-time setup admin checks, please re-enable them. This way you can make sure you have not overlooked anything that may have changed. We will try to add tests for those things that we deem important whenever we add some changes that may be overlooked by people.

Just set $config['skip_config_tests'] = true; to $config['skip_config_tests'] = false; and you should all messages again.

Update

These steps are all performed in the folder which contains CHANGELOG.md.

Tagged Releases

If you cloned from the repository and switched to a tag (e.g. git checkout v1.0.3) during the installation (which you should do), you can run a rather save upgrade following these simple steps:

# Fetch latest master including new tags
git pull origin master
# Checkout the latest version, see previous pulled tags for latest tag
git checkout vX.Y.Z
# Upgrade SQL if upgrade are available
./upgrade/run_upgrades.php

If your checkout of the new tag fails, that probably means you have edited some files locally that are part of the repository and they can not be merged cleanly. In that case, either stash (see further down below) or reset your working directory, then try the checkout again.

Master Clone, discarding changes

A direct clone on the master branch can perform this by calling:

git reset --hard HEAD
git clean -f
git pull

This will destroy all local file changes. However new files created, such as a copy of the config file, will be left alone.

Upgrade, keeping local changes and re-applying them

A direct clone on the master branch (or before trying to switch tags) can perform this by calling:

git stash
git pull

This saves any local changes made into the local stash then pulls and applies upgrades similar to a clean install. However if the update is found to be faulty, the previous version of the files can be restored by calling:

git stash apply

SQL Upgrades

Run the supplied upgrade/run_upgrades.php script to upgrade your database to the newest version.

Configuration Upgrades

If there has been a change to the global.inc.dist.php then any in use configuration file may need updating. To identify changes that need be applied use:

diff /PATH/TO/global.inc.dist.php /PATH/TO/global.inc.php

Disable Maintenance

Once the site update is finished, maintenance mode can be disabled. Re-enable crons on the crontab if disabled and check for errors.