# php_handler: 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