The matrix_upgrade.php script automatically upgrades your system from one version to another, displaying a file comparison of your current system and the Matrix version you are upgrading to, as well as a description of the upgrade steps that will be performed. Please note that this script only supports updates of Matrix versions 3.28.0 and higher.

Downloading the Script

Access to the script via GitHub is only available upon special request from Squiz. Please contact Squiz for more information.

The Matrix Upgrade Script can be downloaded from the Squiz Labs Git repository located at https://gitlab.squiz.net/Labs/MatrixUpgrades.

Please note that GitLab is used by Squiz Staff only, use https://github.com/squizlabs/MatrixUpgrades if you are using GitHub.

It is recommended that you always use the latest version of the Matrix upgrade script available for download from the master branch each time you perform an upgrade.

Once you have downloaded the Matrix upgrade script, unzip the file to a location on your server.

Configuring the main.conf File

Before using the Matrix upgrade script, you must first check the configuration of the main.conf, located at automatic_upgrades/conf/main.conf. The following settings must be checked:

• git: The configuration settings for the Matrix Git repository, including the location of the Git repo and the path of the Git command. By default, the following settings are used to access the Matrix Git repository:
  • location: 'https://gitlab.squiz.net/Labs/Matrix.git'
    (GitLab is used by Squiz Staff only, use 'https://github.com/squizlabs/Matrix.git' if you are using GitHub)
  • path: '/usr/bin/git'
• pre_uploaded (base_folder): The directory used when sourcing code from a pre-uploaded folder location on your server. If you are only using a Git repository, this can be left empty.
• file_perms: By default, the script will restore the Matrix, data and cache folders to the file permissions originally set on them. You can overwrite these permissions using this configuration option which is commented out by default, and can be used to set file system permissions after each upgrade.
• keep_packages: The packages to be kept from the existing system when checking out new code from Git during the upgrade procedure. This option is useful when your system contains custom packages that you want preserved in the updated system.
  
  An example usage of this option is as follows:
  

  'keep_packages' => Array(
                            'example_package_name1',
                            'example_package_name2',
                          ),

• php_path & php_options: The full path to PHP to run scripts, installation steps etc. on the upgrade procedure. Command line options can be specified. For more information on the PHP options available, refer to the PHP: Options manual.
  
  An example usage of this option is as follows:  

  'php_path' => '/usr/bin/php',
  'php_options' => '-c /path/to/php.ini',

  Please note that these settings are optional. If no PHP path is specified, the system's default PHP will be used.

Understanding the Script Parameters

The Matrix upgrade script takes the system root and the version of Squiz Matrix that you want to update to as arguments. This script can also be passed the following optional arguments:

• -F: Forces the copying of new system code (from Git or a pre-upload location) even if there are modified files on the system. If omitted, the upgrade procedure will be aborted if modified files are reported.
• -n: Setting this option will mean that the script will not actually perform an upgrade of your system, but instead show an upgrade report with the steps that will be performed.
• --backup=<option>: Suppresses the option to backup the current system before upgrading. Setting <option> to force will perform a backup before each version upgrade, when running the script. Setting <option> to skip will mean that the script will not backup your system. If this argument is not used, users will be prompted of whether to create a backup or not.
• --disable-colour: Disables colours in the script output.
• --pre-upload=<option>: Set <option> to disable to temporarily disable sourcing code from pre-uploaded folder locations.
• --step: Allows you to confirm the details of each individual installation step before continuing (e.g. 'press any key' to continue).
• --autostep: Allows you to skip the confirmation prompts when proceeding between version upgrades.
• --verbose: Displays a full list of upgrade steps for each version at commencement.
• --check_diff=<option>: Creates a comparison between the current system and the version being updated to. Setting <option> to disable will mean that the script will not compare and display the files that will require modification.
• --truncate_rollback: Truncates all rollback data. This should be used primarily between major upgrades.
• --checkout_only: Use this option to download all of the Matrix versions required to perform the upgrade. These versions will be downloaded to a 'checkout' folder ready for use; no upgrade will actually take place if this parameter is used.
• --ees: Download and install the Edit+ package as part of the upgrade. Works with --checkout_only and --pre-upload options as well.
  

  The --ees option is only supported for Squiz hosted systems.

Displaying Upgrade Steps

The --show_steps argument allows you to view a full list of upgrade steps between two specified versions of Squiz Matrix.

Usage of this script is as follows (please note that the database type must be specified when using this argument):

php matrix_upgrade.php --show_steps 5-1-2-0 5-1-4-4 psql

php matrix_upgrade.php --show_steps 5-1-2-0 5-1-4-4 oci

Upgrading your System

Before initiating the upgrade script, ensure that your server satisfies the minimum requirements for installation. For more information, refer to the Squiz Matrix Requirements. It is also recommended to put your system into Maintenance Mode to ensure that no unexpected data is written and saved to your Squiz Matrix instance during the upgrade.

An example of how to use the upgrade script is shown below. In this example, we are upgrading a Squiz Matrix 5.1.2.0 system to 5.1.4.4. The --verbose argument has been used to display the list of upgrade steps that will be performed. The --backup=force argument has also been used to perform a backup before each version upgrade.

php matrix_upgrade.php --verbose --backup=force /path/to/matrix 5-1-4-4

Running the above command will first display the list of upgrade steps and then prompt you to proceed with the upgrade by pressing ENTER.

Old ver.   | New ver.   | File                 | Description of steps                              
---------- | ---------- | -------------------- | --------------------------------------------------
5-1-2-0    | 5-1-3-0    | 5-1-2-0_to_5-1-3-0   | Clear locks                                       
           |            |                      | Disable dejavu                                    
           |            |                      | Disable trigger manager                           
           |            |                      | Disable search indexing                           
           |            |                      | Disable rollback                                  
           |            |                      | Check out new code, using tag "5-1-3-0"           
           |            |                      | Run install step step_02                          
           |            |                      | Run install step compile_locale                   
           |            |                      | Run install step step_03                          
           |            |                      | Run install step compile_locale                   
           |            |                      |    Enable dejavu                                  
---------- | ---------- | -------------------- | --------------------------------------------------
5-1-3-0    | 5-1-4-0    | 5-1-3-0_to_5-1-4-0   | Clear locks                                       
           |            |                      | Check out new code, using tag "5-1-4-0"           
           |            |                      | Run install step step_02                          
           |            |                      | Run install step compile_locale                   
           |            |                      | Run install step step_03                          
           |            |                      | Run install step compile_locale                   
           |            |                      | Run script: Upgrade form actions to mark them to be executed before
           |            |                      |    creation of submission asset                   
---------- | ---------- | -------------------- | --------------------------------------------------
5-1-4-0    | 5-1-4-4    | standard_patch       | Check out new code, using tag "5-1-4-4"           
           |            |                      | Change ownership of data and cache directories to "apache:apache"
           |            |                      | IF Rollback Mode was previously enabled:          
           |            |                      |    Enable rollback                                
           |            |                      | IF Search indexing was previously enabled:        
           |            |                      |    Enable search indexing                         
           |            |                      | IF Trigger manager was previously enabled:        
           |            |                      |    Enable trigger manager                         
           |            |                      | IF Dejavu was previously enabled:                 
           |            |                      |    Enable dejavu                                  
---------- | ---------- | -------------------- | --------------------------------------------------
Now upgrading from 5.1.2.0 to 5.1.3.0                       [ Press ENTER to start ] 

In this example, the 5.1.2.0 system will first be upgraded to 5.1.3.0, then to 5.1.4.0 and finally 5.1.4.4. Pressing ENTER will begin the upgrade procedure.