======================================================================
Requirements
======================================================================

- A supported version of PHP:

  * 5.1.2 (SLES 10)
  * 5.1.6 (RHEL)
  * 5.2.3 (source builds)

  You can download PHP from

    http://www.php.net/downloads.php

- Ice for C++ 3.2.1 development kit


======================================================================
Building PHP with the Ice extension (Linux)
======================================================================

This source distribution only supports building IcePHP as a dynamic
PHP extension; the product of the build is a shared library that you
must configure PHP to load.

Follow the steps below to build IcePHP:

1. Edit config/Make.rules and review the build settings. For example,
   you may want to enable OPTIMIZE. If your PHP installation resides
   in a non-standard location, modify the PHP_HOME setting to contain
   the installation directory.

2. Set the ICE_HOME environment variable to the directory containing
   your Ice installation. For example, if Ice is installed in
   /opt/Ice-3.2.1, set ICE_HOME as follows:

   $ export ICE_HOME=/opt/Ice-3.2.1

   If you installed Ice using RPMs, set ICE_HOME as shown below:

   $ export ICE_HOME=/usr

3. Run make.


======================================================================
Building PHP with the Ice extension (Windows)
======================================================================

Compiling PHP from source code on Windows is a tedious process,
therefore we recommend that you download the precompiled dynamic
Ice extension from the ZeroC web site (included in the Ice installer
for Visual C++ 6.0) and use the binary PHP distribution if possible.

If you prefer to build the Ice extension yourself, you must first
understand the C run time dependency issues. Specifically, the Ice
extension must use the same C run time as PHP5. Since the binary
distribution of PHP5 available from php.net depends on the Visual C++
6.0 run time DLL (MSVCRT), you must also build the Ice extension using
Visual C++ 6.0 if you want to use Ice with this PHP distribution. This
is the reason why the precompiled Ice extension is included in the Ice
installer for Visual C++ 6.0, as attempting to use an Ice extension
that was built with a newer compiler together with the binary PHP
distribution results in undefined behavior.

To use a later version of Visual C++, you must obtain (or build) PHP5
with the desired compiler, and use the same compiler to build the Ice
extension. Refer to the PHP documentation for instructions on building
PHP5 from source.

Follow these instructions to build the Ice extension:

1) Download the PHP5 binary archive or Windows installer and install
   the distribution.

2) Download and extract the PHP5 sources (IcePHP requires the PHP
   header files).

3) Open a command window.

4) Set the ICE_HOME environment variable to the location of your Ice
   installation. For example:

   > set ICE_HOME=C:\Ice-3.2.1-VC60

5) Change to the IcePHP source directory.

6) Open config\Make.rules.mak, review the comments, and make any
   necessary changes. In particular, you may need to change the values
   of PHP_HOME and PHP_BIN_HOME to refer to your PHP source and binary
   installations, respectively.

7) Start NMAKE:

   > nmake /f Makefile.mak

8) Upon successful completion, the IcePHP extension is created as
   bin\php_ice.dll (Release) or bin\php_iced.dll (Debug).


======================================================================
Installing the Extension
======================================================================

To install the Ice extension, you must move the extension's shared
library into PHP's extension directory. This directory is determined
by the PHP configuration directive "extension_dir". You can determine
the default value for this directive by running the command-line
version of PHP with the -i option:

> php -i
...
extension_dir => C:\php5 => C:\php5
...

After successfully building the extension on Linux, the shared library
is created as lib/IcePHP.so. On Windows, the DLL is created as
bin/php_ice.dll (release) or bin/php_iced.dll (debug).

Once you've copied the extension to PHP's extension directory, you
will need to enable the extension in your PHP configuration. In the
php.ini file, use the following directive on Linux:

extension = IcePHP.so

On Windows, use this directive:

extension = php_ice.dll

You can use the "php -i" command to determine the proper directory in
which to place the php.ini file:

> php -i
...
Configuration File (php.ini) Path => C:\WINDOWS
...


======================================================================
Dependencies
======================================================================

PHP will need to be able to locate the Ice run-time libraries "Ice",
"Slice", "IceUtil" and "bzip2" (Windows) or "libbz2" (Unix). In
general, these libraries must reside in a directory of the user's
PATH.

For Web servers, the libraries may need to reside in a system
directory. For example, on Linux you can add the directory containing
the Ice run-time libraries to /etc/ld.so.conf and run ldconfig. On
Windows, you can copy the DLLs to the C:\WINDOWS\system32 directory,
or to the Apache installation directory.

You can verify that the Ice extension is installed properly by
examining the output of the "php -m" command, or by calling the
phpinfo() function from a script.

Note that if you want to use IceSSL from the Ice extension, then PHP
will also need access to the shared libraries for IceSSL and OpenSSL.

Finally, the Ice extension will need to execute the Ice preprocessor
(icecpp), therefore this binary must reside in an accessible directory.


======================================================================
SELinux Notes
======================================================================

SELinux augments the traditional Unix permissions with a number of
new features. In particular, SELinux can prevent the httpd daemon from
opening network connections and reading files without the proper
SELinux types.

If you suspect that your IcePHP application does not work due to
SELinux restrictions, we recommend that you first try it with SELinux
disabled. As root, run:

# setenforce 0

to disable SELinux until the next reboot of your computer.

If you want to run httpd with IcePHP and SELinux enabled, you must do
the following:

- Allow httpd to open network connections:

  # setsebool httpd_can_network_connect=1 

  (add the -P option to make this setting persistent across reboots)

- Make sure any .ice file used by your PHP scripts can be read by 
  httpd. The enclosing directory also needs to be accessible. For
  example:

  # chcon -R -t httpd_sys_content_t /opt/MyApp/slice 

For more information on SELinux in Red Hat Enterprise Linux 4, refer
to the link below:

  http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/


======================================================================
Running the Tests
======================================================================

The test subdirectory contains PHP implementations of the core Ice
test suite. In order to run these tests, you must have Python 2.2
or later, and the Ice for C++ tests must be built in the directory
specified by the ICE_HOME environment variable.

The test scripts require that the CLI version of the PHP interpreter
be available in your PATH.

To run all of the tests, do the following:

  > python allTests.py

You can also run tests individually by changing to the test directory
and running this command:

  > python run.py

If everything worked out, you should see lots of "ok" messages. In
case of a failure, the tests abort with "failed".