php_handler: Custom PHP Handlers

The php_handler utility is used to 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:

  • managing PHP handlers in Plesk
  • replacing one PHP handler with another for all used service plans and sites
  • obtaining information about PHP handlers 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 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 -displayname, -path, -type, -clipath options.

 

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

To register a PHP handler for PHP of version 5.4, installed to /usr/bin/php-cgi as a FastCGI binary, using the php.ini located in /opt/plesk/php/5.4/etc/php.ini 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 obtain the handler's id, use the --list command.

Only custom handlers can be updated.

To change the path to the php.ini file for the handler with 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 (id=123) with another PHP handler (id=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 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 identifier 123:

plesk bin php_handler --remove -id 123

--enable

Enables the specified PHP handler. Enabled PHP handler can be selected in PHP settings of a site.

To enable the PHP handler with the identifier 123:

plesk bin php_handler --enable -id 123

--disable

Disables the specified PHP handler. Disabled PHP handlers cannot be selected in PHP settings of a site. If you disable a PHP handler that is already used on some site, this site will use a PHP handler defined in its service plan.

To disable the PHP handler with the identifier 123:

plesk bin php_handler --disable -id 123

--get-usage

Displays the list of domains that use the specified PHP handler.

To get the usage of the PHP handler with the identifier 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

--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 identifier.

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

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

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

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

plesk bin php_handler --add -displayname "MyHandler 5.6" -id 12345 -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 the Plesk user interface.

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

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

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 of version 5.5, installed to /usr/bin/php as a FPM application, using php.ini located in /opt/plesk/php/5.5/etc/php.ini, with a service name php5-fpm 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 (id=123) with another PHP handler (id=789):

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

-new-id

<new handler id>

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

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 command (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 of version 5.4, installed to /usr/bin/php-cgi as a FastCGI binary, using php.ini located in /opt/plesk/php/5.4/etc/php.ini 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

 

Leave your comments on this page

Leave your feedback or question on this documentation topic below. For technical assistance, contact your hosting service provider or submit a request to Plesk support. Suggest new features for Plesk here. Discuss general questions on the Plesk forum. All offtopic comments will be removed.