Overview
--------

The PHP/Java Bridge can be installed with two copy operations:

* the JavaBridge.war must be copied into the autodeploy folder of the
  J2EE server and

* the pure PHP PHP/Java Bridge classes or the C-based extension module
  must be copied into the web server document root or into the PHP
  extension directory, respectively.


Install PHP into a pure Java Application Server
-----------------------------------------------

* Install a J2EE application server or servlet engine, for example
  Apache Geronimo, Tomcat 5.5.9, Oracle 10g or WebSphere 6.

* Extract the files from the php-java-bridge J2EE download and deploy
  JavaBridge.war into your J2EE server, example for Tomcat on Unix: 
  
    cp JavaBridge.war $CATALINA_HOME/webapps/

  Example for Apache Geronimo on Windows:

    copy JavaBridge.war "\Program Files\IBM\WebSphereCommunityEdition\deploy"

* Visit http://localhost:<port>/JavaBridge and click on test.php.
  The <port> is 8888 (Oracle), 9080 (WebSphere) or 8080 (Tomcat/Geronimo).

* Please see the README and http://php-java-bridge.sourceforge.net
  for further information.

* Please report bugs/problems to the mailing list:

    php-java-bridge-users@lists.sourceforge.net


Known AS Issues :

- On Windows the php-cgi.exe doesn't support the -b flag. Therefore
either an IIS or Apache front-end or an external PHP "launcher.exe" is
required to run PHP efficiently. IBM Websphere or Apache Geronimo
users can find the "launcher.exe" in the "PHP Integration Kit for
Windows": PHPIntKitForWindows.zip, available from alphaworks.

- If you see a script exception when running
java-server-faces/index.php and the name is displayed as "null", check
if Java can call the PHP script on the external web server (PHP >= 5 must 
be installed on the web server). If not, stop the external web server or 
change the script location from "@80:/java-server-faces/helloWorld.php" 
to "/java-server-faces/helloWorld.php" so that the internal web server
built into your servlet engine or application server is used.

- The JavaBridge.war contains PHP binaries for Linux (x86), Solaris
(x86) and Windows. On other operating systems the PHP binaries are
searched in /usr/bin/php-cgi or c:\php\php-cgi.exe and a pure PHP
implementation of the PHP/Java Bridge is used.


OPTIONAL: Copy the pure PHP classes into an existing PHP Web Server
-------------------------------------------------------------------

* Double-click on test.bat or test.sh. Copy the created "java" folder
  and the test.php over to the document root of your web server.

* Copy the JavaBridge.war into the autodeploy folder of your Application
  Server or servlet engine, as described above.

* Copy your Java libraries (.jar files) into the extension_dir/lib [1]
  directory and your native shared libraries (on windows: dll files)
  into extension_dir [1].

* Visit http://yourHost.com/test.php.

* Please report bugs/problems to the mailing list:

    php-java-bridge-users@lists.sourceforge.net


Known Issues :

- The pure PHP PHP/Java Bridge implementation is currently 10 times
slower than the C implementation described below. Since PHP doesn't
contain a JIT, a "Just In Time" compiler, it is recommended to compile
the bridge to native code, if possible:


OPTIONAL: Install the native, C-based extension
-----------------------------------------------

NOTE: Linux RPMs contain Security Enhanced Linux contexts. If you want
to install software on a SEL system (RHEL, Fedora, ...), please use
the RPM build system instead, see INSTALL.LINUX.

* Install Apache or IIS, if not already installed.

* Install PHP, if not already installed. For example add these lines
  to the end of your Apache2 httpd.conf file:

    LoadModule php5_module "c:/php/php5apache2.dll"
    AddType application/x-httpd-php .php

* The native, C-based PHP extension needs a non-standard PHP "java.so"
  or "php_java.dll" installed on the web server. Check if your PHP
  extension_dir [1] contains this PHP extension. If not, copy the
  appropriate java-<architecture>-<os>.so or
  java-<architecture>-<os>.dll from the JavaBridge.war file to your PHP
  extension directory:

  for PHP >= 4.3.4: php-4-java-<arch>-<os>[.so|.dll]
  for PHP >= 5.0.0: php-5.0-java-<arch>-<os>[.so|.dll]
  for PHP >= 5.1.0: java-<arch>-<os>[.so|.dll]
  ...
  
  Rename it to java.so (Unix) or php_java.dll (Windows). 

  Please see the INSTALL document located in the source download
  archive for information how to compile a php_java.dll or java.so from
  the source.

* Check if the java .ini [2] entry loads the java extension and
  connects php to the servlet or J2EE back-end, e.g.:
  
    extension = java.so
    ; extension = php_java.dll
    [java]
    java.hosts   = 127.0.0.1:8080 ;or 8888 for Oracle, 9080 for WebSphere
    java.servlet = User

* Check if the HTTP document root directory is shared with the AS
  "webapps" directory. If not, change the java.servlet option to "On":

    extension = java.so
    ; extension = php_java.dll
    [java]
    java.hosts   = 127.0.0.1:8080 ;or 8888 for Oracle, 9080 for WebSphere
    java.servlet = On

  Then re-start Apache or IIS and check "java status" and "java server":

    http://yourHost.com/<userContext>/test.php

  e.g.:

    http://yourHost.com/JavaBridge/test.php

* On production systems set the following flags in your php ini file [2]
  so that the back-end can generate standard error pages.

    log_errors     = On
    display_errors = Off
    html_errors    = Off

* Copy your Java libraries (.jar files) into the extension_dir/lib [1]
  directory and your native shared libraries (on windows: dll files)
  into extension_dir [1].

* Please report bugs/problems to the mailing list:

    php-java-bridge-users@lists.sourceforge.net

---
[1] The extension_dir is the PHP extension directory, usually
/usr/lib/php/modules or c:\php on windows. It can be set in the php
.ini file [2] with (example): extension_dir="d:/php".

[2] The php .ini file is the global PHP configuration file, usually
/usr/local/lib/php.ini or /etc/php.d/java.ini or c:\windows\php.ini or
c:\winnt\php.ini.
