====== Enabling Per-User php.ini ======

This document lists the options for enabling a per-user php.ini when you are not running CloudLinux. For CloudLinux and CL PHP Selector has been used, you should refer to [[https://docs.cloudlinux.com/index.html?substitute_global_php_ini.html| "substitute global php.ini for individual customer"]].

The following steps show you how to do it when you are running off LSWS-native configs or running LiteSpeed Web Server (LSWS) off of Apache configurations. If running LSWS using native configs, please take a look at the [[litespeed_wiki:php:per-user-php-ini#notes|Notes]] section.

=====  Supports cPanel MultiPHP INI Editor out of the box =====
When a user logs in to cPanel and edits PHP settings through cPanel's [[https://documentation.cpanel.net/display/82Docs/MultiPHP+INI+Editor+for+cPanel|MultiPHP INI Editor]] (**cPanel > Home > Software > MultiPHP INI Editor**), the editor will save changes to three files in ''/home/$USER/public_html/'': the ''php.ini'' file, the ''user.ini'' file, and the ''.htaccess'' file. 

For example:
  [/home/blogu1/public_html]# ll
  -rw-r--r--  1 blogu1 blogu1 4484 Aug 29 12:25 .htaccess
  -rw-r--r--  1 blogu1 blogu1  576 Aug 29 12:25 php.ini
  -rw-r--r--  1 blogu1 blogu1  582 Aug 29 12:25 .user.ini

in .htaccess
  # BEGIN cPanel-generated php ini directives, do not edit
  # Manual editing of this file may result in unexpected behavior.
  # To make changes to this file, use the cPanel MultiPHP INI Editor (Home >> Software >> MultiPHP INI Editor)
  # For more information, read our documentation (https://go.cpanel.net/EA4ModifyINI)
  <IfModule php7_module>
   php_flag display_errors Off
   php_value max_execution_time 57
   php_value max_input_time 60
   php_value max_input_vars 1000
   php_value memory_limit 33M
   php_value post_max_size 8M
   php_value session.gc_maxlifetime 1440
   php_value session.save_path "/var/cpanel/php/sessions/ea-php72"
   php_value upload_max_filesize 2M
   php_flag zlib.output_compression Off
  </IfModule>
  <IfModule lsapi_module>
   php_flag display_errors Off
   php_value max_execution_time 57
   php_value max_input_time 60
   php_value max_input_vars 1000
   php_value memory_limit 33M
   php_value post_max_size 8M
   php_value session.gc_maxlifetime 1440
   php_value session.save_path "/var/cpanel/php/sessions/ea-php72"
   php_value upload_max_filesize 2M
   php_flag zlib.output_compression Off
  </IfModule>
  # END cPanel-generated php ini directives, do not edit

in .user.ini 
  ; cPanel-generated php ini directives, do not edit
  ; Manual editing of this file may result in unexpected behavior.
  ; To make changes to this file, use the cPanel MultiPHP INI Editor (Home >> Software >> MultiPHP INI Editor)
  ; For more information, read our documentation (https://go.cpanel.net/EA4ModifyINI)
  [PHP]
  display_errors = Off
  max_execution_time = 57
  max_input_time = 60
  max_input_vars = 1000
  memory_limit = 33M
  post_max_size = 8M
  session.gc_maxlifetime = 1440
  session.save_path = "/var/cpanel/php/sessions/ea-php72"
  upload_max_filesize = 2M
  zlib.output_compression = Off
                             
in  php.ini
  ; cPanel-generated php ini directives, do not edit
  ; Manual editing of this file may result in unexpected behavior.
  ; To make changes to this file, use the cPanel MultiPHP INI Editor (Home >> Software >> MultiPHP INI Editor)
  ; For more information, read our documentation (https://go.cpanel.net/EA4ModifyINI)
  display_errors = Off
  max_execution_time = 57
  max_input_time = 60
  max_input_vars = 1000
  memory_limit = 33M
  post_max_size = 8M
  session.gc_maxlifetime = 1440
  session.save_path = "/var/cpanel/php/sessions/ea-php72"
  upload_max_filesize = 2M
  zlib.output_compression = Off

You probably noticed that the same changes are being saved to three different files at the same time. This is because different PHP handlers will use different files to apply the settings. A user may change the handler at some point, and the three files will be udated accordingly to ensure the cPanel MultiPHP INI Editor settings will continue to apply.

Apache SuPHP uses php.ini. 

Apache PHP CGI and PHP-fpm use .user.ini. 

CloudLinux mod_lsapi for Apache uses .htaccess. 

LiteSpeed uses .htaccess.  

LiteSpeed is compatible with cPanel MultiPHP INI Editor out of the box with no extra configuration required. Please also keep in mind that you cannot manually change settings in any of the files through SSH. You must use cPanel MultiPhP INI Editor GUI to make any changes for your test.

If at any time you explicitly want to apply ''/home/$USER/public_html/php.ini'', regardless of the cPanel default multi-file implementation, you will need to use ''PHP_INI_SCAN_DIR'' to manually set it up as instructed later in this wiki. However, this is not recommended, and you are encouraged to just use cPanel MultiPHP INI Editor.

===== 1. Define PHPRC or PHP_INI_SCAN_DIR for a domain on cPanel server =====
To Define PHPRC or PHP_INI_SCAN_DIR for a particular domain/virtual host on a control panel, such as cPanel server, you will need to create an include file and define PHPRC or PHP_INI_SCAN_DIR in it.

Most likely you will need to install extra apache module for it:
  yum install ea-apache24-mod_env
or someting simliar, otherwise apache may return error like: 
  Apr 05 16:21:46 cptest.com restartsrv_httpd[21931]: AH00526: Syntax error on line 1 of /etc/apache2/conf.d/userdata/std/2_4/wpuser99/wpuser99.com/ini.conf:
  Apr 05 16:21:46 cptest.com restartsrv_httpd[21931]: Invalid command 'SetEnv', perhaps misspelled or defined by a module not included in the server configuration
  
For example, on an EA4 CentOS 7 server, to enable custom php.ini for yourdomain.com, create file   
  /etc/apache2/conf.d/userdata/std/2_4/$USER/yourdomain.com/customphpini.conf
  
  
add:
  PHP_INI_SCAN_DIR=/home/$USER/public_html/
or
  SetEnv PHPRC /home/$USER/public_html/
  
then make it virtual host inlcude file enabled:
  vi /etc/apache2/conf/httpd.conf

  Include "/etc/apache2/conf.d/userdata/std/2_4/$USER/yourdomain.com/*.conf"

Please be aware that you need to be very careful before you set the above up. cPanel EA4 only reads this specified php.ini when the PHPRC is set and won't read EA4 originally php.ini and modules in the scan folder. If user specified php.ini doesn't inlcude complete set of modules, it may lead to errors, for example, mysql missing.

[[
https://documentation.cpanel.net/display/EA4/The+cPanel+PHPRC+PHP+Patch+for+EasyApache+4|Please refer: The cPanel PHPRC PHP Patch for EasyApache 4]]

 "If you set the suPHP_ConfigPath directive, the specified php.ini file must be a complete .ini file."  

 "To ensure that your users receive a complete php.ini file, run the following command to combine your existing files:"

<code>cat /opt/cpanel/ea-php##/root/etc/php.ini /opt/cpanel/ea-php##/root/etc/php.d/*.ini > /path/to/specified/php.ini</code>


===== 2. Define PHPRC at the Server Level in the WebAdmin Console =====

Defining the PHPRC environment variable in the WebAdmin console allows you to use a variable that can set a standard location for the php.ini file in each virtual host. This method is also applicable to control panel environment such as cPanel, but it will modify the behavior of any virtual hosts using this external application, hence adding individual include file for that host apache configuration is normally recommended as described as above.

In your external application Environment setting (WebAdmin console > Server > External App > lsphp5), enter: ''PHPRC=variable/php.ini/directory''

Example:

  PHPRC=$VH_ROOT/public_html

The variables available for use are:

  - $VH_ROOT: the virtual host's home directory
  - $VH_NAME: the virtual host's domain
  - $VH_USER: the virtual host's user

**Note:** 
   * Using this method will cause LSWS to ignore any global php.ini files and only use the user-defined php.ini. However, if no user-defined php.ini found, LSWS will still use global php.ini  

Starting from LSWS 5.3.x, LSWS may automatically configure external applications and script handlers for control panels, hence it may not have external applications or script handlers anymore. If you want to define PHPRC environment variable for all external applications, you can use ''PHP'' tab:
{{ :litespeed_wiki:php:lsws-5.3.x-php-tab.png?800 |}}
 

===== 3. Define PHP_INI_SCAN_DIR at the Server Level in the WebAdmin Console =====

Using the ''PHP_INI_SCAN_DIR'' environment variable allows you to set a standard location for the php.ini file for each virtual host. Unlike the ''PHPRC'' environment variable, though, ''PHP_INI_SCAN_DIR'' allows the use of the global php.ini file with the addition of a per-user php.ini.

In a control panel environment such as with cPanel, ea-phpxx will normally load the main php.ini, then scan additional .ini files, like in this example with ea-php73:

{{ :litespeed_wiki:php:per-user-php-ini-additional-ini1.png?800 |}}

To avoid missing any additional folders when scanning from ''/opt/cpanel/ea-php73/root/etc/php.d'', you should specify multiple additional scanning folders in ''PHP_INI_SCAN_DIR'', separating them with '':''. 

In your external application **Environment** setting (**WebAdmin Console > Server > External App > lsphp73**), enter: 

  PHP_INI_SCAN_DIR=/opt/cpanel/ea-php73/root/etc/php.d:$VH_ROOT/public_html
or simply:
  PHP_INI_SCAN_DIR=:$VH_ROOT/public_html  
{{ :litespeed_wiki:php:per-user-php-ini-additional-ini2.png?800 |}}

After you save the change and restart LSWS, the phpinfo page of the accounts using lsphp73 should change to something similar to the following by scanning additional ''.ini'' for additional folders from ''$VH_ROOT/public_html'':
{{ :litespeed_wiki:php:per-user-php-ini-additional-ini3.png?800 |}}

The variables available for use are:

  - ''$VH_ROOT'': the virtual host's home directory
  - ''$VH_NAME'': the virtual host's domain
  - ''$VH_USER'': the virtual host's user

 **Note:** 
  * This method is not recommended if you replace Apache with suPHP. When replacing Apache with suPHP, the ''PHPRC'' environment variable is recommended.
  * The ''PHP_INI_SCAN_DIR'' environment variable is available for PHP 5.2.7 and up.

Starting from LSWS 5.3.x, LSWS may automatically configure external applications and script handlers for control panels, hence it may not have external applications or script handlers anymore. If you want to define the ''PHPRC'' environment variable for all external applications, you can use the **PHP** tab.

===== 4. Define PHPRC in Apache Configs =====

Defining the PHPRC environment variable in Apache's virtual host configurations allows you to set a php.ini location for a specific virtual host.

In the Apache virtual host configuration file, add ''SetEnv PHPRC /php.ini/directory''.

**Note:** 
   * Using this method will cause LSWS to ignore any global php.ini files and only use the user-defined php.ini.
   * This method is supported in LSWS 4.2.13 and up.

===== 5. Define PHPIniDir in Apache Configs =====

Using the PHPIniDir directive in Apache's virtual host configurations allows you to set a php.ini location for the main virtual host of a specific user.

In the Apache virtual host configuration file, add ''PHPIniDir /path/to/php.ini/directory''

**Note:** 
  * The PHPIniDir directive at the vhost level has been supported since LSWS 4.0.2.
  * The PHPIniDir directive is effective **ONLY IF** placed in the 1st (or main domain) vhost of the user. Placing this directive in a subdomain vhost will be cause it to be ignored.

===== 6. How to use .user.ini with lsphp? =====
To make .user.ini to work with lsphp, you need to change lsphpX external app configuration by adding environment variable:
  LSPHP_ENABLE_USER_INI=on

This directive is supported since PHP LSAPI version V6.10.

===== 7. Override External Application Environment Variables =====
The special Apache directive ''LS_EXTAPP_ENV'' can be used on cPanel or other control panel environments to override External application environment variables.

If you have set up ''PHP_INI_SCAN_DIR'' in step 3, and ''PHP_INI_SCAN_DIR'' in step 1, LSWS will use ''PHP_INI_SCAN_DIR'' from an external app environment instead of using Apache directives. Starting from LSWS 5.3.4, you can override this external app environment using a new special Apache directive: ''LS_EXTAPP_ENV''. Place the directive in the Apache virtual host include file, like so:

For example, say you have set the following in an external app environment:
  PHP_INI_SCAN_DIR=/home/USER1/public_html
If you want to override it to another location, such as ''/home/USER1/data'', you can add the following to the Apache virtual host include file:
  <IfModule Litespeed>
  LS_EXTAPP_ENV PHP_INI_SCAN_DIR=/home/USER1/data/
  </IfModule>

===== 8. Use of ''disable_functions'' =====

Please be aware, for security and performance reasons, ''disable_functions'' is unique and can only be set in php.ini, cannot be used in .htaccess, nor be overridden via ''php_admin_value''. You can only apply ''disable_functions'' via global or per-user php.ini.  It would be a security flaw if a user could modify it freely, hence it has been restricted by design in PHP itself, not by LiteSpeed. 


===== Notes =====
  * **PHP suEXEC MUST BE ENABLED IN LSWS.**
  * Make sure the php.ini file is readable by the **Run As User** user.
  * Option 3 can be used along with options 1, 2, or 4 without conflicts. However, this should rarely be needed.
  * Option 4 takes precedence over options 1 and 2 should they be used at the same time.
  * Changes in the php.ini will not be picked up until new PHP process starts. The php.ini is read for the first time when a PHP process starts.
  * Per-user php.ini files are not compatible with [[http://www.litespeedtech.com/products/litespeed-sapi/php/suexec-daemon-mode|Daemon mode]]. Our [[http://www.litespeedtech.com/products/litespeed-sapi/php/guide-to-suexec-setups|two other PHP process modes]] both support per-user php.ini.
  * For native LSWS installs, these variables ($VH_ROOT, $VH_NAME, $VH_USER, etc.) need to be inside of a Virtual Host External App Environment Section, and not inside the general Server External App Environment Section. This is because the variables are expanded on start up, so the VH_* variables cannot be expanded during server level configurations.



===== Troubleshoot =====
Some PHP extensions are missing after being loaded with per user ''php.ini'', for example 
<code>Your PHP installation appears to be missing the MySQL extension which is required by WordPress.</code>

This is because once custom php.ini is loaded, the default php.ini will be ignored. Therefore, extensions will not be loaded.

The easiest way to resolve this problem is to copy the contents of the default php.ini into the custom php.ini by the following command:

<code>cat /opt/cpanel/ea-phpXX/root/etc/php.ini /opt/cpanel/ea-phpXX/root/etc/php.d/*.ini > /path/to/php.ini</code>

Please replace ''ea-phpXX'' and ''/path/to/php.ini'' with the appropriate version and path.

Verify the php.ini content and restart LSWS if necessary, as a change in php.ini will not take effect until a new PHP process starts. The php.ini is read for the first time when a PHP process starts.