Installation on RedHat Linux (RHEL, Fedora, ...)
-------------------------------------------------

* Install a J2RE, for example with the command[1]:
  rpm -i jdk-1_5_0-linux-i586.rpm 

* Install PHP, for example with the command: 
  rpm -i php-4.3.2-8.ent.i386.rpm

* Install the web-server, for example with the command:
  rpm -i httpd-2.0.46-25.ent.i386.rpm

* Install the php-java-bridge, for example with the command:
  rpm -i php-java-bridge-X.Y.Z-1.i386.rpm

* If you have SECURITY ENHANCED LINUX, the above command should have
  provided instructions how to install the php-java-bridge.te and
  php-java-bridge.fc policy files.

Start the web-server with the command: service httpd restart.
Start the bridge with the command: service php-java-bridge restart

Create a simple php file in /var/www/html, for example with
the command: echo "<?php phpinfo(); ?>" >/var/www/html/phpinfo.php.

Browse to http://localhost/phpinfo.php and search for the 
output of the php java bridge module (the entry should be: 
"java.support: Enabled").

Then install your your java libraries (.jar files) in /usr/share/java
or in java.libpath/lib (see output of phpinfo) and your php and
web-pages in /var/www/html or one of their sub-directories.

[1] 
On RHEL3 use the RPM from CD#9: IBMJava2-JRE-1.4.1-8.i386.rpm 
it provides "j2re" instead of "jre".



Installation from source code (Solaris, FreeBSD, WinXP or Linux)
----------------------------------------------------------------

NOTE: 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 (rpmbuild --rebuild php-java-bridge*src.rpm).
However, for a development system you can switch off SEL and follow
the instructions below.


The following software components must be installed on your computer:

* an operating system. For example RedHat Enterprise Linux. If you
  build on Solaris, FreeBSD/MacOSX or WinXP, you also need the GNU
  toolchain (gcc, gnu make, autoconf etc.).

* a Java VM. For example IBM JDK 1.4.1 or GNU Java version 3 or above.

* optional: Oracle 9i/10g AS or IBM WebSphere 5/6.


The following instructions build the components:

* the apache web-server

* PHP as a apache module

* the PHP/Java Bridge as a PHP module and/or as a J2EE
  component (plugin) for IBM WebSphere or Oracle AS.

and optionally, if you want to run JSP and PHP from Apache/Tomcat:

* mod_jk with Apache/Tomcat.


# adjust the install directory
INST=/usr/local #INST=$HOME/bridge

# remove all old files under $INST
#rm -rf $INST

# set build path
export PATH=$INST/bin:$PATH 
export LD_LIBRARY_PATH=$INST/lib:$LD_LIBRARY_PATH

# stop the system http service 
su - -c "service httpd stop"

# adjust the java version
JAVA_HOME=/opt/IBMJava2-141

# The following software components are required during the build
# process: autoconf 2.57, automake 1.6.3 and libtool 1.4.3. If you
# don't have autoconf >= 2.57, automake >= 1.6.3 libtool >= 1.4.3, or
# versions which do not match, for example autoconf 2.59 and libtool
# 1.4.3, you must REMOVE THE OLD VERSIONS and compile and install
# these before proceeding:

(cd autoconf-2.57;  ./configure --prefix=$INST && make && su -c "make install")
(cd automake-1.6.3; ./configure --prefix=$INST && make && su -c "make install")
(cd libtool-1.4.3;  ./configure --prefix=$INST && make && su -c "make install")


#
# BUILD APACHE
# adjust apache MPM.  Prefork is standard behaviour in apache 1.3, worker
# creates worker thread pools which deliver content much faster.  But note:
# some third-party PHP modules may not be thread-safe.
#
MPM=prefork #MPM=worker

# compile and install apache 2
gunzip < httpd-2.x.y.tar.gz | tar xf -
cd httpd-2.x.y
./configure --with-mpm=$MPM --enable-module=so --prefix=$INST
make && su -c "make install"
cd ..


#
# BUILD PHP
#
bunzip2 < php-x.y.z.tar.bz2 | tar xf -
cd php-x.y.z
./configure --prefix=$INST --without-java --with-apxs2=$INST/bin/apxs
make && su -c "make install"
# now activate php in the httpd.conf
su -c "echo 'AddType application/x-httpd-php .php' >>$INST/conf/httpd.conf"
cd ..


#
# BUILD THE PHP/JAVA BRIDGE
#
bunzip2 < php-java-bridge_p.x.y.tar.bz2 | tar xf -
cd php-java-bridge-p.x.y
phpize
./configure --with-java=$JAVA_HOME
make && su -c "make install"
# now activate the bridge in php.ini
su -c "touch $INST/lib/php.ini && echo -e 'extension=java.so\n[java]' >>$INST/lib/php.ini"
cd ..

# TEST
# create a file phpinfo.php in the document root directory 
# of apache and start the http service
su -c "echo '<?php phpinfo() ?>' >$INST/htdocs/phpinfo.php; chmod +xr $INST/htdocs/phpinfo.php; apachectl restart"

# checking cli, should return "java running"
echo '<?php phpinfo() ?>' | php | fgrep java

# checking web, should return "java running"
wget -olog -O-  http://localhost/phpinfo.php|fgrep java

If the above test succeeded, copy the files "java.so",
"libnatcJavaBridge.so" and "JavaBridge.jar" (on Windows: php_java.dll
and JavaBridge.jar) to the extension_dir of your system php
installation and start the system http service again.

If something went wrong, for example if you have forgotten to set
JAVA_HOME or if configure failed because the installed autoconf
version is too old, you can only remove the build directory and start
from the beginning; removing the autom4te cache directories from the
build directory may be enough sometimes, but not always.



------------------------------------
Installation of Tomcat/mod jk
-----------------------------

Optionally you can install the tomcat servlet engine to serve .jsp
files

Download and extract tomcat into a directory, for example /opt/tomcat5
and set the environment variable CATALINA_HOME, for example:

export CATALINA_HOME=/opt/tomcat5


Download and install mod jk, for example
jakarta-tomcat-connectors-1.2.14.1-src.tar.gz, extract the file into a
folder and type the following commands:

cd jakarta-tomcat-connectors-1.2.14.1-src/jk/native/
./configure --with-apxs=$INST/bin/apxs && make && su -c "make install"

# now activate mod_jk in the httpd.conf, mount the tomcat webapps
# directory and ask tomcat to handle all .jsp files
su -c "echo -e 'LoadModule jk_module modules/mod_jk.so\nJkAutoAlias $CATALINA_HOME/webapps\nJkMount /JavaBridge/*.jsp ajp13\nJkMount /JavaBridge/ ajp13' >>$INST/conf/httpd.conf"

Start tomcat, for example with the command:

$CATALINA_HOME/bin/catalina.sh start


Copy the JavaBridge.war file (which you should have created when
compiling the PHP/Java Bridge, see flag "--enable-servlet" above) from
the modules directory into the tomcat webapps directory, for example
with the command:

cp modules/JavaBridge.war $CATALINA_HOME/webapps

Check if tomcat has created the $CATALINA_HOME/webapps/JavaBridge
directory, if not, please check the tomcat logs for errors.

Direct php to tomcat:
su -c "echo -e 'extension=java.so\n[java]\njava.servlet=User\njava.hosts=127.0.0.1:8080' >$INST/lib/php.ini"

Start or re-start apache, for example with:
su -c "apachectl restart"

Visit http://localhost/JavaBridge and run the supplied examples.

The php .ini file [java] section should contain only java.log_level,
java.servlet and java.hosts entries.  Example:

       [java]
       java.log_level="2"
       java.servlet=User
       java.hosts="127.0.0.1:8080"

The PHP/Java Bridge log output appears in the server log file, for
example in $CATALINA_HOME/logs/localhost_log.*.txt

------------------------------------
Oracle 10g AS
-------------

  The following description assumes that you have the Oracle
  Application Server Containers for J2EE 10g installed, for example in
  /opt/10gAS and that the $J2EE_HOME points to the /opt/10gAS/j2ee/home
  directory.

  If you want to download the Oracle 10g AS, please only download the
  pure java implementation called "oc4j_extended.zip". It has a download
  size of less than 30MB. The complete Oracle 10g AS has a download size
  of more than 1GB and includes Apache and other software you don't need
  during development.

  Install the PHP/Java Bridge and copy the JavaBridge.war to the
  $J2EE_HOME/applications directory.

  Edit $J2EE_HOME/config/application.xml so that it contains the
  following line:

    <web-module id="JavaBridge" path="../../home/applications/JavaBridge.war"/>

  Edit $J2EE_HOME/config/http-web-site.xml so that it contains the
  following line:

    <web-app application="default" name="JavaBridge" root="/JavaBridge"/>


  Start the Oracle 10g application server, for example with:

    cd $J2EE_HOME
    java -jar oc4j.jar

  Run the PHP/Java Bridge examples, for example:

    http://localhost:8888/JavaBridge/test.php

  or 

    http://localhost:8888/JavaBridge/sessionSharing.php

  If there are problems, please check if oracle has created the
  $J2EE_HOME/applications/JavaBridge directory and read
  $J2EE_HOME/applications/JavaBridge/WEB-INF/cgi/README.

  The log output appears in $J2EE_HOME/log/global-application.log.


  For production systems it is recommended to install the complete
  Oracle Application Server, which includes Apache, and to install
  PHP as a Apache module.

------------------------------------
IBM WebSphere AS
----------------

  The following description assumes that you have the IBM WebSphere
  6.x Application Server installed and that $WAS_HOME points to the
  /opt/IBM/WebSphere/AppServer directory.

  Install the PHP/Java Bridge. Start the application server, for
  example with the command:

    $WAS_HOME/bin/startServer.sh  server1

  Log into your application server, for example via: 

    http://localhost:9060/ibm/console/secure/logon.do

  Click on Applications -> Install New Application -> Browse
  and select JavaBridge.war. 

  Enter /JavaBridge as "Context root" and click Next.
  Click Next
  Click Continue
  Click Next
  Select JavaBridge.war and click Next
  Select JavaBridge.war and click Next
  Click Finish
  Click on "Save to Master Configuration"
  Click Save

  Click on Applications -> Enterprise Applications and select JavaBridge.war
  Click Start
  
  Run the PHP/Java Bridge examples, for example:

    http://localhost:9080/JavaBridge/test.php

  or 

    http://localhost:9080/JavaBridge/sessionSharing.php

  If there are problems, please check if websphere has created the
  $WAS_HOME/profiles/default/installedApps/[...]/JavaBridge_war.ear/
  directory and read
  $WAS_HOME/[...]/JavaBridge_war.ear/JavaBridge.war/WEB-INF/cgi/README.

  The log output appears in the
  $WAS_HOME/profiles/default/logs/server1/ directory.


  For production systems it is recommended to install the IBM
  HttpServer (a Apache variant) and to install PHP as a Apache
  module.

---------------------------------------------
Compiling the bridge without autoconf
-------------------------------------

Follow these instructions to create a java.so or php_java.dll on
systems which don't have autoconf or if ./configure fails (because the
installed autoconf scripts are too old).

To create a windows php_java.dll you'll need:

* A Unix machine with a C cross compiler, for example
  386-pc-mingw32-gcc

* the standard windows includes in the ./include directory

* the MINGW includes in the ./include directory

* the php5ts.dll in the $PHP directory

* the configured php4 or php5 source distribution in the $PHP
  directory


To create a unix java.so you'll need:

* A unix machine with a C compiler

* the standard unix includes in the /usr/include directory

* the configured php4 or php5 source distribution in the $PHP
  directory


cd to the php-java-bridge* directory and type the following commands:

BRIDGE_VERSION="`cat ./VERSION`"
PHP_JAVA=""
COND_GCJ=0
EXTENSION_NAME=JAVA

# The java executable on windows or unix
#PHP_JAVA_BIN="javaw"
PHP_JAVA_BIN="java"

# The extension_dir on windows or unix
#EXTENSION_DIR="c:/php5"
EXTENSION_DIR="."

# The configured PHP directory, this directory must contain
# the php4ts or php5ts shared library and the header files
#PHP="../php-5.0.3"
PHP="../php-4.4.0"

# The directory which contains the system include files
# for windows (+MINGW include files) or unix
#SYS_INCLUDE="../include"
SYS_INCLUDE="/usr/include"

# The (cross-) compiler for windows or unix
#GCC=386-pc-mingw32-gcc
GCC=gcc

# create init_cfg.h and init_cfg.c
for i in init_cfg.c init_cfg.h; do 
sed "s*@PHP_JAVA@*${PHP_JAVA}*
s*@COND_GCJ@*${COND_GCJ}*
s*@PHP_JAVA_BIN@*${PHP_JAVA_BIN}*
s*@EXTENSION@*${EXTENSION_NAME}*
s*@BRIDGE_VERSION@*${BRIDGE_VERSION}*" \
<./${i}.in >./${i}
done

#compile command for windows (with ZTS)...
#$GCC -w -I$SYS_INCLUDE -I. -I$PHP -I$PHP/main -I$PHP/Zend -I$PHP/TSRM -D"TSRM_EXPORTS" -D"LIBZEND_EXPORTS" -D"ZTS" -D"_MBCS" -DCOMPILE_DL_JAVA -DCFG_JAVA_SOCKET_INET -DEXTENSION_DIR=\"$EXTENSION_DIR\" -c *.c

# ... or unix (without ZTS)
$GCC -w -I$SYS_INCLUDE -I. -I$PHP -I$PHP/main -I$PHP/Zend -I$PHP/TSRM -D"_MBCS" -DCOMPILE_DL_JAVA -DCFG_JAVA_SOCKET_INET -DEXTENSION_DIR=\"$EXTENSION_DIR\" -c *.c

#create the windows .dll or the unix .so file
#i386-pc-mingw32-dllwrap  --export-all-symbols -k  *.o -L$PHP -lphp5ts -lws2_32 -o php_java.dll
$GCC -shared  *.o  -Wl,-soname -Wl,java.so -o java.so

------------------------------------
Compiling a CGI binary on Windows
---------------------------------

  This operating system has some unusal problems with shared libraries
  (DLL's). The autoconf/libtool documentation states:

   - Macro: AC_LIBTOOL_WIN32_DLL
     This macro should be used if the package has been ported to build
     clean dlls on win32 platforms.  Usually this means that any
     library data items are exported with `__declspec(dllexport)' and
     imported with `__declspec(dllimport)'.  If this macro is not used,
     libtool will assume that the package libraries are not dll clean
     and will build only static libraries on win32 hosts.

  Until someone ports the sources to use __declspec, we avoid 
  creating shared libraries on this system.  Instead we will
  compile the extension into PHP:

  1. Install the source code of PHP 4.3.x or higher.

  2. Install RedHat's Cygwin (PHP needs autoconf).

  3. Delete the java sub-directory from php-4.3.x\ext. Copy the
     php-java-bridge directory to the php-x.y.z\ext directory and
     rename it to java.  Update the "m4_include" paths in
     php-x.y.z\ext\java\config.m4 so that they start with "ext/java/":

      m4_include(ext/java/tests.m4/function_checks.m4)
      m4_include(ext/java/tests.m4/java_check_broken_stdio_buffering.m4)
      ...
      m4_include(ext/java/tests.m4/java_check_broken_gcc_installation.m4)

  4. Invoke autoconf to register our java module within the PHP build
     tree:
 
      buildconf.bat --force 

     Instead of running "buildconf" you can also use autoconf directly:

      autoconf

     Then configure and compile php as usual:

      .\configure --with-java=%JAVA_HOME%
      make

  This will create a php binary with the PHP/Java Bridge included.
  You can then copy the sapi\cgi\php executable into the CGI directory 
  of your IIS web server. Before you start the web server, you must
  start the java bridge backend, for example by double-clicking on
  .\modules\JavaBridge.jar.


  Windows uses TCP/IP sockets instead of unix domain sockets. If you
  want to change the java.socketname from its default (which is 9267),
  you must use an integer. For example:

    java.socketname=9268

