php-src/README.Zeus

Using PHP4 with the Zeus Web Server
-----------------------------------

Zeus fully supports running PHP in combination with our webserver. A
significant improvement in PHP 4 is that you can now run PHP as an
ISAPI module, giving great performance benefits over traditional CGI
code.

Note that you will need to be running at least version 3.3.8 of the
webserver. If you are running an earlier version, please see our
website (http://www.zeus.com) for upgrade instructions.
Earlier versions of Zeus (3.3.6) can also run PHP, but it is
suggested that you upgrade for full compatibility.

You should compile PHP using the gcc compiler. Other compilers may
cause build errors.

To build the ISAPI version of PHP, start the configuration with:

./configure --with-zeus=/usr/local/zeus

Obviously, replace /usr/local/zeus with the location of where you have
installed Zeus on your machine. For PHP to build successfully, you
need to have 3.3.6 already installed, because the code relies on the
presence of header files provided with the latest version.

You may have to adjust the environment variable LDFLAGS and EXTRA_LIBS
in order to link in extra libraries. This depends on the platform on
which you are building and also on the compiler used (see below). A
standard GNU/Linux install with GCC should build fine with no changes.


Configuring the webserver
-------------------------

After running 'make' and 'make install', you will have a 'libphp4.so'
file. Copy this file into a directory reserved for ISAPI
binaries. Now, perform the following steps for each virtual server
that you wish to run PHP on:

1) On the Admin server, go to 'edit server->path mapping'
2) Add an alias to the directory with libphp4.so in it, mapped to
   /isapi/ (or a location of your choice). Make sure you set the alias
   type to ISAPI.
3) Click 'update'
4) Add a handler for file extension 'php' to be run by /isapi/libphp4.so
5) Click 'update', then go back to the previous page.
6) Click on the 'module configuration' button, ensure that ISAPI
   support is ticked.
7) Click on the ISAPI link. At the bottom of the page, click the
   checkbox for running ISAPI extensions 'out of process'.
8) Click 'update'. Then restart the virtual server. Done!


Troubleshooting
---------------

*) Why does the compile fail at Zend/zend-scanner-cc.cc
                             or Zend/zend-parser.c ?

These source files are auto-generated from the corresponding .y files.
The default distribution of PHP contains pre-generated versions of these
files that have caused problems for some people. The simplest solution is
to delete the files. They will then be rebuilt correctly. You must have the
following GNU tools to do this:

       bison  1.28 or later
       flex  2.5.4 or later

*) Why does my PHP library fail to load?

After configuring Zeus, if you get a '502 Bad Gateway' error when
accessing a PHP page, there are problems loading the PHP
library. Check the error log ($ZEUSHOME/web/log/errors) for errors.

Failing to load the PHP ISAPI module is likely to be due to unresolved
symbols in the module. A way to check for this is to visit our support
page at http://support.zeus.com/faq/entries/isapi_error.html and run
the program there on your libphp4.so. It will list any unresolved
symbols.

*) My libphp4.so has unresolved symbols. How do I fix this?

You must ensure that the PHP build process links in the appropriate
libraries that contain these symbols! The libraries required will
depend on the platform you are running PHP on.

You may need to set one or two environment variables before running
the 'configure' program to set up PHP; LDFLAGS and EXTRA_LIBS. Make
sure that you also export these variables to the build process.
(Type 'export LDFLAGS EXTRA_LIBS' in the shell to do this.)

If you are using 3rd party tools and libraries which are installed
in non-standard locations, you may need to set the environment
variable LD_LIBRARY_PATH to point to the library's location, prior
to running the Zeus Web Server. For example, if you have compiled
external MySQL support, and mysql is installed in /usr/local/mysql,
you should set LD_LIBRARY_PATH to '/usr/local/mysql/lib/mysql'
and then 'export LD_LIBRARY_PATH'. For convenience, you should add
this to the 'start-zeus' script provided.

Yet another method of ensuring the linked libraries are found is to
set the environment variable LD_RUN_PATH before compiling PHP. This
works in a similar way to LD_LIBRARY_PATH, but at compile-time.
Libraries produced with this envrionment variable set will have its
value 'burned' into the resultant binary, specifying a runtime
search pth to locate other required libraries such as MySQL.

On Linux, you can also tell the dynamic linker where to find the
libraries, by adding '/usr/local/mysql/lib/mysql' to the file 
/etc/ld.so.conf - after editting this file, run 'ldconfig' as root,
to use the changes.


Specific examples:

Solaris + gcc:
Ensure you run ./configure with the `--enable-libgcc' parameter. You
may need to set LDFLAGS to '-L/usr/local/egcs/lib' (path depends on
your gcc installation)

FreeBSD 4:
Some people may find they need to run ./configure with the
'--enable-libgcc' compile option too.


Performance issues
==================

To make PHP run fast under Zeus, check the following points:

1) Run PHP as an ISAPI module, not a CGI - compile it with the --with-zeus=...
   flag!

2) Tune the ISAPI runner to your required workload. There are several
   tuneables that can be given. These are set by adding the appropriate
   lines to the $ZEUSHOME/web/global.cfg file. Changes to this file will only
   be picked up after the web server is restarted (run stop-zeus ; start-zeus)

   tuning!modules!isapi!external!maxthreads xxx

   - Sets the maximum number of threads that the ISAPI runner will spawn. If
     further PHP page requests arrive, they will be queued until a current
     page is finished. For busy websites, we suggest increasing this value
     (defaults to 16). Replace the 'xxx' in the above line with the required
     number of threads. Note that the threads are equally shared between
     ISAPI extensions and filters, so if you want to handle 100 concurrent
     PHP page requests, set this tuneable to 200.

   tuning!modules!isapi!external!minthreads xxx

   - Sets the minimum number of threads. Idle threads will be kept in a pool,
     which avoids costly thread creation/deletion.


For more information and help with Zeus, please visit our website:
http://support.zeus.com