PHP and PHP-FPM

This tutorial describes how to configure and use PHP and PHP-FPM on Clear Linux* OS.

Description

The PHP language is an Open Source general-purpose scripting language that is popular with web-developers who leverage its ability to create dynamically generated web pages. PHP-FPM is a PHP FastCGI implementation that controls process management, workers, and logging for PHP. The two applications work together, but each one has its own configuration.

This tutorial specifically addresses PHP and PHP-FPM, however, it provides a general guide for working with applications in the Clear Linux OS Stateless environment.

Background

By default, PHP looks for configuration settings in the php.ini file, which resides in the usr/share/defaults/php/ path. Because Clear Linux OS is a Stateless operating system, you must create an optional configuration file to override the default values. Every time swupd updates the system, it overwrites changes to the /usr/share/defaults file structure. To save your configuration options through updates, you must create a PHP configuration file in a location that will not be overwritten. The recommended location is within the /etc file structure, which is why this tutorial creates a /etc/php.d directory.

The PHP-FPM configuration file is separate from the php.ini file used by PHP, however it has a similar default path restriction. Clear Linux OS installs the default php-fpm.conf file in /usr/share/defaults/php. This file with its default values is overwritten during each software update. However, PHP-FPM requires that the configuration file exist in that location, and, by design, does not read configuration options from a different path. This tutorial describes a solution to changing PHP-FPM configuration options in Clear Linux OS, by manually overriding the php-fpm.service unit in systemd to pass an explicit location to a custom php-fpm.conf file.

Prerequisites

  • Install Clear Linux OS on your host system.

  • Use swupd to install the php-basic bundle:

    sudo swupd bundle-add php-basic

Note

PHP does not require a web server for operation. If you need a web server, refer to LAMP Web Server for instructions on setting up a LAMP server, or use swupd to install nginx or similar.

Configure PHP

Important

This section does not describe configuration for the PHP-FPM service, which is described later in this guide.

This section creates a /etc/php.d directory for all PHP configuration files to work around the default path restriction.

  1. Create a php.ini file:

    sudo mkdir -p /etc/php.d
sudo touch /etc/php.d/my-php.ini

    This file can be edited with any of your specific configuration requirements, and will not be overwritten when swupd performs an update. The PHP configuration file documentation contains details about what you can set in this file.

  2. Verify the location of the PHP configuration files:

    php --ini

    You should see output like this:

    Configuration File (php.ini) Path: /usr/share/defaults/php/
Loaded Configuration File:         /usr/share/defaults/php/php.ini
Scan for additional .ini files in: /etc/php.d
Additional .ini files parsed:

    This output indicates that PHP will read the php.ini file from /usr/share/defaults/php and will then load any further configuration from .ini files in /etc/php.d/. The my-php.ini file in /etc/php.d contains your configuration details, and allows the defaults to be read from /usr/share/defaults/php/. Note that the my-php.ini file has not been parsed, because the file has no content at this point and is disregarded.

Install PHP extensions

PHP extensions are compiled libraries designed to enable specific functions in your PHP code. Clear Linux OS provides PHP extensions in the php-extras bundle.

  1. Install the bundle with swupd:

    sudo swupd bundle-add php-extras

  2. Find the list of extensions included in the php-extras bundle on the Clear Linux OS Store.

Enable PHP extensions

To enable an installed extension, you must add it to the php.ini file for the composer.

  1. Create the my-php.ini file using the directive to load the php-imagick extension:

    sudo echo "extension=imagick.so" >> /etc/php.d/my-php.ini

  2. Restart the php-fpm service for PHP to pick up the modification to the /etc/php.d/my-php.ini file:

    sudo systemctl restart php-fpm

  3. Verify that the imagick extension has been loaded by searching through the runtime list of loaded PHP Modules:

    php -m | grep imagick

Note

To enable an extension, you must install it, add it to the my-php.ini file, and restart the php-fpm service. However, some extensions may have configuration options, which will be documented by the extension maintainer. Add the options you need to the /etc/php.d/my-php.ini file as described in the extension’s documentation. Be sure to restart php-fpm after changing the file.

Configure PHP-FPM

The PHP-FPM configuration file is separate from the php.ini file used by PHP, however, it has a similar default path restriction. Follow the steps below to configure PHP-FPM.

  1. Copy the /usr/share/defaults/php/php-fpm.conf file to the /etc/php.d file:

    sudo cp /usr/share/defaults/php/php-fpm.conf /etc/php.d/php-fpm.conf

  2. Make changes to the php-fpm.conf file as needed. The FPM documentation has details on the configuration options available to PHP-FPM.

  3. Edit the systemd service unit file:

    sudo systemctl edit --full php-fpm.service

    This opens the php-fpm.service file for systemd in your editor.

  4. Change the ExecStart configuration to add the --fpm-config option to point to the custom location:

    [Unit]
Description=The PHP FastCGI Process Manager
After=syslog.target network.target

[Service]
Type=notify
PIDFile=/run/php-fpm.pid
ExecStart=/usr/sbin/php-fpm --nodaemonize --fpm-config /etc/php.d/php-fpm.conf
ExecReload=/bin/kill -USR2 $MAINPID
PrivateTmp=true

[Install]
WantedBy=multi-user.target

  5. Restart the service:

    sudo systemctl restart php-fpm.service

  6. Verify that the new path has been picked up:

    sudo systemctl status php-fpm.service

    You should see the new path in the output:

    ● php-fpm.service - The PHP FastCGI Process Manager
Loaded: loaded (/etc/systemd/system/php-fpm.service; enabled; vendor preset: disabled)
Active: active (running) since Thu 2019-10-17 13:19:34 PDT; 8min ago
Main PID: 14452 (php-fpm)
Status: "Processes active: 0, idle: 0, Requests: 0, slow: 0, Traffic: 0req/sec"
 Tasks: 1
Memory: 11.1M
CGroup: /system.slice/php-fpm.service
        └─14452 php-fpm: master process (/etc/php.d/php-fpm.conf)