Installing ZendPHP on Alpine Linux

The preferred installation procedure for all Linux distributions and for IBM i is the zendphpctl tool. This article describes the alternative manual procedure for installing ZendPHP on an Alpine Linux operating system..

Installing the APK repository

In order to install ZendPHP on Alpine Linux, you must first register its APK repository with your system.

Manual installation

First, you can install the APK repository manually using the following command:

echo "https://repos.zend.com/zendphp/apk_alpine318/" >> /etc/apk/repositories

You also need to add the repository key using the following command:

wget https://repos.zend.com/zendphp/apk_alpine318/zendphp-alpine-devel.rsa.pub -O /etc/apk/keys/zendphp-alpine-devel.rsa.pub

Next, run:

apk update

Access to ZendPHP LTS binaries

In order to install ZendPHP LTS binaries, you need to export the HTTP_AUTH variable with your credentials. For example:

export HTTP_AUTH=basic:*:{USERNAME}:{PASSWORD}

where {USERNAME} is the user name or Order ID provided by Zend, and {PASSWORD} is the corresponding password.

This needs to be performed before any attempt to install packages from the ZendPHP repository.

If using Docker, this could be provided in the Dockerfile, via build arguments, or via an 'env' file when running the container. You also may want to consider using our zendphpctl script instead for installing PHP binaries and extensions, as it manages this for you. We highly recommend using zendphpctl to install PHP and extensions when on Alpine Linux.

Installation using zendphpctl

To install the APK repository using zendphpctl:

zendphpctl repo install

Access to ZendPHP LTS binaries

To allow access to LTS binaries, you can provide your credentials to zendphpctl:

zendphpctl repo credentials --account {USERNAME} --password {PASSWORD}

where {USERNAME} is the username or Order ID provided by Zend, and {PASSWORD} is the corresponding password.

Alternately, you can provide the --account and --password options when calling zendphpctl repo install to set it all up at once.

Installing PHP binaries

After setting up your repository and updating the packages, you can now install ZendPHP. In the examples below, {VERSION} is the PHP minor version (for example, '8.1' or '7.4') you want to install, without the '.' separator (for example, 81, 74).

1. Install the PHP packages:

apk add php{VERSION}zend

This installs a number of common modules and the CLI binary for the specified version. If you want to search for additional available packages, use apk search php{VERSION}zend.

We recommend also installing one of the following packages:

  • php{VERSION}zend-apache2 for mod_apache bindings
  • php{VERSION}zend-cgi for a CGI binary
  • php{VERSION}zend-fpm for PHP-FPM

2. Use the CLI binary:

php{VERSION}zend -v

If desired, you can symlink the binary to /usr/bin/zend:

ln -s /usr/bin/php{VERSION}zend /usr/bin/php

When using zendphpctl, the above is done for the first version of PHP installed; calling zendphpctl php set-default changes the symlink.

3. (Optional) If you have installed PHP-FPM and are using Apache, you need to enable the FastCGI module, and then configure the php-fpm bindings for it. First, add the FastCGI bindings:

apk add apache-mod-fcgid

In /etc/apache2/httpd.conf, ensure the following line is uncommented:

LoadModule setenvif_module modules/mod_setenvif.so

Next, you need to add the following configuration to Apache, assuming that Apache and PHP-FPM are running on the same machine; you can place the following in a file under /etc/apache2/conf.d/:

Copy 
 <IfModule proxy_fcgi_module>
    # Enable http authorization headers
    <IfModule setenvif_module>
    SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
    </IfModule>

    <FilesMatch ".+\.ph(ar|p|tml)$">
        SetHandler "proxy:fcgi://localhost:9000|fcgi://localhost"
    </FilesMatch>
    <FilesMatch ".+\.phps$">
        # Deny access to raw php sources by default
        # To re-enable it's recommended to enable access to the files
        # only in specific virtual host or directory
        Require all denied
    </FilesMatch>
    # Deny access to files without filename (e.g. '.php')
    <FilesMatch "^\.ph(ar|p|ps|tml)$">
        Require all denied
    </FilesMatch>
</IfModule>

Finally, start the PHP-FPM pool and Apache2:

/etc/init.d/php-fpm{VERSION}zend start
/etc/init.d/apache2 start

(Configuration for the PHP-FPM pool is in /etc/php/{VERSION}zend/php-fpm.d/)

4. (Optional) If you have installed PHP-FPM and are using nginx, you need to create a virtual host configuration for nginx that proxies PHP requests to its FastCGI pool. For example:

Copy 
server {
    listen 80;
    root /var/www/html;
    server_name _;
    index index.html index.html index.php;
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_index index.php
    }
}

(Assuming that your PHP-FPM pool is running on a socket exposed on port 9000.)

Ensure you start your PHP-FPM pool before starting nginx.

Installing extensions on Alpine

For a variety of reasons, we do not ship PECL with Alpine Linux. As such, you need to perform the following steps in order to compile custom extensions.

  1. Install the ZendPHP development package:

    apk add php{VERSION}zend-dev

  2. Retrieve the extension tarball from https://pecl.php.net. Generally speaking, the latest version of a PECL package can be found using the following URL structure:

    https://pecl.php.net/get/{extension}.
    You can retrieve a specific version using: 
    https://pecl.php.net/get/{extension}-{version}.tgz.

  3. Create a working directory, and extract the package:

    mkdir -p /tmp/pecl-{extension}
cd /tmp/pecl-{extension}
tar xzf path/to/extension.tgz

  4. Use phpize to prepare the package for compilation:

    phpize{VERSION}zend

  5. Configure the package. After phpize has run, you can use the generated configure script to configure compilation. We recommend running ./configure --help to see what the various options are; in many cases, most if not all can be ignored. However, you MUST use the --with-php-config option:

    ./configure --with-php-config=/usr/bin/php-config{VERSION}zend

    You may get errors indicating you are missing required libraries. If you do, you need to search the APK repository for the correct package providing the library, and then install it before attempting to configure again.

  6. Assuming configuration succeeds, you can compile and install the package:

    make
make install

  7. Enable the extension by adding a configuration file to the /etc/php/{VERSION}zend/conf.d/ directory. We recommend naming these 20_{extension}.ini or similar, with the following contents:

    extension={extension}