Installing 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.

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 web server (PHP >= 5 must be
installed on the web server). If not, stop the web server or change
the script location from "@80:/java-server-faces/helloWorld.php" to
"/java-server-faces/helloWorld.php".

- 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. This implementation is
currently 10 times slower than the native, C based implementation. The
INSTALL document located in the source download archive contains
information how to compile the C based implementation for your
operating system version and the java/README document located in the
JavaBridge.war zip file contains information how to install the pure
PHP implementation of the PHP/Java Bridge.


OPTIONAL: Installing PHP into Apache or IIS
-------------------------------------------

All pure Java application server or servlet implementations have the
problem that they cannot directly respond to requests on the HTTP port
number 80; they cannot listen on this port without having admin
privileges and they cannot drop their privileges due to the Java
architecture. Running the entire application server with admin
privileges causes security problems. Therefore it is recommended to
install a native HTTP server with PHP as a front end.

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 PHP/Java Bridge front-end is available as a) a pure PHP component
  or b) as a C based PHP extension. 

* The pure PHP component is currently 10 times slower than the C based
  component, but it is easier to install. See the java/README located in
  the JavaBridge.war zip archive for details.

* 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). 

  If the binary download doesn't contain a PHP executable for your
  operating system, compile a php_java.dll or java.so from the source,
  as described in the INSTALL document located in the source download
  archive.

  NOTE: The pure PHP implementation of the PHP/Java Bridge currently
  does not read the following php.ini entries. The java.hosts and
  java.servlet values are coded in java/Protocol.php, function
  createHttpHandler(), change them accordingly. See java/README for
  details.

* 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.


FAQ
---

Q: In previous versions it was possible to just drop the
JavaBridge.jar and the PHP java dll into the PHP extension
directory. Why isn't this option availablable anmore? Starting a Java
application server just to call out to some Java libraries seems to be
overkill.

A: This is still possible. But since the J2EE component is available,
the standalone component is obsolete. The J2EE component works in a
full featured 1GB application server as well as in a 100K servlet
engine.
