The php_handler utility is used to manage PHP versions, SAPI, and php.ini availiable for hosting users (PHP handlers). For more information, see Multiple PHP Versions and PHP Settings in the Administrator’s Guide.

By using the php_handler utility, you can perform the following tasks:

  • Manage PHP handlers and PHP extensions in Plesk.
  • Replace one PHP handler with another for all used service plans and websites.
  • Get information about PHP handlers and PHP extensions in JSON or plain text format.

Usage 

php_handler <command> [
<option_1> [<param>]
[<option_2> [<param>]]
... [<option_N> [<param>]]
]

Example

The following command registers a new PHP handler as a FastCGI binary in Plesk:

plesk bin php_handler --add -displayname "MyHandler 5.4" -path /usr/bin/php-cgi -clipath /usr/bin/php -phpini /opt/plesk/php/5.4/etc/php.ini -type fastcgi

The following command registers a new PHP handler as an FPM application in Plesk:

plesk bin php_handler --add -displayname "MyHandler 5.5" -path /usr/bin/php -clipath /usr/bin/php -phpini /opt/plesk/php/5.5/etc/php.ini -type fpm -service php5-fpm -poold /etc/php5-fpm/pool.d

Commands

Command Description Example
--add

Registers a PHP handler.

Requires the -displayname, -path, -type, and -clipath options.

Fot PHP handlers of the FPM type, the required options are -service and -poold.

To register the PHP handler for PHP version 5.4, installed in /usr/bin/php-cgi as a FastCGI binary, using the /opt/plesk/php/5.4/etc/php.ini file, and to specify the path to the PHP CLI binary as /usr/bin/php:

plesk bin php_handler --add -displayname "MyHandler 5.4" -path /usr/bin/php-cgi -clipath /usr/bin/php -phpini /opt/plesk/php/5.4/etc/php.ini -type fastcgi

--update

Updates an existing PHP handler.

To get the handler ID, use the --list command.

Only custom handlers can be updated.

To change the path to the php.ini file for the handler with the ID 123:

plesk bin php_handler --update -id 123 -phpini /new/path/php.ini

--replace Replaces a certain PHP handler with another one for all service plans and websites in Plesk.

To replace the PHP handler (whose ID is 123) with another PHP handler (whose ID is 789):

plesk bin php_handler --replace -old-id 123 -new-id 789

--remove

Deletes a PHP handler. The handler must not be used in service plans or websites. If you try to remove an already used PHP handler, the following error will be displayed: “Unable to remove the PHP handler: The PHP handler is used in site configurations”.

Only custom handlers can be deleted.

To remove the PHP handler with the ID 123:

plesk bin php_handler --remove -id 123

--enable Enables the specified PHP handler. The enabled PHP handler can be selected in a website’s PHP settings.

To enable the PHP handler with the ID 123:

plesk bin php_handler --enable -id 123

--disable Disables the specified PHP handler. Disabled PHP handlers cannot be selected in a website’s PHP settings. If you disable a PHP handler already used on some website, the website will use a PHP handler defined in its service plan.

To disable the PHP handler with the ID 123:

plesk bin php_handler --disable -id 123

--get-usage Displays the list of domains that use the specified PHP handler.

To show all domains that use the PHP handler with the ID 123:

plesk bin php_handler --get-usage -id 123

--list Displays the list of all PHP handlers registered in Plesk.

To view all registered PHP handlers:

plesk bin php_handler --list

--reread Refreshes information about PHP handlers in Plesk. Use this command after some of PHP binary files have been upgraded.

To refresh information about PHP handlers in Plesk:

plesk bin php_handler --reread

--extension-list

Shows the list of installed PHP extensions with their status (enabled or disabled) for the specified PHP handler.

Requires the -id option.

To show all PHP extensions installed for the “8.2.7 CGI application” PHP handler:

plesk bin php_handler --extension-list -id plesk-php82-cgi

--extension-enable

Enables a PHP extension for the specified PHP handler.

Requires the -id option.

To enable the ionCube Loader PHP extension for the “8.0.29 FPM application” PHP handler:

plesk bin php_handler --extension-enable ioncube_loader -id plesk-php81-fpm

--extension-disable

Disables a PHP extension for the specified PHP handler.

Requires the -id option.

To disable the ionCube Loader PHP extension for the “8.0.29 FPM application” PHP handler:

plesk bin php_handler --extension-disable ioncube_loader -id plesk-php81-fpm

--extension-install

Installs a PHP extension for the specified PHP handler.

Requires the -id option.

To install the APCu PHP extension for the “8.0.29 FPM application” PHP handler:

plesk bin php_handler --extension-install apcu -id plesk-php81-fpm

--extension-uninstall

Uninstalls a PHP extension for the specified PHP handler:

Requires the -id option.

To uninstall the APCu PHP extension for the “8.0.29 FPM application” PHP handler:

plesk bin php_handler --extension-install apcu -id plesk-php81-fpm

--extension-list-installable

Shows the list of all PHP extensions available for installation for the specified PHP handler.

Requires the -id option.

To show all PHP extensions you can install for the “8.2.7 CGI application” PHP handler:

plesk bin php_handler --extension-list-installable -id plesk-php82-cgi

--help or -h Displays help on the use of the utility.

To view help on the use of the utility:

plesk bin php_handler --help

or

plesk bin php_handler -h

Options

Option Parameter Description Example
-id <handler id>

Sets the PHP handler ID.

Used with the --add, --update, --remove, --enable, --disable, and --get-usage commands.

If you do not specify an ID when registering a PHP handler, the ID will be set automatically.

To view the IDs of registered handlers, use the --list command.

To register a PHP handler for PHP version 5.6, with the ID 123 installed in /usr/bin/php-cgi as a FastCGI binary, and using the /opt/plesk/php/5.6/etc/php.ini file:

plesk bin php_handler --add -displayname "MyHandler 5.6" -id 123 -path /usr/bin/php-cgi -clipath /usr/bin/php -phpini /opt/plesk/php/5.6/etc/php.ini -type fastcgi

-displayname <name>

Sets the name for the PHP handler to be displayed in Plesk.

Used with the --add and --update commands.

To register a PHP handler for PHP version 5.4, installed in /usr/bin/php-cgi as a FastCGI binary, and using the /opt/plesk/php/5.4/etc/php.ini file:

plesk bin php_handler --add -displayname "MyHandler 5.4" -path /usr/bin/php-cgi -clipath /usr/bin/php -phpini /opt/plesk/php/5.4/etc/php.ini -type fastcgi

-path <path to php-cgi>

Sets the path to the PHP-CGI binary file (for CGI or FastCGI applications) or PHP-FPM file (for FPM applications).

Used with the --add and --update commands.

  
-phpini <path to php.ini>

Sets the path to the php.ini file.

Used with the --add and --update commands.

  
-type <cgi|fastcgi|fpm>

Sets the PHP handler type.

Used with the --add and --update commands.

  
-service <service name>

Defines the service name.

Used with the --add and --update commands when configuring FPM type handlers.

To register a PHP handler for PHP version 5.5, installed in /usr/bin/php as an FPM application, using the /opt/plesk/php/5.5/etc/php.ini file, with the php5-fpm service name and the path to the pool.d directory /etc/php5-fpm/pool.d:

plesk bin php_handler --add -displayname "MyHandler 5.5" -path /usr/bin/php -clipath /usr/bin/php -phpini /opt/plesk/php/5.5/etc/php.ini -type fpm -service php5-fpm -poold /etc/php5-fpm/pool.d

-poold <path to pool.d>

Defines the path to the pool.d directory.

Used with the --add and --update commands when configuring FPM type handlers.

  
-old-id <old handler id>

Specifies the PHP handler you want to replace.

Used with the --replace command.

To replace the PHP handler (whose ID is 123) with another PHP handler (whose ID is 789):

plesk bin php_handler --replace -old-id 123 -new-id 789

-new-id <new handler id>

Specifies the PHP handler you want to replace the existing one with.

Used with the --replace command.

  
-json true|false

Displays the output in the JSON format (if true) or in plain text format (if false). The JSON format may be used to pass information about PHP handlers to scripts.

Used with the --list and the --get-usage commands (optional, by default, is false).

To display the list of PHP handlers in the JSON format:

plesk bin php_handler --list -json true

-clipath <path to php-cli>

Sets the path to the PHP CLI binary file.

Used with the --add and --update commands.

To register a PHP handler for PHP version 5.4, installed in /usr/bin/php-cgi as a FastCGI binary, using the /opt/plesk/php/5.4/etc/php.ini file and to specify the path to the PHP CLI binary as /usr/bin/php:

plesk bin php_handler --add -displayname "MyHandler 5.4" -path /usr/bin/php-cgi -clipath /usr/bin/php -phpini /opt/plesk/php/5.4/etc/php.ini -type fastcgi