php-src/sapi/litespeed

Introduction
============

LiteSpeed SAPI module is a dedicated interface for PHP integration with
LiteSpeed Web Server. LiteSpeed SAPI has similar architecture to the
FastCGI SAPI with two major enhancements: better performance and
support for dynamic PHP configuration changes through web server
configuration and .htaccess files.  

Our simple benchmark test ("hello world") shows that PHP with
LiteSpeed SAPI has 30% better performance over PHP with FastCGI SAPI,
which is nearly twice the performance that Apache mod_php can deliver. 
 
A major drawback of FastCGI PHP comparing to mod_php is that "php.ini"
is the only way to set PHP configuration, and cannot be changed at
runtime via configuration files like .htaccess files or web server's
virtual host configuration. As FastCGI PHP is usually shared at server
level by all virtual hosts, it is big security concern to use it in a
shared hosting environment. LiteSpeed SAPI is carefully designed to
address this issue. It accepts same flexible configuration overridden
methods as those supported in mod_php. LiteSpeed SAPI also uses the
same configuration directives as Apache mod_php. 

Therefore, with above enhancements, LiteSpeed SAPI is highly
recommended over FastCGI SAPI for using PHP with LiteSpeed web
server. 


Building PHP with LiteSpeed SAPI
================================

You need to add "--with-litespeed" to the configure command to build
PHP with LiteSpeed SAPI, all other SAPI related configure options
should be removed. 

For example: 
    ./configure --with-litespeed
    make

You should find an executable called 'php' under sapi/litespeed/
directory after the compilation succeeds. Copy it to
'lsws/fcgi-bin/lsphp' or wherever you prefer, if LiteSpeed web server
has been configured to run PHP with LiteSpeed SAPI already, you just
need to overwrite the old executable with this one and you are all
set. 


Using LiteSpeed PHP with LiteSpeed Web Server
=============================================

Detailed information about how to configure LiteSpeed web server with
PHP support is available from our website, at: 

http://www.litespeedtech.com/docs/HowTo_QA.html

Usually, PHP support has been configured out of box, you don't need to
change it unless you want to change PHP interface from FastCGI to
LiteSpeed SAPI or vice versa. 

Brief instructions are as follow:

1) Login to web admin interface, go to 'Server'->'Ext App' tab, add an
   external application of type "LSAPI app", "Command" should be set
   to a shell command that executes the PHP binary you just
   built. "Instances" should be set to match the value of "Max
   Connections".  

2) Go to 'Server'->'Script Handler' tab, add a script handler
   configuration: set 'suffix' to 'php', 'Handler Type' to 'LiteSpeed
   API', 'Handler Name' should be the name of external application
   just defined. 


3) Click 'Apply Changes' link on the top left of the page, then click 
   'graceful restart'. Now PHP is running with LiteSpeed SAPI. 

Tuning
------

There are two environment variables that can be tweaked to control the
behavior of LiteSpeed PHP.  

PHP_LSAPI_CHILDREN  (no default)

In order to handle multiple requests concurrently, LiteSpeed web
server can either spawn multiple PHP processes; or spawn one process,
and this process will create a number of child processes to handle
multiple requests simultaneously. 

The web server will create PHP processes specified by "Instance" in
LSAPI application configuration. For one PHP process launched by the
server, if PHP_LSAPI_CHILDREN is not set, it will not create any child
process; if PHP_LSAPI_CHILDREN is set, it will spawn a number of child
processes specified by PHP_LSAPI_CHILDREN. Usually, it should match
"Max Connections" configured for the LSAPI application, and both
values should not be set over 100 in most cases. 

PHP_LSAPI_MAX_REQUESTS (default value: 500)

This controls how many requests each child process will handle before
exit. When one process exits, another will be created. This tuning is
necessary because several PHP functions have been identified having
memory leaks. If the PHP processes were left around forever, they
could become very inefficient. 


Contact
=======

For support questions, please post to our free support forum, at:

http://www.litespeedtech.com/forum/

For bug report, please send bug report to bug [at] litespeedtech.com.