Make PHP-FPM configurable

.gitignore

@@ -38,15 +38,24 @@
 /cfg/percona-5.6/*.cnf
 /cfg/percona-5.7/*.cnf
 
-# Ignore custom PHP-FPM configs
+# Ignore custom PHP.ini configs
-/cfg/php-fpm-5.4/*.ini
+/cfg/php-ini-5.4/*.ini
-/cfg/php-fpm-5.5/*.ini
+/cfg/php-ini-5.5/*.ini
-/cfg/php-fpm-5.6/*.ini
+/cfg/php-ini-5.6/*.ini
-/cfg/php-fpm-7.0/*.ini
+/cfg/php-ini-7.0/*.ini
-/cfg/php-fpm-7.1/*.ini
+/cfg/php-ini-7.1/*.ini
-/cfg/php-fpm-7.2/*.ini
+/cfg/php-ini-7.2/*.ini
 #/cfg/hhvm-latest/*.ini
 
+# Ignore custom PHP-FPM configs
+/cfg/php-fpm-5.4/*.conf
+/cfg/php-fpm-5.5/*.conf
+/cfg/php-fpm-5.6/*.conf
+/cfg/php-fpm-7.0/*.conf
+/cfg/php-fpm-7.1/*.conf
+/cfg/php-fpm-7.2/*.conf
+#/cfg/hhvm-latest/*.conf
+
 # Ignore custom PHP-FPM modules
 /mod/php-fpm-5.4/*.so
 /mod/php-fpm-5.5/*.so

cfg/php-ini-5.6/xdebug.ini.off

@@ -0,0 +1,9 @@
+xdebug.default_enable=1
+xdebug.remote_enable=1
+xdebug.remote_handler=dbgp
+; port 9000 is used by php-fpm
+xdebug.remote_port=9000
+xdebug.remote_autostart=1
+; no need for remote host
+xdebug.remote_connect_back=1
+xdebug.idekey="PHPSTORM"

docker-compose.yml

@@ -139,8 +139,12 @@ services:
       - ${DEVILBOX_PATH}/backups:/shared/backups
 
       # Mount devilbox user-defined *.ini files in order
-      # to overwrite the default PHP configuration
+      # to overwrite the default PHP.ini configuration
-      - ${DEVILBOX_PATH}/cfg/php-fpm-${PHP_SERVER}:/etc/php-custom.d:ro
+      - ${DEVILBOX_PATH}/cfg/php-ini-${PHP_SERVER}:/etc/php-custom.d:ro
+
+      # Mount devilbox user-defined PHP-FPM *.conf files in order
+      # to overwrite the default PHP-FPM configuration
+      - ${DEVILBOX_PATH}/cfg/php-fpm-${PHP_SERVER}:/etc/php-fpm-custom.d:ro
 
       # Mount devilbox user-defined *.so files in order
       # to load custom PHP modules

docs/configuration-files/php-fpm-conf.rst

@@ -0,0 +1,178 @@
+.. _php_fpm_conf:
+
+************
+php-fpm.conf
+************
+
+
+``php-fpm.conf`` changes are global to all projects, but will only affect the currently selected
+PHP version.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+General
+=======
+
+You can set custom php-fpm.conf configuration options for each PHP version separately.
+These changes affect the PHP-FPM process itself, global as well as pool specific configuration can
+be set.
+
+.. note::
+    The default PHP-FPM pool is called ``www`` in case you want to make changes to it.
+
+
+See the directory structure for PHP-FPM configuration directories inside ``./cfg/`` directory:
+
+.. code-block:: bash
+
+    host> ls -l path/to/devilbox/cfg/ | grep 'php-fpm'
+
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-5.4/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-5.5/
+    drwxr-xr-x  2 cytopia cytopia 4096 Apr  3 22:04 php-fpm-5.6/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.0/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.1/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.2/
+
+Customization is achieved by placing a file into ``cfg/php-fpm-X.X/`` (where ``X.X`` stands for
+your PHP version).  The file must end by ``.conf`` in order to be sourced by the PHP-FPM server.
+
+Each of the PHP-FPM conf configuration directories already contain an example file:
+``devilbox-custom.conf-example``, that can simply be renamed to ``devilbox-custom.conf``.
+This file holds some example values that can be adjusted or commented out.
+
+In order for the changes to be applied, you will have to restart the Devilbox.
+
+.. seealso::
+    To find out about all available PHP-FPM directives, global or pool specific have a look
+    at its documentation: https://secure.php.net/manual/en/install.fpm.configuration.php
+
+
+Examples
+========
+
+Change rlimit core for master process for PHP 7.1
+-------------------------------------------------
+
+The following examples shows you how to change the
+`rlimit_core <https://secure.php.net/manual/en/install.fpm.configuration.php#rlimit-core-master>`_
+of PHP-FPM 7.1 master process to 100.
+
+.. code-block:: bash
+
+    # Navigate to the Devilbox directory
+    host> cd path/to/devilbox
+
+    # Navigate to PHP 7.1 config directory
+    host> cd cfg/php-fpm-7.1
+
+    # Create new conf file
+    host> touch rlimit.conf
+
+Now add the following content to the file:
+
+.. code-block:: ini
+    :name: rlimit.conf
+    :caption: rlimit.conf
+
+    [global]
+    rlimit_core = 100
+
+.. important:: Note the ``[global]`` section.
+
+In order to apply the changes you need to restart the Devilbox.
+
+
+Change child process on pool ``www`` for PHP 5.6
+------------------------------------------------
+
+The following examples shows you how to change the
+`pm <https://secure.php.net/manual/en/install.fpm.configuration.php#pm>`_,
+`pm.max_children <https://secure.php.net/manual/en/install.fpm.configuration.php#pm.max-chidlren>`_,
+`pm.start_servers <https://secure.php.net/manual/en/install.fpm.configuration.php#pm.start-servers>`_,
+`pm.min_spare_servers <https://secure.php.net/manual/en/install.fpm.configuration.php#pm.min-spare-servers>`_
+and
+`pm.max_spare_servers <https://secure.php.net/manual/en/install.fpm.configuration.php#pm.max-spare-servers>`_
+of PHP-FPM 5.6 on pool ``www``.
+
+.. code-block:: bash
+
+    # Navigate to the Devilbox directory
+    host> cd path/to/devilbox
+
+    # Navigate to PHP 5.6 config directory
+    host> cd cfg/php-fpm-5.6
+
+    # Create new conf file
+    host> touch www_server.conf
+
+Now add the following content to the file:
+
+.. code-block:: ini
+    :name: www_server.conf
+    :caption: www_server.conf
+
+    [www]
+    ; Pool config
+    pm = dynamic
+    pm.max_children = 10
+    pm.start_servers = 3
+    pm.min_spare_servers = 2
+    pm.max_spare_servers = 5
+
+.. important:: Note the ``[www]`` section.
+
+In order to apply the changes you need to restart the Devilbox.
+
+
+Set non-overwritable php.ini values for PHP 7.0
+-----------------------------------------------
+
+You can also set ``php.ini`` values that cannot be overwritten by ``php.ini`` or the ``ini_set()``
+function of PHP. This might be useful to make sure a specific value is enforced and will not be
+changed by some PHP frameworks on-the-fly.
+
+This is achieved by ``php_admin_flag`` and ``php_admin_value`` that are parsed directly to PHP-FPM.
+
+.. seealso:: https://secure.php.net/manual/en/install.fpm.configuration.php
+
+The following example will disable built-in PHP functions globally and non-overwriteable for PHP 7.0.
+
+.. code-block:: bash
+
+    # Navigate to the Devilbox directory
+    host> cd path/to/devilbox
+
+    # Navigate to PHP 7.0 config directory
+    host> cd cfg/php-fpm-7.0
+
+    # Create new conf file
+    host> touch admin.conf
+
+Now add the following content to the file:
+
+.. code-block:: ini
+    :name: admin.conf
+    :caption: admin.conf
+
+    [www]
+    php_admin_value[disable_functions] = link,symlink,popen,exec,system,shell_exec
+
+.. important:: Note the ``[www]`` section.
+
+.. important::
+    This kind of setting only has affects PHP files served through PHP-FPM, when you run php
+    on the command line, this setting will be ignored.
+
+.. important::
+    Be aware that none of your projects can use the above disabled functions anymore.
+    They will simply not exist for PHP 7.0 after that configuration took affect.
+
+In order to apply the changes you need to restart the Devilbox.
+
+
+

docs/configuration-files/php-ini.rst

@@ -22,16 +22,16 @@ See the directory structure for PHP configuration directories inside ``./cfg/``
 
 .. code-block:: bash
 
-    host> ls -l path/to/devilbox/cfg/ | grep 'php'
+    host> ls -l path/to/devilbox/cfg/ | grep 'php-ini'
 
-    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-5.4/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-5.4/
-    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-5.5/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-5.5/
-    drwxr-xr-x  2 cytopia cytopia 4096 Apr  3 22:04 php-fpm-5.6/
+    drwxr-xr-x  2 cytopia cytopia 4096 Apr  3 22:04 php-ini-5.6/
-    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.0/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.0/
-    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.1/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.1/
-    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.2/
+    drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.2/
 
-Customization is achieved by placing a file into ``cfg/php-fpm-X.X/`` (where ``X.X`` stands for
+Customization is achieved by placing a file into ``cfg/php-ini-X.X/`` (where ``X.X`` stands for
 your PHP version).  The file must end by ``.ini`` in order to be sourced by the PHP-FPM server.
 
 Each of the PHP ini configuration directories already contain an example file:
@@ -57,7 +57,7 @@ The following examples shows you how to change the
     host> cd path/to/devilbox
 
     # Navigate to PHP 7.1 config directory
-    host> cd cfg/php-fpm-7.1
+    host> cd cfg/php-ini-7.1
 
     # Create new ini file
     host> touch memory_limit.ini
@@ -89,7 +89,7 @@ of PHP 5.6.
     host> cd path/to/devilbox
 
     # Navigate to PHP 5.6 config directory
-    host> cd cfg/php-fpm-5.6
+    host> cd cfg/php-ini-5.6
 
     # Create new ini file
     host> touch timeouts.ini

docs/index.rst

@@ -127,6 +127,7 @@ host is ready to be served with your custom domain.
    configuration-files/apache-conf
    configuration-files/nginx-conf
    configuration-files/php-ini
+   configuration-files/php-fpm-conf
    configuration-files/my-cnf
    configuration-files/bashrc-sh