What is the PHP/Java bridge?

The PHP/Java bridge is a PHP module ("java.so" or "php_java.dll") with an associated backend ("JavaBridge.jar", "JavaBridge.war" or "MonoBridge.exe") which connect the PHP object system with the Java or ECMA 335 object system. It implements JSR 223 (where applicable) and can be used to access CLR (e.g. VB.NET, C#) or Java (e.g. Java, KAWA, JRuby) based applications from PHP scripts. The PHP/Java Bridge communicates with the VM through local sockets using an efficient communication protocol. Each request-handling PHP process of a multi-process HTTP server communicates with a corresponding thread spawned by the VM.

Requests from more than one HTTP server may either be routed to an application server running the PHP/Java Bridge or each HTTP server may own a PHP/Java Bridge and communicate with a J2EE java application server by exchanging java value objects; the necessary client-stub classes (ejb client .jar) can be loaded at run-time.

ECMA 335 based classes can be accessed if at least one backend is running inside a ECMA complient VM, for example Novell's MONO or Microsoft's .NET. Special features such as varargs, reflection or assembly loading are also supported.

Clustering and load balancing is available if the backend runs in a servlet environment supporting these features, tomcat 5 for example.

Unlike previous attempts (the ext/java or the JSR223 sample implementation) the PHP/Java Bridge does not use the java native interface ("JNI"). In case a php instance crashes, it will not take down the java application server or servlet engine.

The bridge adds the following primitives to PHP. The type mappings are shown in table 1.


Table 1. Type Mappings

PHPJavaDescriptionExample
objectjava.lang.ObjectAn opaque object handle. However, we guarantee that the first handle always starts with 1 and that the next handle is n+1 for all n < 1024 (useful if you work with the raw XML protocol, see the python and scheme examples).$buf=new java("java.io.ByteArrayOutputStream");
$outbuf=new java("java.io.PrintStream", $buf);
nullnullNULL value$outbuf->println(null);
exact numberlong64 bit integer$outbuf->println(100);
booleanbooleanboolean value $outbuf->println(true);
inexact numberdoubleIEEE floating point$outbuf->println(3.14);
stringbyte[]binary data, unconverted$bytes=$buf->toByteArray();
stringjava.lang.StringAn UTF-8 encoded string. Since PHP does not support unicode, all java.lang.String values are auto-converted into a byte[] (see above) using UTF-8 encoding. The encoding can be changed with the java_set_file_encoding() primitive.$string=$buf->toString();
array (as array)java.util.Collection or T[]PHP4 sends and receives arrays as values. PHP5 sends arrays as values and receives object handles which implement the new iterator and array interface.// pass a Collection to Vector
$ar=array(1, 2, 3);
$v=new java("java.util.Vector", $ar);
echo $v->capacity();

// pass T[] to asList()
$A=new JavaClass("java.util.Arrays");
$lst=$A->asList($ar);
echo $lst->size();
array (as hash)java.util.MapPHP4 sends and receives hashtables as values. PHP5 sends hashtables as values and receives object handles which implement the new iterator interface.$h=array("k"=>"v", "k2"=>"v2");
$m=new java("java.util.HashMap",$h);
echo $m->size();
JavaExceptionjava.lang.ExceptionA wrapped exception class. The original exception can be retrieved with $exception->getCause();...
catch(JavaException $ex) {
echo $ex->getCause();
}


There is one example provided: test.php. You can either invoke the test.php by typing ./test.php or copy the example into the document root of you web-server and evaluate the file using the browser.

The PHP/Java bridge is a replacement for the experimental ext/java bridge shipped with PHP 4. It is not possible to run the build-in bridge and the PHP/Java bridge at the same time.

The module has been tested on a Mandrake Linux System (Version 9.2), on RedHat Enterprise 3, RedHat Fedora Core 1..4, FreeBSD 5.3, Solaris 9 (Sparc, 64 bit JVM) and Windows with RedHat Cygwin, but it should run on all Unix-like operating systems.

Custom java libraries (.jar files) can be stored in the following locations:

  1. Somewhere on a HTTP or FTP server, see PHP function java_require. On Security Enhanced Linux .jar files can only be loaded from locations which are tagged with the lib_t security context.
  2. In the sub-directory "lib" of the PHP extension directory, if it exists and is accessible when the JVM starts the bridge. This is usually "`php-config --extension-dir`/lib". On Security Enhanced Linux this directory is tagged with the lib_t security context.
  3. In the /usr/share/java/ directory, if it exists and is accessible when the JVM starts the bridge. On Security Enhanced Linux this directory is tagged with the lib_t security context.

The PHP/Java Bridge can operate in 4 different modes:

  1. Invoked from the dl() function. In this mode the bridge starts when the HTTP server receives a client request and terminates after the response is written. This is very slow because it starts a new Java VM for each request. But it does not require any administrative privileges.
  2. Permanently activated in the global php.ini file with an internal java process running in the HTTP server domain. In this mode the bridge starts when the HTTP server starts and terminates when the HTTP server terminates. Recommended during development. Please see web server installation below.
  3. Permanently activated in the global php.ini file with an external java process. Recommended for production systems. This mode is used by the RPM package available for RedHat Enterprise Linux. In this mode the bridge starts and stops as a system service.
  4. Permanently activated in the global php.ini file with an external application server or servlet engine.

Furthermore the PHP/Java Bridge can be:



Installation instructions

If you have a RedHat Linux system (RedHat 9, RedHat Enterprise 3 or Fedora), you can download the 32bit RPM and type rpm -i php-java-bridge-v.x.y-z-i386.rpm to install it (if you run a 64bit system and a 64bit JVM you need to install the 64bit RPM instead). For other operating systems please follow the instructions below (on Security Enhanced Linux please use the RPM or please read the README before installation).

Table 2. .ini options

NameDefaultDescriptionExample
java.java_homecompile time option.The java installation directory.java.java_home="/opt/jdk1.5"
java.javacompile time option.The java executable.java.java="/opt/jdk1.5/jre/bin/java"
java.socketname/var/run/.php-java-bridge_socketThe name of the communication channel for the local backend. Must be an integer on windows.java.socketname="9167"
java.log_level1The log level from 0 (log off) to 4 (log debug).java.log_level="3"
java.log_file/var/log/php-java-bridge.logThe log file for the local PHP/Java Bridge backend.java.log_file="/tmp/php-java-bridge.log"
java.hosts<none>Additional bridge hosts which are used when the local backend is not available.java.hosts="127.0.0.1:9168;127.0.0.1:9169"
java.servletOffThe communication protocol. If set to "On", the bridge uses HTTP to communicate with the java.hosts backends.;; Make sure that this option is only set
;; if your backend is deployed in a
;; servlet engine or application server.

java.servlet="On"
java.classpath compile time option.The java classpath. Please do not change the default valuejava.classpath="/tmp/myJavaBridge.jar:/tmp/myCasses/"
java.libpathcompile time option.The directory which contains the natcJavaBridge.so used for local ("unix domain") sockets. Please do not change the default value. java.libpath="/tmp/"


For further information please read the README, INSTALL and INSTALL.WINDOWS documents contained in the download files.



Related