Upgrade ZendPHP and ZendHQ

Depending on your operating system, perform the following tasks to upgrade ZendPHP and ZendHQ to the latest available version:

To refer back to the installation instructions, see Install ZendPHP and Install and configure ZendHQ.

Upgrade steps for Linux and IBM i

ZendPHP and ZendHQ software is distributed using software package repositories that are compatible with the computer's specific operating system (such as Linux distributions or IBM i OS). The installation and upgrade procedures are identical to those for the OS distribution packages. We do not recommend upgrading Zend packages separately without updating OS packages.

Upgrading ZendPHP is only possible for the same minor version of PHP (for example from 8.3.12 to 8.3.18, not from 8.1.5 to 8.4.5). Upgrading ZendHQ has no version-specific limitations.

The upgrade process for ZendHQ may create extra configuration files. These may be relevant when upgrading from an older major version (for example from 1.7.0 to 2.1.0). If this happens, the system will remain functional, but you should consider reviewing the messages shown in the system console during the upgrade process and perform any suggested manual actions. Configuration files from older versions may not include all the default settings required for newer versions, and vice versa. Configuring the system is easier when the proper configuration files containing the templates for all supported settings are in place.

Installation and upgrade commands on Linux require root access. Use the sudo or doas command to gain the necessary privileges.

Installation and upgrade commands on IBM i require *SECOFR user permissions.

Newer Linux OS versions use dnf (Dandified Yum) tools for package management.

Run the following upgrade command:

Copy 
dnf update

If dnf command is not available (on older distributions, such as RHEL 7 and IBM i OS), use the following command instead:

Copy 
yum update

Any modified configuration files will remain in place. Default configuration files will be provided as an additional copy with the .rpmnew suffix added to the original file name.

If any packages are removed, modified configuration files will be retained and renamed with the .rpmsave suffix.

Run the following upgrade command:

Copy 
apt update && apt upgrade

Any modified configuration files will remain in place.

The Linux package upgrade mechanism allows you to choose between existing or new configuration files if there are any locally made modifications after the initial installation:

  • Choosing the existing (locally modified) configuration file: The new default configuration file will be provided with the .dpkg-dist suffix in the file name, while the locally modified configuration file will remain unchanged.

  • Choosing the package maintainer's version: The locally modified configuration file will be renamed with the .dpkg-old suffix, and the default configuration file from the installed package will become the active one.

Run the following upgrade command:

Copy 
apk update

If local modifications are detected, the new default configuration files will be available with the suffix .apk_new.

Upgrade steps for Windows

ZendPHP can be upgraded in the following ways:

  • By utilizing the MSI installer

  • By downloading ZIP files and extracting them to the installation directory

  • By using the PowerShell installation script

You cannot upgrade an existing non-MSI-based installation (performed using a PowerShell script or by manually extracting ZIP files) using the MSI installer. In this case, install a fresh copy using the MSI installer and manually migrate all PHP configuration settings from the old installation directory to the new one.

Upgrading ZendPHP is only possible for the same minor version of PHP (for example from 8.3.12 to 8.3.18, not from 8.1.5 to 8.4.5).

The MSI installation logic does not overwrite modified configuration files. This logic is the essential part of the MSI installation method and is not controlled by Perforce.

Before upgrading, you must back up your configuration files to ensure they are not lost if the upgrade fails.

To upgrade the existing ZendPHP installation on Windows:

  1. Download the newer version of the ZendPHP MSI installer. This includes the optional ZendHQ PHP extension on Windows.

  2. Run the MSI installer and follow the prompts to complete the upgrade process.

If any files have not been installed properly, the MSI installation method also supports the "Repair” option. This option is available in the Windows Control Panel under "Uninstall or change a program.” To use it, right -click the specific program in the list. This repair feature may be necessary when upgrading to bugfix versions in some scenarios or if any of the files were accidentally removed or replaced.

Because the configuration files may not be compatible, upgrading from a different minor version of PHP is not recommended (for example, from 8.1.x to 8.4.x).

To upgrade using ZIP files or a PowerShell script, perform the following steps:

  1. Manually make a copy of the existing PHP configuration files (php.ini and extension configuration files).

  2. Install the newer version in the same way as the original installation. This will replace all files, including configuration files.

  3. Manually restore the configuration files.

Upgrade troubleshooting

The following table outlines a known issue that may occur during the upgrade process, along with its corresponding error message, description, and recommended resolution.

Problem Error message Description Resolution

ZendHQ API mismatches

 
[Warning] 0MQ socket worker received a message with wrong API version; expected 20250603, received 20240228 (hq_zmq_scoket.cpp:317)

May occur if the ZendHQ extension is updated separately from the ZendHQ daemon (service), and the ZendHQ API version differs.

When this occurs, the ZendHQ PHP extension cannot communicate with the ZendHQ daemon, which can lead to broken applications and downtime.

  • If you updated the ZendHQ PHP extension in your ZendPHP installation, you need to update your ZendHQ daemon (service).

  • If you updated the ZendHQ daemon (service), update the ZendHQ extension on all connected ZendPHP nodes.