Install and configure ZendHQ

This topic describes the procedures for installing ZendHQ. ZendHQ is made up of two pieces, a service daemon and a PHP extension.

Requirements

ZendHQ has the following requirements:

  • In all cases, the ZendPHP repository must be installed first.

  • For the service daemon:

    • The service daemon is supported only on Linux and IBM i.

  • For the PHP extension:

    • On Linux and IBM i, the ZendHQ extension is available for PHP versions 7.2 and later.

    • On Windows, the ZendHQ extension is available for PHP 7.3 and later.

Do not load XDebug and ZendHQ extensions at the same time. This applies to all supported ZendHQ platforms and supported PHP versions. Both extensions interact closely with PHP internals. This can cause conflicts between the extensions resulting in errors or invalid results for ZendHQ. For this reason, running the ZendHQ extension in parallel with XDebug is not supported.

Install the ZendHQ service

To install the ZendHQdaemon, install the zendhqd package for your platform. The ZendHQ daemon can run on a ZendPHP server, or separately. If you are running ZendPHP on multiple servers, run the ZendHQ daemon on a separate server.

  1. Install the ZendPHP repository on your system before installing ZendHQ.

    Use either the zendphpctl repo install script, or see the platform-specific ZendHQ installation documentation.

  2. Install ZendHQ for your platform.

    Choose one of the following options:

    Copy

    DEB-based systems

    apt install zendhqd
    Copy

    RPM-based systems (option 1)

    yum install zendhqd
    Copy

    RPM-based systems (option 2)

    dnf install zendhqd
    Copy

    Alpine-based systems

    apk add zendhqd
    Copy

    IBM i systems

    yum install zendhqd

    On IBM i systems, you can also use Access Client Solutions (ACS).

Control the ZendHQ service

On initial installation, the daemon should start. During an upgrade, if the daemon is running, it should restart. To validate the status of the ZendHQ daemon, run one of the following commands, as needed.

Alpine Linux does not use systemd, and therefore the systemctl command is not available. To manage the ZendHQ service on Alpine, you need to start and stop the daemon manually using standard shell commands or manage it through container orchestration tools if running in a containerized environment.

  • To determine if ZendHQ is running:

    On Linux:

    Run the following command:

    Copy

     

    systemctl status zendhqd

    On IBM i:

    From the ZendPHP main menu (GO ZENDPHP/ZPMENU), select option 2. ZendHQ, and then choose option 21. Status.

  • To start the ZendHQ daemon:

    On Linux:

    Run the following command:

    Copy

     

    systemctl start zendhqd

    On IBM i:

    From the ZendHQ Menu, select option 3. Start ZendHQ Daemon.

  • To restart an already running ZendHQ daemon (for example, to pick up configuration changes):

    On Linux:

    Run the following command:

    Copy

     

    systemctl restart zendhqd

    On IBM i:

    From the ZendHQ Menu, select option 5. Reload ZendHQ Daemon.

  • To stop the ZendHQ daemon:

    On Linux:

    Copy

     

    systemctl stop zendhqd

    On IBM i:

    From the ZendHQ Menu, select option 4. Stop ZendHQ Daemon.

Install the ZendHQ PHP extension

To enable the ZendHQ extension on servers running ZendPHP, install one of the following packages:

  • For DEB-based servers, install the php{VERSION}-zend-zendhq package, where {VERSION} is the PHP minor version.

    Copy
    Example for PHP 8.4
    apt install php8.4-zend-zendhq

  • For RPM-based servers, including IBM i, install the php{VERSION}zend-php-zendhq package, where {VERSION} is the PHP minor version minus the dot separator.

    Copy
    Example 1 for PHP 8.4
    yum install php84zend-php-zendhq
    Copy
    Example 2 for PHP 8.4
    dnf install php84zend-php-zendhq

  • For Windows-based servers, there are several options. To learn more, see Install the ZendHQ PHP Extension on Windows.

    Copy
    Example for installing PHP 8.4 using the installation script on a server with IP address 10.0.0.1
    zendphp-8.4-latest-nts-x64.msi

Licensing

Install the license file. After getting your license from Zend Support, copy it to the file /opt/zend/zendphp/etc/license on the server where you have installed the ZendHQ daemon. The ZendHQ daemon is the holder of the license.

The ZendHQ extension on Windows does not need a separate local license on the Windows machine. If the ZendHQ daemon has a valid license, the ZendHQ extension will work normally.

ZendHQ node configuration

Configure the server running the zendhqd so that it can communicate with:

  • ZendPHP nodes
  • The ZendHQ User Interface

These URIs are configured in the file /opt/zend/zendphp/etc/zendhqd.ini. The relevant settings for these are, with their defaults, respectively:

  • zendhqd.daemon_uri = tcp://127.0.0.1:10090
  • zendhqd.websocket.interface = 127.0.0.1:10091

If you want the zendhqd.daemon_uri to listen to port 10090 on any IP address, use tcp://0.0.0.0:10090. To configure the zendhqd.websocket.interface setting to listen on any IP address behind your firewall, specify the port only, prefixed by `:`; For example, `:10091`.

Do not configure the zendhqd.websocket.interface setting to listen on all IP addresses unless the ZendHQ daemon is behind a secure firewall. Not specifying an IP address poses a security risk.

For these changes to take effect, restart the zendhqd daemon. For more information, see ZendHQ Service Configuration.

ZendPHP node configuration

Configure your ZendPHP nodes to communicate with the ZendHQ node. Edit the configuration file for the extension, which is in one of the following locations:

  • DEB: /etc/php/{VERSION}-zend/mods-available/zendhq.ini

    where {VERSION} is the PHP minor version (such as 7.2, 8.0, 8.1).

  • RPM: /etc/opt/zend/php{VERSION}zend/php.d/90-zendhq.ini

    where {VERSION} is the PHP minor version, minus the . separator (such as 72, 80, 81).

  • Alpine: /etc/php/<XY>zend/conf.d/10_zendhq.ini

    where X is the PHP major version and Y is the PHP minor version, for example, /etc/php/74zend/conf.d/10_zendhq.ini for ZendPHP 7.4.

  • IBM i: /etc/php/<XY>zend/conf.d/90-zendhq.ini

    where X is the PHP major version and Y is the PHP minor version, for example, /etc/php/74zend/conf.d/90-zendhq.ini for ZendPHP 7.4.

Change the zendhq.daemon_uri setting so that it mirrors your zendhqd.daemon_uri setting.

Copy 
zendhq.daemon_uri = tcp://192.168.0.10:10090

You may specify the IP address or a name that resolves to that IP address via DNS. (For example, with docker-compose or kubernetes, you might specify a service name for the ZendHQ node.)

If you are using PHP-FPM, restart your FPM process for the changes to take effect. For example:

Copy

On Debian Linux systems (Debian, Ubuntu)

systemctl restart php7.4-zend-fpm
Copy

On Enterprise Linux systems (RHEL, CentOS, Alma, Rocky, Oracle)

systemctl restart php74zend-php-fpm

On IBM i, ZendPHP uses FastCGI to integrate PHP with the Apache HTTP Server. Unlike traditional Linux environments where PHP-FPM is managed as a separate service, on IBM i, PHP-FPM is not started or stopped independently.

To apply configuration changes (for example, updates to zendhq.ini), you must restart the Apache HTTP Server, which will also restart the FastCGI processes handling PHP.

To restart Apache (and PHP-FPM):

  1. From the ZendPHP main menu, select option 3. Apache.

  2. In the Apache menu, select option 2. Stop to stop the HTTP server.

  3. To start the HTTP server again, select option 1: Start.

    Restarting Apache ensures that any changes made to PHP configuration files, such as zendhq.ini, are applied.

Install the ZendHQ user interface

ZendHQ has a separate GUI for interacting with the daemon. For more information about how to install it on Windows, macOS, or Linux, see ZendHQ User Interface Installation.

Also in this section