This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
plugins:phpswitcher [2017/02/28 19:54] nuxwin |
plugins:phpswitcher [2019/09/28 11:11] nuxwin |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | <markdown> | ||
- | # i-MSCP PhpSwitcher plugin | ||
- | </markdown> | ||
<WRAP center round important 60%> | <WRAP center round important 60%> | ||
- | **Be aware that this documentation is for the last available version. If you use an older version, you must refer to the README.md file inside the plugin archive.** | + | **Bear in mind that this documentation is for the lastest PhpSwitcher plugin version. If you use an older version, you must refer to the README.md file inside the plugin archive.** |
</WRAP> | </WRAP> | ||
<markdown> | <markdown> | ||
- | ## Introduction | + | # i-MSCP PhpSwitcher plugin v5.0.0 |
Provides additional PHP versions for customers. | Provides additional PHP versions for customers. | ||
Line 12: | Line 9: | ||
## Requirements | ## Requirements | ||
- | - i-MSCP Serie 1.3.x | + | - One of the [supported distributions](#supported_distributions) |
- | - Either the Fcgid or the PHP-FPM Apache2 httpd server implementation | + | - i-MSCP Serie ≥ 1.5.3 |
+ | - The Fcgid or the FPM i-MSCP httpd server implementation | ||
- | You can switch between HTTPD server implementations by running the following commands: | + | ### Supported distributions |
- | ``` | + | - Debian Jessie 8.x, Debian Stretch 9.x, Debian Buster 10.x |
- | # cd <path_to_your_imscp_archive> | + | - Ubuntu Xenial Xerus 16.04, Ubuntu Bionic Beaver 18.04 |
- | # perl imscp-autoinstall -dar httpd | + | - Devuan Jessie 1.x, Devuan ASCII 2.x |
- | ``` | + | |
+ | ### Recommendations | ||
- | Note that when asked, it is recommended to choose the `per_site` PHP configuration level. This allow your customers to | + | Recommended use of this plugin is with the i-MSCP FPM httpd server in **UDS** |
- | set different PHP versions for any of their domains (domain, subdomains...). | + | mode, and with the **per_site** PHP configuration level. |
## Installation | ## Installation | ||
- | 1. Be sure that all requirements as stated in the requirements section are met | + | 1. Be sure that all requirements are met |
- | 2. Upload the plugin through the plugin management interface | + | 2. Upload and install the plugin through the plugin management interface |
- | 3. Install the plugin through the plugin management interface | + | 3. Compile, install and/or register your PHP versions |
- | 4. Compile and install additional PHP versions (see below to know how) | + | |
- | 5. Register additional PHP versions through the PhpSwitcher administration interface (see below to know how) | + | |
## Update | ## Update | ||
- | 1. Read the UPDATE file inside the plugin archive | + | 1. Read the UPDATE.md file inside the plugin archive |
- | 2. Be sure that all requirements as stated in the requirements section are met | + | 2. Be sure that all requirements are met |
3. Upload the plugin through the plugin management interface | 3. Upload the plugin through the plugin management interface | ||
- | 4. Update the plugin list through the plugin management interface | + | 4. Compile, install and/or register your PHP versions |
- | 5. Re-compile your PHP versions if needed (see the doc/graceful_update.md file to know how) | + | |
- | ## Setup new PHP versions | + | ## Glossary |
- | At first, you must download, configure, compile and install the PHP versions that you want make available for your | + | In the documentation below, the following variables are used: |
- | customers. For this, you can either do the job manually, or use the PHP compiler (recommended) that is shipped with this | + | |
- | plugin. | + | |
- | If you choose to compile your additional PHP versions manually, you must not forget to build them with the `cgi` SAPI, | + | - %version% : One of available PHP version such as 7.1, 7.2, 7.3, 7.4 ... |
- | even if you don't use the Fcgid Apache2 httpd server implementation. Indeed the PHP FastCGI binary is always required | + | - %ymd% : The date of the day such as 20190831 |
- | by this plugin. You must also not forgot to update the patterns inside the plugin configuration file. | + | - %installdir% : Installation directory such as /opt/phpswitcher/20170306 |
- | Be aware that configuring multiple PHP-FPM instances requires to name your binaries with unique names. This is | + | ## Compiled PHP versions |
- | needed to avoid conflict with PHP-FPM master processes. If you don't have any idea of what we are talking about, it is | + | |
- | best for you to simply use the PHP compiler which will do all that work for you. | + | |
- | ### PHP compiler | + | This plugin provides the `php_compiler.pl` script that can, compile and install |
+ | additional PHP versions in one step. It can also register them in the | ||
+ | Phpswitcher plugin. | ||
- | The PHP compiler is a Perl script that downloads, configures, compiles and installs additional PHP versions in one step, | + | For example, if you want to compile and install all additional PHP versions, you |
- | without any human intervention. The script is located in the PhpSwitcher/PhpCompiler directory. | + | can execute the following command: |
- | + | ||
- | For instance, if you want to setup the PHP 7.1 version, you can run the following command: | + | |
- | ``` | + | ```shell |
- | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl 7.1 | + | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl |
``` | ``` | ||
- | or if you want to setup any other PHP version, or all supported by this script, you can run it as follow: | + | or if you want to install specific PHP versions: |
- | ``` | + | ```shell |
- | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl %version% | + | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl %version% %version% |
``` | ``` | ||
- | where the `%version%` parameter can be one of the available PHP version or `all` for all available PHP versions. Note | + | You can also automatically register the PHP versions in the PhpSwitcher plugin |
- | that the `%version%` parameter can be used more than once. For instance | + | by passing the `--register` option. For instance: |
- | ``` | + | ```shell |
- | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl 5.5 5.6 7.0 7.1 | + | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl --register %version% %version% |
``` | ``` | ||
- | #### Supported PHP versions | + | Doing this avoid the need to register them manually through the PhpSwitcher |
+ | plugin administration interface. | ||
- | PHP versions provided by the compiler depend on the httpd server implementation in use. For instance, older PHP versions | + | ### Supported PHP versions |
- | such as PHP 4.4 and PHP 5.2 don't provide the `fpm` SAPI, and therefore, the compiler doesn't provides these versions | + | |
- | when it detects that you use the PHP-FPM Apache2 httpd server implementation. | + | |
- | If you use the Fcgid Apache2 httpd server implementation, the following PHP versions are supported: `4.4`, `5.2`, `5.3`, | + | The supported PHP versions are the last that were available when this plugin |
- | `5.4`, `5.5`, `5.6`, `7.0` and `7.1`. | + | version has been released. This means that by default, the versions provided by |
+ | the `php_compiler.pl` script can be lower than the last that were released on | ||
+ | the PHP site. | ||
- | If you use the PHP-FPM Apache2 httpd server implementation, the following PHP versions are supported: `5.3`, `5.4`, | + | Supported PHP versions are: `5.3` up-to `7.4` |
- | `5.5`, `5.6`, `7.0` and `7.1`. | + | |
- | Note that the supported PHP versions are the last that were available when this plugin version has been released. This | + | #### Forcing the `php_compiler.pl` script to download latest PHP sources |
- | means that by default, the versions provided by the compiler can be lower than the last released on the PHP site. In | + | |
- | such case, you can try to use the `--force-last` command line option that tells the PHP compiler to download the last | + | |
- | released versions. However, you must be aware that the PHP compiler could fail to apply the needed patches on these | + | |
- | versions. In such a case, you should report us the failure message by creating an issue on our bug tracker. | + | |
- | #### Building and installation directories | + | You can ask the `php_compiler.pl` script to download latest PHP sources by |
+ | passing the `--force-last` option. However, you must bear in mind that some | ||
+ | patches might not longer apply, in which case you should report us the failure | ||
+ | message by creating a new issue on our bug tracker. | ||
- | By default, the PHP compiler will build new PHP versions into the /usr/local/src/phpswitcher/php%version% directory and | + | ### Download directory |
- | install them in the /opt/phpswitcher/php%version% directory but you can change this behavior using command line options. | + | |
- | To get list of all available command line options, you can run: | + | By default, the PHP sources are downloaded in the `/usr/local/src/phpswitcher` |
+ | directory. You can override the default download directory by passing the | ||
+ | `--download-dir` option to the `php_compiler.pl` script. | ||
- | ``` | + | ### Build directory |
- | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl --help | + | |
- | ``` | + | |
- | + | ||
- | #### SSL support for PHP 4.4 | + | |
- | PHP 4.4 is is built against a self-compiled OpenSSL library (openssl-0.9.8) that is installed in the | + | By default, the compiled PHP versions are build in the |
- | /opt/phpswitcher/openssl/openssl-0.9.8zh directory. | + | `/usr/local/src/phpswitcher/php%version%` directory. You can override the |
+ | default build directory by passing the `--build-dir` option to the | ||
+ | `php_compiler.pl` script. | ||
- | #### SSL support for PHP >= 4.4 < 7.0 | + | ### Installation directory |
- | For systems on which OpenSSL library is greater than 1.1.0, PHP versions greater than 4.4 but older than 7.0 are built | + | By default, the compiled PHP versions are installed in the |
- | against a self-compiled OpenSSL library (1.0.2k) that is installed in the /opt/phpswitcher/openssl/openssl-1.0.2k | + | `/opt/phpswitcher/%ymd%/php%version%` directory. You can override the |
- | directory. | + | default installation directory by passing the `--install-dir` option to the |
+ | `php_compiler.pl` script. | ||
- | #### Changes made on PHP versions | + | ### Changes made on PHP sources |
- | PHP versions provided by the PHP compiler are almost identical to those which are provided by the Debian team. For each | + | A set of patches is applied on PHP sources before configuring them. The patches |
- | PHP version, a set of patches is applied on upstream source before compiling them. The patches include the following | + | include the following changes: |
- | changes: | + | |
- Multiarch support | - Multiarch support | ||
- | - Usage of libtool as provided by Debian package instead of the bundled version (when possible) | + | - Support for latest OpenSSL 1.1.x version |
- | - Any patch that fix a bug, a security issue or an FTBFS issue | + | - Any patch that fix a bug, a security issue or a FTBFS issue |
- | Majority of the applied patches were pulled from the Debian PHP source packages and adjusted when needed, while some | + | Most of the patches were pulled from the Debian PHP team git repository and |
- | other were created to resolve FTBFS issues or adjust configuration. Patches which were not pulled from Debian PHP source | + | modified when needed, while some other were created to resolve FTBFS issues. |
- | packages are prefixed with the `nxw_` prefix. | + | Patches which were not pulled from Debian PHP team git repository have the |
+ | `nxw-` prefix in their names. | ||
- | #### Enabled PHP extensions | + | ### PHP extensions |
- | Enabled PHP extensions are the same that are enabled in PHP versions provided by Debian team. However, it should be | + | PHP extensions are the same that are provided by PHP versions from the Debian |
- | noted that the db extension is disabled for PHP versions older than 5.3.x due to incompatibility with the Berkeley | + | PHP team. Most are compiled as shared module. |
- | Database libraries versions that are shipped with Debian >= Wheezy and Ubuntu >= Precise. | + | |
- | Several extensions are compiled as shared module. See below for more details. | + | ### PHP build dependencies (since version 5.0.0) |
- | #### Build dependencies | + | The `php_compiler.pl` script install the build dependencies for you by creating |
+ | a specific Debian dependency package for each PHP version. These packages are | ||
+ | purged after a successfull build. | ||
- | The PHP compiler installs the build dependencies for you. However, if a package isn't available, it will go ahead and | + | ### PHP runtime dependencies (since version 5.0.0) |
- | the PHP configuration process will fail. | + | |
- | #### Parallel Execution (GNU make) | + | The `php_compiler.pl` script install the PHP runtime dependencies for you by |
+ | creating a specific Debian runtime dependency package for each PHP version. | ||
+ | These packages are purged only when you uninstall the plugin. | ||
- | For faster compilation, the parallel execution feature provided by GNU make is enabled whenever possible. This feature | + | ### Build environment (since version 5.0.0) |
- | allows to execute many recipes simultaneously. By default, the number of parallel jobs is set according the number of | + | |
- | CPU core available on your system. You can still set the value manually using the `--parallel-jobs` command line option | + | |
- | as follow: | + | |
- | ``` | + | Build perations are performed in a chroot environment by default. This allows to |
- | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl --parallel-jobs 1 7.1 | + | setup a clean build environment, and this also avoid to pollute the production |
- | ``` | + | system with PHP build dependencies. |
+ | |||
+ | You can switch back to the historical behavior by passing the `--no-chroot` | ||
+ | option to the `php_compiler.pl` script. | ||
+ | |||
+ | ### Parallel Execution (GNU make) | ||
+ | |||
+ | For faster compilation, the parallel execution feature provided by GNU make is | ||
+ | enabled. This feature allows to execute many recipes simultaneously. By default, | ||
+ | the number of parallel jobs is set according the number of CPU core available on | ||
+ | your system + 1. You can still set the value manually by passing the | ||
+ | `--parallel-jobs` option to the `php_compiler.pl` script. | ||
- | Here, only one recipe will be run at time. | + | See [Parallel Execution](https://www.gnu.org/software/make/manual/html_node/Parallel.html) |
+ | for further details about this feature. | ||
- | See https://www.gnu.org/software/make/manual/html_node/Parallel.html for further details about this feature. | + | ### Installation layout |
- | #### Installation layout | + | For all PHP versions provided by the PHP compiler, the following installation |
+ | layout applies: | ||
- | First, you must note that in all cases, we build the following SAPIs: `cli`, `cgi` and `fpm`. This allows switching on | + | #### Common to all PHP SAPIs |
- | other httpd server implementation without having to rebuild all PHP versions. This is also needed to build static | + | |
- | phpinfo files (we always use the PHP FastCGI binary to build static phpinfo files). | + | |
- | For all versions provided by the PHP compiler, the following installation layout applies: | + | - Main php.ini file: /opt/phpswitcher/%ymd%/php%version%/etc/php/php.ini |
+ | - Additional *.ini files: /opt/phpswitcher/%ymd%/php%version%/etc/php/conf.d | ||
- | #### Common to cgi and fpm SAPIs | + | #### PHP cli SAPI |
- | - PHP CLI binary: /opt/phpswitcher/php%version%/bin/php | + | - PHP CLI binary: /opt/phpswitcher/%ymd%/php%version%/bin/php |
- | - Master php.ini file: /opt/phpswitcher/php%version%/etc/php/php.ini | + | |
- | - Additional *.ini files: /opt/phpswitcher/php%version%/etc/php/conf.d | + | |
- | #### Specific to cgi SAPI | + | #### PHP cgi SAPI |
- | - PHP FastCGI binary: /opt/phpswitcher/php%version%/bin/php-cgi | + | - PHP FastCGI binary: /opt/phpswitcher/%ymd%/php%version%/bin/php-cgi |
- | - Customer php.ini files: /var/www/fcgi/%domain%/php%version%/php.ini | + | - User php.ini files: /var/www/fcgi/%domain%/php%version%/php.ini |
- | #### Specific to fpm SAPI | + | #### PHP fpm SAPI |
- | - PHP-FPM binary: /opt/phpswitcher/php%version%/sbin/psw%version%-fpm | + | - PHP-FPM binary: /opt/phpswitcher/%ymd%/php%version%/sbin/psw%version%-fpm |
- | - PHP-FPM configuration file: /opt/phpswitcher/php%Version%/etc/php-fpm.conf | + | - PHP-FPM configuration file: /opt/phpswitcher/%ymd%/php%Version%/etc/php-fpm.conf |
- | - PHP-FPM checkconf script: /usr/local/lib/phpswitcher/psw%version%-fpm-checkconf | + | |
- PHP-FPM instance pid file: /var/run/phpswitcher/psw%version%-fpm.pid | - PHP-FPM instance pid file: /var/run/phpswitcher/psw%version%-fpm.pid | ||
- PHP-FPM log file: /var/log/phpswitcher/psw%version%-fpm.log | - PHP-FPM log file: /var/log/phpswitcher/psw%version%-fpm.log | ||
- | - PHP-FPM pool configuration files: /opt/phpswitcher/php%Version%/etc/php-fpm.d/%domain%.conf | + | - PHP-FPM pool configuration files: /opt/phpswitcher/%ymd%/php%Version%/etc/php-fpm.d/%domain%.conf |
- PHP-FPM reopenlogs script: /usr/local/lib/phpswitcher/psw%version%-fpm-reopenlogs | - PHP-FPM reopenlogs script: /usr/local/lib/phpswitcher/psw%version%-fpm-reopenlogs | ||
- PHP-FPM sysvinit script: /etc/init.d/psw%version%-fpm | - PHP-FPM sysvinit script: /etc/init.d/psw%version%-fpm | ||
- PHP-FPM tmpfile: /etc/tmpfiles.d/psw%version%-fpm.conf | - PHP-FPM tmpfile: /etc/tmpfiles.d/psw%version%-fpm.conf | ||
- | As you can see, we use a specific naming convention for PHP-FPM. This is needed to avoid conflict between different | + | As you can see, there is a specific naming convention for PHP-FPM. This is needed |
- | PHP-FPM installations. | + | to avoid conflict with packaged PHP versions. |
- | Note that the `psw` suffix stands for `PhpSwitcher`. | + | Note that the `psw` prefix stands for `PhpSwitcher`. |
- | ## Configuration | + | #### Static paths (since version 5.0.0) |
- | ### PHP configuration | + | For convenience, the `php_compiler.pl` script also creates symlinks to the |
+ | installation directories of various PHP versions, which allows the sysadmin | ||
+ | to access the PHP binaries always by the same paths (e.g. in CRONTAB(5) files). | ||
- | This section is only relevant if you installed additional PHP versions with the PHP compiler. | + | These symlinks are created in the `/opt/phpswitcher/static` directory, either at |
+ | the installation stage, or at the registration stage. If you do not want these | ||
+ | symlinks, you can pass the `--no-static-paths` option to the `php_compiler.pl` | ||
+ | script. | ||
- | First, it is important to note that it is useless to edit any PHP configuration file located under the /etc/php5 | + | Note that when the symlinks are available, they will be used for registration |
- | directory for a PHP version that has been built by the PHP compiler. Indeed, the files located under that directory are | + | process in place of the default paths. |
- | only relevant for the PHP versions provided by your distribution. | + | |
- | For the same reasons, it is useless to try to enable/disable a PHP module using the command line tools | + | ## Packaged PHP versions (since version 5.0.0) |
- | php5enmod/php5dismod that are provided by your distribution. Those tools only operate on the .ini files that are | + | |
- | provided by your distribution. | + | |
- | #### PEAR packages | + | The `php_compiler.pl` script also make possible to register packaged PHP |
+ | versions in the PhpSwitcher plugin. Packaged PHP versions are either those | ||
+ | provided by the Debian PHP team, or the Ondřej Surý repositories. To register | ||
+ | the packaged PHP versions, you need to execute the following command: | ||
- | Each PHP version has its own PEAR that is installed under the `/opt/phpswitcher/php%version%/share/pear` directory. | + | ```shell |
- | Please don't try to include PEAR library from another location without knowning what you are doing. Doing this could | + | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl --register --packaged |
- | lead to serious problems. | + | ``` |
- | + | ||
- | If you need to install additional PEAR packages, you must install them using the `pear` command provided by the PHP | + | |
- | version for which you want act. For instance: | + | |
+ | When the `--packaged` option is passed-in, the `php_compiler.pl` script will | ||
+ | favor registration of packaged PHP versions rather than compiled ones. In other | ||
+ | words, for a given PHP version, the PHP compiler will fallback to a compiled PHP | ||
+ | version only if there is no packaged PHP version available. | ||
+ | |||
+ | If you only want work with packaged PHP versions, you can also pass the | ||
+ | `--packaged-only` option: | ||
+ | |||
+ | ```shell | ||
+ | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl --register --packaged --packaged-only | ||
``` | ``` | ||
- | # /opt/phpswitcher/php5.6/bin/pear install Net_SMTP | + | |
+ | With this option, only the packaged PHP versions will be considered, regardless | ||
+ | of their availalibity. If no packaged PHP version is available, nothing will | ||
+ | happend, that is, no fallback to a compiled PHP version will be made. | ||
+ | |||
+ | You can of course still specify the PHP versions for which you want to operate | ||
+ | on, and you can also change the default directory, where the PHP compiler is | ||
+ | looking for the compiled PHP versions, by passing the `--install-dir` option. | ||
+ | For instance: | ||
+ | |||
+ | ```shell | ||
+ | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl --register --packaged --install-dir /opt/my/install/directory 7.1 7.3 7.4 | ||
``` | ``` | ||
- | will install the `Net_SMTP` PEAR package into the `/opt/phpswitcher/php5.6/share/pear` directory. Thus, that package | + | Note that for a packaged PHP version, the plugin backend will skip generation of |
- | will be available for customers that use the PHP 5.6 version. | + | most configuration files as those are already provided by the package. You need |
+ | also remember that for a packaged PHP version, the FPM service name is | ||
+ | `php%version%-fpm` instead of `psw%version%-fpm`. | ||
- | #### PHP extensions (modules) | + | Finally, you need keep in mind that for the `php_compiler.pl` script, the |
+ | packaged PHP versions are considered only when all requirements are met, that | ||
+ | is, when for a given PHP version, the CGI sapi, FPM sapi, and the PEAR | ||
+ | distribution are all installed on the system. For instance, if you want to | ||
+ | register the PHP 7.3 packaged version, you must first make sure that all | ||
+ | required distribution packages are installed: | ||
- | For convenience, most of PHP extensions are compiled as shared modules. When installing a new PHP version, the PHP | + | ```shell |
- | compiler create a specific INI file that enable most of available PHP extensions. By default, this file is located at | + | # apt-get update |
- | `/opt/phpswitcher/php%version%/etc/php/conf.d/modules.ini`. | + | # apt-get install php7.3-cli php7.3-cgi php7.3-fpm php-pear |
+ | ``` | ||
- | Here, a single INI file is used for ease. This is not like with PHP Debian packages where an INI file is created for | + | ## PEAR packages |
- | each module. To enable/disable a specific module, you must just edit the INI file and then, restart the Web server or | + | |
- | related PHP-FPM instance, according the httpd server implementation you use. | + | |
- | #### Pecl extensions | + | ### For a compiled PHP version |
- | If you want install a Pecl extension for a specific PHP version, you must not use the `pecl` or `phpize` commands that | + | Each compiled PHP version comes with its own PEAR distribution which is |
- | are shipped with your distribution. Instead, you must use the commands that are provided in the directory of the PHP | + | installed under the `/opt/phpswitcher/%ymd%/php%version%/share/pear` directory. |
- | version for which you want act. | + | |
- | For instance, if you want install the `FileInfo` Pecl extension that was not yet integrated in PHP 5.2, you must process | + | You shouldn't try to include a PEAR library from another location without |
- | as follow: | + | knowing what you are doing because doing this could lead to an unexpected |
+ | behavior. | ||
+ | |||
+ | If you want to install additional PEAR packages, you must install them using | ||
+ | the `pear` command provided by the compiled PHP version for which you want act. | ||
+ | For instance: | ||
- | ``` | + | ```shell |
- | # /opt/phpswitcher/php5.2/bin/pecl install fileinfo | + | # cd /opt/phpswitcher/%ymd%/php%Version%/bin |
- | # echo 'extension = fileinfo.so' >> /opt/phpswitcher/php5.2/etc/php/conf.d/modules.ini | + | # ./pear install Net_SMTP |
``` | ``` | ||
- | #### APCu extension | + | ### For a packaged PHP version |
- | APCu is a userland cache stripped of opcode caching that comes in replacement of the APC extension. It is a good | + | For a packaged PHP version, you just need to install the distribution package: |
- | complement for PHP versions >= PHP 5.5 that already provide an opcode cache through the OPcache extension. | + | |
- | + | ||
- | If you want install this extension for one of your PHP version, you can do as follow | + | |
+ | ```shell | ||
+ | # apt-get update | ||
+ | # apt-get install php-net-smtp | ||
``` | ``` | ||
- | # /opt/phpswitcher/php%version%/bin/pecl install channel://pecl.php.net/apcu-%apcu_version% | + | |
- | # PHP_EXT_DIR=$(/opt/phpswitcher/php%version%/bin/php-config --extension-dir) | + | or if there is none, you can process as follows: |
- | # echo "extension = $PHP_EXT_DIR/apcu.so" > /opt/phpswitcher/php%version%/etc/php/conf.d/02_apcu.ini | + | |
+ | ```shell | ||
+ | # /usr/bin/pear install Net_SMTP | ||
``` | ``` | ||
- | then, if you use the Fcgid Apache2 httpd server implementation | + | ## PHP extensions |
- | ``` | + | ### For a compiled PHP version |
- | # service apache2 restart | + | |
+ | For convenience, most of PHP extensions are compiled as shared modules. When a | ||
+ | compiled PHP version is being installed, a specific INI file that enable most of | ||
+ | available PHP extensions is created. By default, this file is located at | ||
+ | `/opt/phpswitcher/%ymd%/php%version%/etc/php/conf.d/modules.ini`. | ||
+ | |||
+ | Here, a single INI file is involved. This is not like with a packaged PHP | ||
+ | version where there is one INI file per extension. | ||
+ | |||
+ | To enable/disable a specific PHP extension, you must just edit the modules.ini | ||
+ | INI file and once done, restart the Web server or PHP-FPM instance, depending on | ||
+ | the i-MSCP httpd server implementation in use. | ||
+ | |||
+ | ### For a packaged PHP version | ||
+ | |||
+ | For a packaged PHP version, you can enable/disable the PHP extensions using the | ||
+ | phpenmod/phpdismod command provided by your distribution. | ||
+ | |||
+ | ## PECL extensions | ||
+ | |||
+ | ### For a compiled PHP version | ||
+ | |||
+ | If you want to install a PECL extension, you must not invoke the `pecl` or | ||
+ | `phpize` commands that are provided by your distribution. Instead, you must | ||
+ | invoke those that are provided by the compiled PHP version for which you want | ||
+ | act. | ||
+ | |||
+ | For instance, if you want to install the `Imagick` PECL extension you can | ||
+ | process as follows: | ||
+ | |||
+ | ```shell | ||
+ | # apt-get update | ||
+ | # apt-get -y install libmagickwand-dev imagemagick | ||
+ | # /opt/phpswitcher/%ymd%/php%version%/bin/pecl install imagick | ||
+ | # echo 'extension = imagick.so' > /opt/phpswitcher/%ymd%/php%version%/etc/php/conf.d/imagick.ini | ||
``` | ``` | ||
- | else | + | Finally, you must restart the Web server or PHP-FPM instance, depending on the |
+ | i-MSCP httpd server implementation in use. | ||
- | ``` | + | ### For a packaged PHP version |
- | # service psw%version%-fpm restart | + | |
+ | For a packaged PHP version, you just need to install the distribution package: | ||
+ | |||
+ | ```shell | ||
+ | # apt-get update | ||
+ | # apt-get install php%version%-imagick | ||
+ | ``` | ||
+ | |||
+ | or if there is none, you can process as follows: | ||
+ | |||
+ | ```shell | ||
+ | # apt-get update | ||
+ | # apt-get -y install php%version%-dev libmagickwand-dev imagemagick | ||
+ | # update-alternatives --set php /usr/bin/php%version% | ||
+ | # update-alternatives --set phpize /usr/bin/phpize%version% | ||
+ | # update-alternatives --set php-config /usr/bin/php-config%version% | ||
+ | # pecl install imagick | ||
+ | # echo 'extension = imagick.so' > /etc/php/%version%/mods-available/imagick.ini | ||
+ | # phpenmod -v %version% imagick | ||
``` | ``` | ||
- | Note that the APcu version to install depends on your PHP version | + | Finally, you must restart the Web server, or PHP-FPM instance, depending on the |
+ | i-MSCP httpd server implementation in use. | ||
- | - 4.0.x for PHP 5.5.x and 5.6.x | + | You can uninstall the PECL extension by following the same procedure, replacing |
- | - 5.1.x for PHP 7.0.x and PHP 7.1.x | + | the pecl `install` command by the pecl `uninstall` command. However, you'll have |
+ | to disable the module first. For instance: | ||
- | #### IonCube loader | + | ```shell |
+ | # update-alternatives --set php /usr/bin/php%version% | ||
+ | # update-alternatives --set phpize /usr/bin/phpize%version% | ||
+ | # update-alternatives --set php-config /usr/bin/php-config%version% | ||
+ | # phpdismod -v %version% imagick | ||
+ | # rm /etc/php/%version%/mods-available/imagick.ini | ||
+ | # pecl uninstall imagick | ||
+ | ``` | ||
- | If you want install this extension for one of your PHP version, you can do as follow: | + | **WARNING:** In both cases, you must not forget to reset the various |
+ | alternatives to their previous values, as required by i-MSCP core: | ||
+ | ```shell | ||
+ | # PHP_VERSION=$(egrep '^PHP_VERSION' /etc/imscp/php/php.data | sed -e 's/PHP_VERSION\s\+=\s\+\(.*\)/\1/g') | ||
+ | # update-alternatives --set php /usr/bin/php"$PHP_VERSION" | ||
+ | # update-alternatives --set phpize /usr/bin/phpize"$PHP_VERSION" | ||
+ | # update-alternatives --set php-config /usr/bin/php-config"$PHP_VERSION" | ||
``` | ``` | ||
+ | |||
+ | ## IonCube loader | ||
+ | |||
+ | If you want to install this extension for one of your PHP version, you can | ||
+ | process as follows (example for the x86-64 architecture): | ||
+ | |||
+ | ### For a compiled PHP version | ||
+ | |||
+ | ```shell | ||
# cd /usr/local/src | # cd /usr/local/src | ||
# wget http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz | # wget http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz | ||
# tar -xzf ioncube_loaders_lin_x86-64.tar.gz | # tar -xzf ioncube_loaders_lin_x86-64.tar.gz | ||
# cd ioncube | # cd ioncube | ||
- | # PHP_EXT_DIR=$(/opt/phpswitcher/php%version%/bin/php-config --extension-dir) | + | # PHP_EXT_DIR=$(/opt/phpswitcher/%ymd%/php%version%/bin/php-config --extension-dir) |
# cp ioncube_loader_lin_%version%.so $PHP_EXT_DIR/ioncube.so | # cp ioncube_loader_lin_%version%.so $PHP_EXT_DIR/ioncube.so | ||
- | # echo "zend_extension = $PHP_EXT_DIR/ioncube.so" > /opt/phpswitcher/php%version%/etc/php/conf.d/01_ioncube.ini | + | # echo "zend_extension = $PHP_EXT_DIR/ioncube.so" > /opt/phpswitcher/%ymd%/php%version%/etc/php/conf.d/01_ioncube.ini |
``` | ``` | ||
- | then, if you use the Fcgid Apache2 httpd server implementation | + | Finally, you must restart the Web server or PHP-FPM instance, depending on the |
+ | i-MSCP httpd server implementation in use. | ||
- | ``` | + | ### For a packaged PHP version |
- | # service apache2 restart | + | |
+ | ```shell | ||
+ | # apt-get update | ||
+ | # apt-get install php%version%-dev | ||
+ | # cd /usr/local/src | ||
+ | # wget http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz | ||
+ | # tar -xzf ioncube_loaders_lin_x86-64.tar.gz | ||
+ | # cd ioncube | ||
+ | # PHP_EXT_DIR=$(php-config%version% --extension-dir) | ||
+ | # cp ioncube_loader_lin_%version%.so "$PHP_EXT_DIR"/ioncube.so | ||
+ | # echo -e "; priority=01\nzend_extension = $PHP_EXT_DIR"/ioncube.so" >> /etc/php/%version%/mods-available/ioncube.ini | ||
+ | # phpenmod -v %version% ioncube | ||
``` | ``` | ||
- | else | + | Finally, you must restart the Web server or PHP-FPM instance, depending on the |
+ | i-MSCP httpd server implementation in use. | ||
- | ``` | + | ## PHP configuration information (phpinfo) |
- | # service psw%version%-fpm restart | + | |
- | ``` | + | |
- | Once done, you can ensure that all is ok by running the following command: | + | This feature allows the customers to access the configuration information of |
+ | various PHP versions through their own PhpSwitcher interface. This feature can | ||
+ | be disabled by editing the plugin configuration file, and by triggering a plugin | ||
+ | list update through the plugin management interface. | ||
- | ``` | + | ### With the i-MSCP FPM httpd server implementation |
- | # /opt/phpswitcher/php4.4/bin/php -v | + | |
- | ``` | + | |
- | which should give a similar result: | + | The plugin make use of the default `www.conf` FPM pool of each PHP version to |
+ | serve the PHP configuration information at runtime. | ||
- | ``` | + | ### With the i-MSCP Fcgid httpd server implementation |
- | PHP 4.4.9 (cgi-fcgi) (built: May 3 2015 14:16:01) | + | |
- | Copyright (c) 1997-2008 The PHP Group | + | |
- | Zend Engine v1.3.0, Copyright (c) 1998-2004 Zend Technologies | + | |
- | with the ionCube PHP Loader v5.0.2, Copyright (c) 2002-2015, by ionCube Ltd. | + | |
- | ``` | + | |
- | Note that in the example above, we assume an amd64 architecture (64 bits OS). | + | The plugin generate a static PHP info file for each PHP version. Because the |
+ | information are static, you must not forget to re-generate them each time you do | ||
+ | a configuration change for a specific PHP version (e.g. when you enable or | ||
+ | disable a PHP/PECL extension). This task can be done through the PhpSwitcher | ||
+ | administration interface, for each PHP version. | ||
- | ### PHP info files | + | ## Registration of new PHP versions |
- | For each PHP version that is registered through the PhpSwitcher administration interface (see below), a static phpinfo | + | You can register new PHP version either using the `php_compiler.pl` script |
- | file is generated, which allows your customers to get PHP information via their own PhpSwitcher interface. This feature, | + | (recommended), or manually through the PhpSwitcher administration interface. |
- | if not desired, can be disabled by editing the plugin configuration file and by updating the plugin list through the | + | |
- | plugin management interface. | + | |
- | Be aware that because the phpinfo files are static, you must re-generate them each time you made a configuration change | + | ### Registration through the `php_compiler.pl` script |
- | for a specific PHP version (e.g. when you enable or disable a PHP/Pecl extension). This task can be done through the | + | |
- | PhpSwitcher administration interface. Be also aware that because those files are static, some information such as memory | + | |
- | could not matches with those that you have set for your customers (e.g. using the PHP editor provided by i-MSCP). | + | |
- | ### Registering a new PHP version in PhpSwitcher | + | To register a PHP version, you need to execute the following command: |
- | Once you have installed a new PHP version, you need to register it into the PhpSwitcher plugin to make it available for | + | ```shell |
- | your customers. For instance: | + | # perl /var/www/imscp/gui/plugins/PhpSwitcher/PhpCompiler/php_compiler.pl --register --install-dir %installdir% |
+ | ``` | ||
- | 1. Login into the panel as administrator and go to the PhpSwitcher administration interface (settings section) | + | See the previous documentation sections for all possible options, notably those |
- | 2. Create a new PHP version as follow (example for PHP 7.1): | + | which apply to packaged PHP versions. |
- | #### PHP Common settings (Required) | + | ### Registration through the PhpSwitcher administration interface |
- | - Path to PEAR directory: /opt/phpswitcher/php7.1/share/pear | + | |
- | #### PHP FastCGI settings (Required) | + | 1. Login into the panel as administrator and go to the PhpSwitcher |
- | - Path to binary: /opt/phpswitcher/php7.1/bin/php-cgi | + | administration interface (settings section) |
+ | 2. Setup your new PHP versions as follows: | ||
- | #### PHP-FPM settings (Only if you use PHP-FPM httpd server implementation) | + | #### Common settings (Required) |
- | - Path to binary: /opt/phpswitcher/php7.1/sbin/psw7.1-fpm | + | - Path to PEAR directory: /opt/phpswitcher/%ymd%/php%version%/share/pear |
- | - Path to configuration file: /opt/phpswitcher/php7.1/etc/php-fpm.conf | + | |
- | - Path to pool directory: /opt/phpswitcher/php7.1/etc/php-fpm.d | + | |
- | Once done and if all went well, your customers should be able to switch on this new PHP version through their own | + | #### PHP FastCGI settings (Required) |
- | PhpSwitcher interface. | + | - Path to binary: /opt/phpswitcher/%ymd%/php%version%/bin/php-cgi |
+ | |||
+ | #### PHP-FPM settings (Required) | ||
+ | - Path to binary: /opt/phpswitcher/%ymd%/php%version%/sbin/psw%version%-fpm | ||
+ | - Path to configuration file: /opt/phpswitcher/%ymd%/php%version%/etc/php-fpm.conf | ||
+ | - Path to pool directory: /opt/phpswitcher/%ymd%/php%version%/etc/php-fpm.d | ||
## Plugin translation | ## Plugin translation | ||
- | You can translate this plugin using a gettext translation editor such as `poedit`. Translation files are located under | + | You can translate this plugin using a gettext translation editor such as |
- | the `./l10n` directory inside of this plugin archive. Once translated you can send us your translation file (po file) | + | `poedit`. Translation files are located under the `./l10n` directory inside of |
- | for integration in future release. | + | this plugin archive. Once translated you can send us your translation file |
+ | (po file) for integration in future release. | ||
- | Note that if no translation file exists for your localization in the `./l10n/po` directory, you must create it first | + | Note that if no translation file exists for your localization in the |
- | from the l10n/PhpSwitcher.pot file. Be aware that your file must be UTF-8, else, it won't be accepted. | + | `./l10n/po` directory, you must create it first from the l10n/PhpSwitcher.pot |
+ | file. Be aware that your file must be UTF-8, else, it won't be accepted. | ||
## License | ## License | ||
Line 371: | Line 495: | ||
``` | ``` | ||
i-MSCP PhpSwitcher plugin | i-MSCP PhpSwitcher plugin | ||
- | © 2014-2017 Laurent Declercq <[email protected]> | + | © 2014-2019 Laurent Declercq <[email protected]> |
i-MSCP License <https://www.i-mscp.net/license-agreement.html> | i-MSCP License <https://www.i-mscp.net/license-agreement.html> | ||
``` | ``` | ||
- | |||
- | See the LICENSE file inside the archive for further details. | ||
</markdown> | </markdown> |