Fixed nesting issue. (#895)

* Fixed nesting issue.
* Fixes #888 
Editorial changes for grammar and formatting.

Signed-off-by: MCamp859 <maryx.camp@intel.com>

* Moved Background section, made minor text edits

Signed-off-by: MCamp859 <maryx.camp@intel.com>
This commit is contained in:
Mary Camp
2019-11-15 15:34:46 -08:00
committed by michael vincerra
parent 3ec50a2cf8
commit 2258c90604
+161 -106
View File
@@ -1,26 +1,58 @@
.. _php:
PHP and PHP-FPM
***************
###############
This tutorial describes how to configure and use PHP and PHP-FPM on |CL-ATTR|. Although we specifically address PHP this tutorial can serve as a general guide for working with applications in the |CL| :ref:`stateless` environment.
This tutorial describes how to configure and use :abbr:`PHP (PHP: Hypertext Preprocessor)`
and :abbr:`PHP-FPM (PHP FastCGI Process Manager)` on |CL-ATTR|.
.. contents::
:local:
:depth: 1
Overview
********
Description
***********
`PHP (PHP:Hypertext Preprocessor)`_ 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 (FastCGI Process Manager)`_ is a PHP FastCGI implementation that controls process management, workers, and logging for PHP. The two applications work in conjunction but each has its own configuration.
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 |CL| :ref:`stateless`
environment.
Background
**********
By default, PHP looks for configuration settings in the :file:`php.ini` file,
which resides in the :file:`usr/share/defaults/php/` path. Because |CL| is a
:ref:`stateless` operating system, you must create an optional configuration
file to override the default values. Every time :command:`swupd` updates the
system, it overwrites changes to the :file:`/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 :file:`/etc` file structure, which is why this
tutorial creates a :file:`/etc/php.d` directory.
The PHP-FPM configuration file is separate from the :file:`php.ini` file used
by PHP, however it has a similar default path restriction. |CL| installs the
default :file:`php-fpm.conf` file in :file:`/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 |CL|, by manually overriding the php-fpm.service unit in systemd to pass
an explicit location to a custom :file:`php-fpm.conf` file.
Prerequisites
*************
* :ref:`Install <bare-metal-install-desktop>` |CL| on your host system
* Use :command:`swupd` to install the :file:`php-basic` bundle.
* :ref:`Install <bare-metal-install-desktop>` |CL| on your host system.
* Use :command:`swupd` to install the :file:`php-basic` bundle:
.. code-block:: bash
@@ -28,7 +60,10 @@ Prerequisites
.. note::
PHP does not require a web server for operation. Refer to :ref:`web-server-install` for instructions on setting up a :abbr:`LAMP (Linux, Apache\*, MySQL, PHP)` server, or use :command:`swupd` to install :file:`nginx` or similar if you need a web server.
PHP does not require a web server for operation. If you need a web
server, refer to :ref:`web-server-install` for instructions on setting
up a :abbr:`LAMP (Linux, Apache\*, MySQL, PHP)` server, or use
:command:`swupd` to install :file:`nginx` or similar.
Configure PHP
@@ -36,158 +71,178 @@ Configure PHP
.. important::
This section does not cover configuring the PHP-FPM service. There is a difference between the two configurations. This section is only looking at the PHP configuration directives, not those of PHP-FPM.
This section does **not** describe configuration for the PHP-FPM service, which is
described later in this guide.
This section creates a :file:`/etc/php.d` directory for all PHP configuration
files to work around the default path restriction.
#. Create a :file:`php.ini` file:
.. code-block:: bash
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 :command:`swupd` performs
an update. The `PHP configuration file`_ documentation contains details
about what you can set in this file.
#. Verify the location of the PHP configuration files:
.. code-block:: bash
php --ini
You should see output like this:
.. code-block:: console
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:
By default PHP looks for configuration settings in the :file:`php.ini` file, which resides in the :file:`usr/share/defaults/php/` path. Because |CL| is designed to be a :ref:`stateless` operating system, you must create an optional configuration file to override the default values. Every time :command:`swupd` updates the system it will overwrite changes to the :file:`/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 :file:`/etc` file structure. For PHP we will create a :file:`/etc/php.d` directory for all PHP config files.
Create a :file:`php.ini`.
.. code-block:: bash
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 :command:`swupd` performs an update. The `PHP configuration file`_ documentation has complete detail about what you can set in this file.
Verify the location of the PHP configuration files with the :command:`php --ini` command:
.. code-block:: bash
php --ini
You should see output like this
.. code-block:: console
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 :file:`/usr/share/defaults/php` and will then load any further configuration from :file:`.ini` files in :file:`/etc/php.d/`. We use the :file:`my-php.ini` file in :file:`/etc/php.d` for our specific needs, and allow the defaults to be read from :file:`/usr/share/defaults/php/`. Note that the :file:`my-php.ini` file has not been parsed yet -- this is because the file has no content at this point, and is disregarded.
This output indicates that PHP will read the :file:`php.ini` file from
:file:`/usr/share/defaults/php` and will then load any further
configuration from :file:`.ini` files in :file:`/etc/php.d/`. The
:file:`my-php.ini` file in :file:`/etc/php.d` contains your configuration
details, and allows the defaults to be read from
:file:`/usr/share/defaults/php/`. Note that the :file:`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. |CL| provides PHP extensions in the :file:`php-extras` bundle. Install the bundle with swupd:
PHP extensions are compiled libraries designed to enable specific functions in
your PHP code. |CL| provides PHP extensions in the :file:`php-extras` bundle.
.. code-block:: bash
#. Install the bundle with swupd:
sudo swupd bundle-add php-extras
.. code-block:: bash
Find the list of extensions included in the `php-extras`_ bundle on the |CL| `Store`_.
sudo swupd bundle-add php-extras
#. Find the list of extensions included in the `php-extras`_ bundle on the
|CL| `Store`_.
Enable PHP extensions
*********************
To enable an installed extension we need to add it to the :file:`php.ini` for the composer to use it.
To enable an installed extension, you must add it to the :file:`php.ini` file
for the composer.
Create the :file:`my-php.ini` file, with the directive to load the php-imagick extension
#. Create the :file:`my-php.ini` file using the directive to load the
php-imagick extension:
.. code-block:: bash
.. code-block:: bash
sudo echo "extension=imagick.so" >> /etc/php.d/my-php.ini
sudo echo "extension=imagick.so" >> /etc/php.d/my-php.ini
#. Restart the php-fpm service for PHP to pick up the modification to the
:file:`/etc/php.d/my-php.ini` file:
No further detail is required to load the extension, but you must restart the php-fpm service for PHP to pick up the modification to the :file:`/etc/php.d/my-php.ini` file.
.. code-block:: bash
.. code-block:: bash
sudo systemctl restart php-fpm
sudo systemctl restart php-fpm
#. Verify that the imagick extension has been loaded by searching through the
runtime list of loaded PHP Modules:
Verify that the imagick extension has been loaded by searching through the runtime list of loaded PHP Modules.
.. code-block:: bash
.. code-block:: bash
php -m | grep imagick
php -m | grep imagick
.. note::
To enable an extension, you must install it, add it to the :file:`my-php.ini` file, and restart the :file:`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 :file:`/etc/php.d/my-php.ini` file as described in the extension's documentation. Be sure to restart :file:`php-fpm` after changing the file.
To enable an extension, you must install it, add it to the
:file:`my-php.ini` file, and restart the :file:`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
:file:`/etc/php.d/my-php.ini` file as described in the extension's
documentation. Be sure to restart :file:`php-fpm` after changing the file.
Configure PHP-FPM
*****************
The PHP-FPM configuration file is separate from the :file:`php.ini` file used by PHP. |CL| installs the default :file:`php-fpm.conf` file in :file:`/usr/share/defaults/php` and this file will be overwritten with its default values during each software update. However, PHP-FPM requires that the configuration file exist in that location, and by design will not read configuration options from a different path.
One solution to changing PHP-FPM configuration options in |CL| is to manually override the php-fpm.service unit in systemd to pass an explicit location to a custom :file:`php-fpm.conf` file.
#. Copy the :file:`/usr/share/defaults/php/php-fpm.conf` file to the :file:`/etc/php.d`
.. code-block:: bash
sudo cp /usr/share/defaults/php/php-fpm.conf /etc/php.d/php-fpm.conf
#. Make changes to the :file:`php-fpm.conf` file as needed. The `FPM documentation`_ has detail on the configuration options available to PHP-FPM.
The PHP-FPM configuration file is separate from the :file:`php.ini` file used
by PHP, however, it has a similar default path restriction. Follow the steps
below to configure PHP-FPM.
#. Edit the systemd service unit file
#. Copy the :file:`/usr/share/defaults/php/php-fpm.conf` file to the
:file:`/etc/php.d` file:
.. code-block:: bash
.. code-block:: bash
sudo systemctl edit --full php-fpm.service
sudo cp /usr/share/defaults/php/php-fpm.conf /etc/php.d/php-fpm.conf
This will open the php-fpm.service file for systemd in your editor. Change the :command:`ExecStart` configuration to add the :command:`--fpm-config` option to point to the custom location.
#. Make changes to the :file:`php-fpm.conf` file as needed. The
`FPM documentation`_ has details on the configuration options available
to PHP-FPM.
.. code-block:: bash
#. Edit the systemd service unit file:
sudo systemctl edit --full php-fpm.service
.. code-block:: bash
.. code-block:: console
sudo systemctl edit --full php-fpm.service
[Unit]
Description=The PHP FastCGI Process Manager
After=syslog.target network.target
This opens the :file:`php-fpm.service` file for systemd in your editor.
[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
#. Change the :command:`ExecStart` configuration to add the
:command:`--fpm-config` option to point to the custom location:
[Install]
WantedBy=multi-user.target
.. code-block:: console
#. Restart the service
[Unit]
Description=The PHP FastCGI Process Manager
After=syslog.target network.target
.. code-block:: bash
[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
sudo systemctl restart php-fpm.service
[Install]
WantedBy=multi-user.target
#. Verify that the new path has been picked up
#. Restart the service:
.. code-block:: bash
.. code-block:: bash
sudo systemctl status php-fpm.service
sudo systemctl restart php-fpm.service
You should see the new path in the output
#. Verify that the new path has been picked up:
.. code-block:: console
.. code-block:: bash
● 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)
sudo systemctl status php-fpm.service
You should see the new path in the output:
.. code-block:: console
● 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)
.. _PHP language: https://www.php.net/
.. _PHP (PHP:Hypertext Preprocessor): https://www.php.net/
.. _PHP-FPM (FastCGI Process Manager): https://php-fpm.org/
.. _PHP-FPM: https://php-fpm.org/
.. _php-extras: https://clearlinux.org/software/bundle/php-extras