====== PHP 4/5 with LSAPI Compile/Install How-To ======




===== Preamble =====

LSAPI is LiteSpeed's open-source API between external applications and LiteSpeed Web Server. This how-to is for compiling and installing PHP + LSAPI on Linux, OS X, FreeBSD, Solaris, and so on.

In this how-to such directories as ///lswsinstall// and ///php5// are used as general directories to refer to the paths actually used. If you did not modify the installation location of LSWS on initial installation this will be at ///opt/lsws//. The PHP install directory can be any directory which you will set upon the initial configuration of PHP by changing the --prefix value.

With LSWS 3.3 release or later, LSAPI PHP can be built from within the web console. Step 1-6 can be skipped in this tutorial.

If PHP has been installed on your server, either as mod_php or FastCGI PHP, you should copy over the configuration parameters used for your current PHP. The configuration parameter is available from a phpinfo() page. When you copy over the configuration parameters, you should remove parameters specific to that SAPI, like "--with-axps(2)", "--enable-fastcgi", etc. The web console will add "--with-litespeed" automatically. 

You also need to make decision whether to install PHP to its current location. Usually is  "--prefix=/usr/local". If you compile the same PHP version for LiteSpeed, you can choose to install to the same location. Just remember to upgrade both LiteSpeed PHP and Apache mod_php later together if you want to keep both LiteSpeed and Apache work properly. Mixing different version of PHP together may break you PHP installation.

If you want to compile different PHP version, for example, have LiteSpeed support both PHP4 and PHP5, you should install them to different location. For PHP4 we recommend something like "--prefix=/lsphp4", for PHP5, we recommend something like "--prefix=/lsphp5". 










===== Instructions =====
==== You can skip step 1-6 by using the new "Compile PHP" feature from LiteSpeed Web console under "Actions" menu ====


1) Download/expand latest PHP 4/5 from http://www.php.net/downloads.php:

<code>
wget http://us3.php.net/get/php-5.2.6.tar.gz/from/us2.php.net/mirror
tar -zxf php-5.2.6.tar.gz
</code>

2) Change directory (''cd'') into php-source/sapi directory: 

<code>
cd php-5.2.6/sapi
</code>

We will refer to the unpacked php src directory as "/php-source/".

3) Download and expand latest LSAPI for PHP from http://www.litespeedtech.com/products/lsapi/download/ into the “sapi” folder of php source:

<code>
wget http://www.litespeedtech.com/packages/lsapi/php-litespeed-4.7.tgz
tar -zxf php-litespeed-4.7.tgz
</code>

4) Change directory to root PHP source directory and run commands:

<code>
cd ..
touch ac* 
./buildconf --force
</code>

**Update: You can combine step 1-4 by downloading patched PHP package from ** [[http://download.medialayer.net/public/|http://download.medialayer.net/public/]]
These packages include Suhosin (hardened-php.net), and mail_header patch (choon.net).

5) Configure/Compile PHP:

<code>
./configure '--prefix=/lsphp5' '--with-litespeed' --with-mysql ...
make
make install
</code>

If you would like to compile with additional PHP extensions, insert the options in the ./configure line. If you migrate from a Apache installation, you can use exact the same configuration options dumped in output of a phpinfo() page, just remember to remove **--with-apxs** and **--with-apxs2** options. These are for installing PHP with Apache, not Litespeed. If you want to use PHP with MySQL 4.1 and above, you should build PHP with the client library coming with MySQL installed on your server by using option **--with-mysql**=<path_to_mysql_base_dir>, MySQL client shipped with PHP may not work due to changes in MySQL authentication.

**Note:** You must compile PCRE (Perl Compatible Regular Expressions) support in order for the default auto-index PHP script to work correctly (at least this is true for 3.0RC2).

6) Replace the lsphp5 binary (backup first) in /opt/lsws/fcgi-bin/ directory with /php-src/sapi/litespeed/php:

<code>
cd /opt/lsws/fcgi-bin/
cp /php-src/sapi/litespeed/php lsphp-5.2.6
ln -sf lsphp-5.2.6 lsphp5
</code>

Remember that /php-src/ is the source directory of php where you unpacked and compiled php.


=====Check Installation=====

7) To check installation success:

<code>
cd ..
fcgi-bin/lsphp5 -v
</code>

It should return something like:

<code>
PHP 5.2.6 (litespeed) (built: Aug 26 2008 14:09:09)
Copyright (c) 1997-2004 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2008 Zend Technologies
</code>

Notice **litespeed** in parenthesis. This means that the PHP binary has litespeed (LSAPI) support builtin.

Final check:
 
<code>
fcgi-bin/lsphp5 -i
</code>

Above command will dump all the version info, configuration settings, and list of installed extensions with PHP.



=====Final Instructions=====

8) Location of php.ini:

<code>lsphp5 -i</code>
give the location that PHP looking for php.ini, 

<code>Configuration File (php.ini) Path => /opt/lsws/lsphp5/lib</code>

You should place php.ini at
 
<code>/opt/lsws/lsphp5/lib/php.ini</code>

9) Restarting Litespeed Webserver

Our final step is to restart LSWS and use our new PHP binary.

<code>
/opt/lsws/bin/lswsctrl restart
</code>

We should now be running our new PHP binary with LSAPI, however we'll check. Run:

<code>tail -n100 /opt/lsws/logs/error.log
tail -n100 /opt/lsws/logs/stderr.log</code> 

to make sure your newly compiled PHP did not throw any fatal errors on startup.



=====Trouble shooting=====
If you LiteSpeed PHP setup give 503 errors, you may have PHP configuration problem, usually it is because the version of a loadable module does not match the PHP version used. You need to recompile the loadable module to fix it.

Some trouble shooting techniques:
  * check lsws/logs/stderr.log and lsws/logs/error.log.
  * try to start the lsphp binary with matching user id with command like

  sudo -u nobody ./lsphp5 -i

  * disable opcode cache one by one, especially when multiple caches are used, like xcache, eaccelerator, APC, ionCube, etc.
  * compare the phpinfo() page to a working installation, sometimes, due to permission problem, php configuration files cannot be fully loaded.
  * strace/truss/ktrace a lsphp process, it shows all the system calls made by the process.