What is the PHP/Java Bridge?

The PHP/Java Bridge is an optimized, XML-based network protocol, which can be used to connect a native script engine with a Java or ECMA 335 virtual machine. It is more than 50 times faster than local RPC via SOAP, requires less resources on the web-server side, and it is faster and more reliable than a communication via the Java Native Interface.

The Java/.NET libraries can be called from any PHP implementation by opening a socket connection to the VM and by sending PHP/Java Bridge protocol requests:

<?php
class Protocol {
  const Pc='<C v="%s" p="I">', PC='</C>';
  const Pi='<I v="%d" m="%s" p="I">', PI='</I>';
  const Ps='<S v="%s"/>', Pl='<L v="%d" p="%s"/>', Po='<O v="%d"/>';
  var $c;
  
  function __construct() { $this->c=fsockopen("127.0.0.1",9267); fwrite($this->c, "\177@"); }

  function createBegin($s) { fwrite($this->c, sprintf(self::Pc, $s)); }
  function createEnd() { fwrite($this->c, self::PC); }

  function invokeBegin($o, $m) { fwrite($this->c, sprintf(self::Pi, $o, $m)); }
  function invokeEnd() { fwrite($this->c, self::PI); }

  function writeString($s) {fwrite($this->c, sprintf(self::Ps, $s));}
  function writeInt($s) { fwrite($this->c, sprintf(self::Pl, $s<0?-$s:$s, $s<0?"A":"O")); }
  function writeObject($s) { fwrite($this->c, sprintf(self::Po, $s->java)); }
  function writeVal($s) {
    if(is_string($s)) $this->writeString($s);
    else if(is_int($s)) $this->writeInt($s);
    else $this->writeObject($s);
  }

  function getResult() { $res = fread($this->c, 8192); $ar = sscanf($res, '%s v="%[^"]"'); return $ar[1]; }
}

function getProtocol() { static $protocol; if(!isset($protocol)) $protocol=new Protocol(); return $protocol; }

class Java {
  var $java;
  function __construct() {
    if(!func_num_args()) return;
    $protocol=getProtocol();
    $ar = func_get_args();
    $protocol->createBegin(array_shift($ar));
    foreach($ar as $arg) { $protocol->writeVal($arg); }
    $protocol->createEnd();
    $ar = sscanf($protocol->getResult(), "%d");
    $this->java=$ar[0];
  }
  function __call($method, $args) {
    $protocol=getProtocol();
    $protocol->invokeBegin($this->java, $method);
    foreach($args as $arg) { $protocol->writeVal($arg); }
    $protocol->invokeEnd();
    $proxy = new Java();
    $ar = sscanf($protocol->getResult(), "%d");
    $proxy->java=$ar[0];
    return $proxy;
  }
  function toString() {
    $protocol=getProtocol();
    $protocol->invokeBegin("", "castToString");
    $protocol->writeVal($this);
    $protocol->invokeEnd();
    return $protocol->getResult();
  }
}
// Test
$i1 = new Java("java.math.BigInteger", "1");
$i2 = new Java("java.math.BigInteger", "2");
$i3 = $i1->add($i2);
echo $i3->toString() . "\n";
?>


Furthermore PHP classes can be created from Java libraries and be installed in the PHP PEAR include_path. For example the following command translates the Java library lucene.jar into PHP and installs it into the /usr/share/pear/lucene directory:

java -jar JavaBridge.jar --convert /usr/share/pear lucene.jar

PHP code can call all public Java methods or procedures and examine all public fields. All public PHP procedures can be called from Java, all PHP classes may implement Java interfaces and PHP objects may be passed to Java procedures or methods. Example:

<?php
require_once("lucene/org_apache_lucene_search_IndexSearcher.php");
require_once("lucene/org_apache_lucene_search_PhraseQuery.php");
require_once("lucene/org_apache_lucene_index_Term.php");

$searcher = new org_apache_lucene_search_IndexSearcher(getcwd());
$term = new org_apache_lucene_index_Term("name", "test.php");
$phrase = new org_apache_lucene_search_PhraseQuery();

$phrase->add($term);

$hits = $searcher->search($phrase);
$iter = $hits->iterator();

while($iter->hasNext()) {
  $next = $iter->next();
  $name = $next->get("name");
  echo "found name: $name\n";
}
?>

Java knowledge is not necessary and it is neither necessary nor recommended to write custom- or glue logic in the Java programming language.

The following sections describe the low-level interface provided by the PHP/Java Bridge implementations.

Description

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

• new Java("CLASSNAME"): References and instantiates the class CLASSNAME. After script execution the referenced classes may be garbage collected. Example:
  
  

  <?php
$v = new Java("java.util.Vector");
$v->add($buf=new Java("java.lang.StringBuffer"));
$buf->append("100");
echo (int)($v->elementAt(0)->toString()) + 2;
?>


  
  
• new JavaClass("CLASSNAME"): References the class CLASSNAME without creating an instance. The returned object is the class object itself, not an object of the class. After script execution the referenced classes may be garbage collected. Example:
  
  

  $Object = new JavaClass("java.lang.Object");
$obj = $Object->newInstance();

$Thread = new JavaClass("java.lang.Thread");
$Thread->sleep(10);



  
  
• java_require("JAR1;JAR2"): Makes additional libraries available to the current script. JAR can either be a "http:", "ftp:", "file:" or a "jar:" or a default location. On "Security Enhanced Linux" (please see the README) the location must be tagged with a lib_t security context. Example:
  
  // load scheme interpreter
// try to load it from /usr/share/java/ or from sourceforge.net
try { java_require("kawa.jar"); } catch (JavaException $e) {/*ignore*/}
java_require("http://php-java-bridge.sourceforge.net/kawa.jar");
$n=100;
$System = new JavaClass("java.lang.System");
$t1 = $System->currentTimeMillis();
$code="(letrec ((f (lambda(v) (if (= v 0) 1 (* (f (- v 1)) v))))) (f $n))";
$scheme = new java("kawa.standard.Scheme");
$res=(float)$scheme->eval($code);
echo "${n}! => $res\n";
$delta = $System->currentTimeMillis() - $t1;
echo "Evaluated in $delta ms.\n";

  
  
• java_context(): Makes the javax.script.ScriptContext available to the current script. All implicit web objects (session, servlet context, etc.) are available from the context, if the back end is running in a servlet engine or application server. The following example uses the jdk1.6 jrunscript to eval PHP statements interactively:
  
  /opt/jdk1.6/bin/jrunscript -l php-intractive
php-interactive> echo (string)(java_context()->getAttribute("javax.script.filename"));
=> <STDIN>


  
• java_values(JAVA_OBJECT): Fetches the values for JAVA_OBJECT, if possible. Examples:
  
  

  $str = new java("java.lang.String", "hello"); echo $str;
=> [o(String):"hello"]

// fetch the php string from the java string
echo (java_values($str));
=> hello

// fetch the values of the java char array
print_r (java_values($str->toCharArray()));
=> array('h', 'e', 'l', 'l', 'o')

// no php type exists for java.lang.Object
print (java_values(new java("java.lang.Object")));
=> [o(Object):"java.lang.Object@4a85fc"]

  
  
• java_cast(JAVA_VALUE, php_type): Converts a primitive JAVA_VALUE to a php value of type php_type. Unlike java_values, which return the "natural" php value for the JAVA_VALUE, the cast can convert the JAVA_VALUE into the desired php_type before it is returned. Allowed conversions are "string", "boolean", "integer" or "long", "double" or "float", "null", "array" and "object". The "object" conversion is the identiy function. Since PHP5 (php_type)JAVA_VALUE is identical to java_cast(JAVA_VALUE, php_type) (Zend Engine 2 and above only). Examples:
  
  

  $str = new java("java.lang.String", "12"); echo $str;
=> [o(String):"12"]

// fetch the php string from the java string
echo java_cast($str, "string");
=> "12"

echo java_cast($str, "integer" );
=> 12

var_dump (java_cast($str, "boolean"));
=> true

  
  
• java_begin_document() and java_end_document(): Enables/disables XML stream mode. In XML stream mode the PHP/Java Bridge XML statements are sent in one XML stream. Compared with SOAP, which usually creates the entire XML document before sending it, this mode uses much less resources on the web-server side. Raised server-side exceptions are reported when java_end_document() is invoked. Example:
  
  

  // send the following XML statements in one stream
java_begin_document();
for ($x = 0; $x < $dx; $x++) {
  $row = $sheet->createRow($x);
  for ($y = 0; $y < $dy; $y++) {
    $cell = $row->createCell($y);
    $cell->setCellValue("$x . $y");
    $cell->setCellStyle($style);
  }
}
java_end_document(); // back to synchronous mode


  
  
• java_closure(ENVIRONMENT, MAP, TYPE): Makes it possible to call PHP code from Java. It closes over the PHP environment, packages it up as a java class and returns an instance of the class. If the ENVIRONMENT is missing, the current environment is used. If MAP is missing, the PHP procedures must have the same name as the required procedures. If TYPE is missing, the generated class is "generic", i.e. the interface it implements is determined when the closure is applied. Example:
  
  

  <?php
function toString() { return "hello" ; }
echo (string)java_closure();
?>
=> hello

  
  
• $session=java_session(): Creates or retrieves a session context. When the back end is running in a J2EE environment, the session is taken from the request object, otherwise it is taken from PHP. Please see the ISession interface documentation for details. The java_session() must be called before the response headers have been sent and it should be called as the first statement within a PHP script.

  $session = java_session(); $servletRequest = $session->getHttpServletRequest();
$servletRequest->setAttribute(...);
...


  
  
• $session=java_session(SESSIONNAME): Creates or retrieves the session SESSIONNAME. This primitive uses a session store with the name SESSIONNAME which is independent of the current PHP- or Java session. Please see the ISession interface documentation for details. For Java values $_SESSION['var']=val is syntactic sugar for java_session("internal-prefix@".session_id())->put('var', val).

  $session=java_session("testSession");
if($session->isNew()) {
   echo "new session\n";
   $session->put("a", 1);
   $session->put("b", 5);
} else {
   echo "cont session\n";
}
$session->put("a", $session->get("a")+1);
$session->put("b", $session->get("b")-1);

$val=$session->get("a");
echo "session var: $val\n";

if($session->get("b")==0) $session->destroy();


  The java_session primitive is meant for values which must survive the current script. If you want to cache data which is expensive to create, bind the data to a class. Example:

  // Compile this class, create cache.jar and copy it to /usr/share/java
public class Cache {
   private static final Cache instance = makeInstance();
   public static Cache getInstance() { return instance; }
}

<?php
java_require("cache.jar");
$Cache = new JavaClass("Cache");
$instance=$Cache->getInstance(); //instance will stay in the VM until the VM runs short of memory
?>


  
  
• JavaException: A java exception class. Available in PHP 5 and above only. Example:
  
  

  try {
  new java("java.lang.String", null);
} catch(JavaException $ex) {
   $exStr = java_cast($ex, "string");
   echo "Exception occured; mixed trace: $exStr\n";
   $trace = new java("java.io.ByteArrayOutputStream");
   $ex->printStackTrace(new java("java.io.PrintStream", $trace));
   print "java stack trace: $trace\n";
}


  The original exception can be retrieved with $ex->getCause(), for example:

  function rethrow($ex) {
  static $NullPointerException=new JavaClass("java.lang.NullPointerException");
  $ex=$ex->getCause();
  if(java_instanceof($ex, $NullPointerException)) {
    throw new NullPointerException($ex);
  }
  ...
  die("unexpected exception: $ex");
}


  
  
• foreach(COLLECTION): It is possible to iterate over values of java classes that implement java.util.Collection or java.util.Map. Available in PHP 5 and above only. Example:
  
  

  $conversion = new java("java.util.Properties");
$conversion->put("long", "java.lang.Byte java.lang.Short java.lang.Integer");
$conversion->put("boolean", "java.lang.Boolean");
foreach ($conversion as $key=>$value)
   echo "$key => $value\n";


  
  
• [index]: It is possible to access elements of java arrays or elements of java classes that implement the java.util.Map interface. Available in PHP 5 and above only. Example:
  
  

  $Array = new JavaClass("java.lang.reflect.Array");
$String = new JavaClass("java.lang.String");
$entries = $Array->newInstance($String, 3);
$entries[0] ="Jakob der Lügner, Jurek Becker 1937--1997";
$entries[1] ="Mutmassungen über Jakob, Uwe Johnson, 1934--1984";
$entries[2] ="Die Blechtrommel, Günter Grass, 1927--";
for ($i = 0; $i < $Array->getLength($entries); $i++) {
   echo "$i: " . $entries[$i] ."\n";
}


  
  
• java_instanceof(JAVA_OBJ, JAVA_CLASS): Tests if JAVA_OBJ is an instance of JAVA_CLASS. Example:
  
  

  $Collection=new JavaClass("java.util.Collection");
$list = new java("java.util.ArrayList");
$list->add(0);
$list->add(null);
$list->add(new java("java.lang.Object"));
$list->add(new java("java.util.ArrayList"));
foreach ($list as $value) {
   if($value instanceof java && java_instanceof($value, $Collection))
     /* iterate through nested ArrayList */
   else
     echo "$value\n";
}


  
  
• java_last_exception_get(): Returns the last exception instance or null. Since PHP 5 you can use try/catch instead.
  
  
• java_last_exception_clear(): Clears the error condition. Since PHP 5 you can use try/catch instead.

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.

Installation instructions

If you have a Unix, Windows or Linux system, download either the binary or the source and install it.

Installation on Linux

• Download and install J2SE >= 1.6 or J2EE >= 1.4.

• Download and install PHP >= 5.1.4 or the pure Java implementation of PHP. If you want to use PHP < 5.1.4, you need to compile a "java.so" or "php_java.dll" extension, see the README and INSTALL document for details.

• Download and extract the PHP/Java Bridge zip file into a folder.

• Right-click on "JavaBridge.war" and select "Open with Java ...", this creates two directories: "ext", "java" and a file "test.php".

• Move the created "java" folder to the web server document root.

• Copy the "JavaBridge.war" file to the autodeploy folder of your J2EE server. Or, if use don't want to use J2EE, open the "ext" folder, right-click on "JavaBridge.jar" and select "Open with Java ..."; in the following dialog box click "OK". Use java -jar JavaBridge.jar --help for more information.

• Copy the file "test.php" to the web server document root and browse to test.php.

• Java libraries can be installed in a sub-directory of extension_dir/lib, see output from "test.php", or be packaged with the "JavaBridge.war" web component.

Further information

For further information please read the README, INSTALL, INSTALL.LINUX, INSTALL.J2EE, INSTALL.J2SE, INSTALL.WEBSPHERE, INSTALL.ORACLE documents contained in the download files.

The NEWS file lists the latest user visible changes, development documentation can be found in the documentation and server/documentation folder.

FAQ

• The "C" extension doesn't compile on my system!?!

  Please follow the instructions from the INSTALL document as close as possible. In particular the back end needs the specified versions of GNU autoconf, GNU libtool and GNU automake in the path. Don't try to re-use specialized versions which came with your operating system (e.g. symlink libtool-1.5 to libtool), this will not work; if you don't have autoconf 2.59, automake 1.9 and libtool 1.5.20, you must compile and install them, as described in the INSTALL document. If there are problems compiling the bridge code against any PHP version >= 4.3.4 on Windows, Linux/Unix or MacOS, please do not report this problem to the mailing list. Please open a problem report instead (you don't need an account to submit a problem report).

  If Java or Mono is not installed on the build machine, the back end compilation can be switched off with the --disable-backend configure option. A compiled, platform-independent back end ("JavaBridge.war") can be found in the download folder.

  On RPM based Security Enhanced Linux installations (RHEL, Fedora) please install one of the binary RPMs or compile a binary RPM from the source RPM using the command: rpmbuild --rebuild php-java-bridge*src.rpm and install it.

  On recent Debian installations, Ubuntu for example, a binary package can be created with the command: fakeroot debian/rules binary.

  If everything else fails, use the pure PHP implementation of the PHP/Java Bridge.

• Can I use java libraries without installing java?

  Yes. Simply ommit the --with-java= configure option. The bridge will use the libgcj library, which is part of the GNU gcc compiler. This library also uses much less system resources (memory, files) than a "real" Java VM.

• Does the bridge run native code within my servlet engine or application server?

  No. The bridge back end is written in pure java, it doesn't use any native code. Native PHP runs within Apache, IIS, a FCGI server or via CGI. If the PHP instance crashes, an error page is returned to the client and the Apache, IIS, CGI container usually starts a new PHP instance for the next request.

• How do I make my script state (objects or variables) persistent?

  If you must code it yourself: with e.g. java_session()->put("buf", $stringBuffer) or via $_SESSION["buf"]=$stringBuffer. The $_SESSION is syntactic sugar provided by the php session module, it uses java_session() internaly. If you don't want depend on the PHP session module, for example if you have compiled PHP without the session.so, use java_session() instead.

  If you use the Java Server Faces framework, you declare the scope of the script in the PHP managed bean descriptor. For example, if the managed-bean-scope is changed from request to session, the framework automatically saves the state of the PHP script instance and restores it when the next request belonging to the same session comes in.

• How many threads does the bridge start?

  Request-handling threads are started from a thread pool, which limits the number of user requests to 20 (default), see system property php.java.bridge.threads. All further requests have to wait until one of the worker threads returns to the pool.

  When running in a servlet engine, a ContextServer is started which handles the pipe or local socket communication channel.

  When java invokes local scripts outside of a HTTP environment, the bridge starts a HttpServer, a ContextServer and a HttpProxy. The HttpProxy represents the PHP continuation and the HttpServer the request-handling java continuation associated with the JSR223 script.

• How do I lock down the VM so that users cannot start threads or call System.exit?

  Usually with a java policy file. An example file has been installed in the php extension directory and can be enabled with: java.security_policy=On

• Where is my output?

  System.out and System.err are redirected to the server log file(s). When PHP scripts are invoked from a java framework (Java Server Faces for example), even the PHP output is redirected. For the standalone back end the output appears in the /var/log/php-java-bridge.log or in JavaBridge.log, see .ini option java.log_file. For the j2ee back end the location of the log file(s) depends on the j2ee server configuration.

• How do I access enums or inner classes?

  With the classname$inner syntax. For example
  
  public interface php {
  public class java {
    public enum bridge {JavaBridge, JavaBridgeRunner};
  }
}

  can be accessed with:
  
  <?php
java_require(getcwd()); // load php.class
$bridge = new java('php$java$bridge');
echo $bridge->JavaBridgeRunner;
?>

  The above code is not a good programming example but it demonstrates why a different syntax is used to access inner classes.

• How do I create a primitive array?

  Primitive types are wrapped by associated java classes. The following example uses reflect.Array to create a new byte array:
  
  $Byte = new JavaClass("java.lang.Byte");
$byte = $Byte->TYPE;
$Array = new JavaClass("java.lang.reflect.Array");
$byteArray = $Array->newInstance($byte, 255);
$System = new JavaClass("java.lang.System");
$length = $System->in->read($byteArray);
$str = new Java("java.lang.String", $byteArray, 0, $length);
echo "You have typed: $str\n";


• How fast is it?

  The following scripts were executed on one 1.688 GHZ x86 cpu running RedHat Fedora Core 4 Linux and Sun jdk1.6.0:

  The PHP 5.1.2 code
  

  <?php
$String = new JavaClass("java.lang.String");
$buf=new java("java.lang.StringBuffer");

$i=0;
java_begin_document();
while($i<400000) {
    $i=$i+1;
    $buf->append(new java("java.lang.String", $String->valueOf($i)));
}
java_end_document();

print $buf->length() . "\n";
?>


  The BSH 2.0 code
  

  buf=new java.lang.StringBuffer();

int i=0;
while(i<400000) {
  i=i+1;
  buf.append(new String(String.valueOf(i)));
}

print (buf.length()); print("\n");


  The ECMAScript ("Mozilla Rhino") code
  

  buf = new java.lang.StringBuffer();
for(i=0; i<400000; i++) buf.append(new String(i));
print (buf.toString().length());


  Command	Script Engine	Communication Channel	Execution time (real, user, sys)
  time jrunscript -l php t11.php	PHP5 + PHP/Java Bridge 3.0.8	named pipes	0m20.112s, 0m18.999s, 0m0.651s
  time jrunscript -l bsh t11.bsh	BSH 2.0	none (native code)	0m21.342s, 0m20.779s, 0m0.291s
  time jrunscript -J-Xmx512M -J-Xms512M -l js t11.js	ECMA script	none (native code)	1m36.877s, 0m55.398s, 0m0.323s

• How do I start a persistent VM?

  If you want to start one persistent VM per HTTP server running on a computer, see the web server installation description. If you want to start one persistent VM per computer, please see the application server or servlet engine description.

  Furthermore it is possible to start a standalone back end, for example with the command:
  
    java -jar JavaBridge.jar INET_LOCAL:9676 3

  The php.ini entry might look like:
  
    [java]
  java.hosts = 127.0.0.1:9676
  java.servlet = Off

  Please see the JavaBridge documentation for details.

• I want to start the back end automatically as a sub-component of my HTTP Server. How do I pass my own java options and how do I change the security context and the UID of the Java process?

  The bridge uses a wrapper binary which can carry the SUID bit and can be tagged with the SEL security context. This wrapper also allows you to change the standard options, which are: java -Djava.library.path=... -Djava.class.path=... -Djava.awt.headless=true -Dphp.java.bridge.base=... php.java.bridge.JavaBridge SOCKET_NAME LOG_LEVEL LOG_FILE. A custom wrapper can be set with:
  
  java.wrapper=/path/to/wrapper/binary


  On Unix the bridge terminates the sub-process hierarchy with SIGTERM, sleep 5 seconds and SIGTERM, if necessary, sleep 5 seconds and SIGKILL, if necessary. On Windows the bridge emulates the Unix kill behaviour, the bridge kills the entire sub-process hierarchy so that you can use a cmd /c wrapper.

  Please see the wrapper RunJavaBridge for an example.

• I want to use the bridge as a replacement for the PHP 4 servlet API, how do I install it into tomcat?

  Download the J2EE binary and copy the JavaBridge.war into the tomcat webapps folder. After that visit http://localhost:8080/JavaBridge and run the supplied PHP examples. Please see webapps/JavaBridge/WEB-INF/cgi/README for details.

• I want to use PHP for all tomcat applications. Apache and IIS are not available, but performance is important. How do I install it?

  Check if your PHP cgi binary supports the -b flag. If not, compile PHP with the --enable-fastcgi option or use Apache or IIS as a front-end instead. On Windows one could also copy a wrapper binary into the WEB-INF/cgi/ folder, for example the launcher.exe from the PHPIntKitForWindows.zip available from alphaworks.

  Download and install the J2EE binary: copy JavaBridge.war into the tomcat webapps folder.

  Copy the JavaBridge.jar and the php-servlet.jar from the JavaBridge.war into the tomcat shared/lib folder. Uncomment the shared_fast_cgi_pool parameter in the JavaBridge/WEB-INF/web.xml and add the lines marked with a + to the tomcat conf/web.xml:

  
<!-- ================== Built In Servlet Definitions ==================== -->

+ <!-- PHP Servlet -->
+ <servlet>
+ <servlet-name>GlobalPhpJavaServlet</servlet-name>
+ <servlet-class>php.java.servlet.PhpJavaServlet</servlet-class>
+ </servlet>
+ <!-- PHP CGI Servlet -->
+ <servlet>
+ <servlet-name>GlobalPhpCGIServlet</servlet-name>
+ <servlet-class>php.java.servlet.PhpCGIServlet</servlet-class>
+ <init-param>
+ <!-- Remember to set the shared_fast_cgi_pool option -->
+ <!-- in JavaBridge/WEB-INF/web.xml to On, too. -->
+ <param-name>shared_fast_cgi_pool</param-name>
+ <param-value>On</param-value>
+ </init-param>
+ </servlet>

<!-- The default servlet for all web applications, that serves static -->
<!-- resources. It processes all requests that are not mapped to other -->
[...]
<!-- ================ Built In Servlet Mappings ========================= -->

+ <!-- PHP Servlet Mapping -->
+ <servlet-mapping>
+ <servlet-name>GlobalPhpJavaServlet</servlet-name>
+ <url-pattern>*.phpjavabridge</url-pattern>
+ </servlet-mapping>
+ <!-- CGI Servlet Mapping -->
+ <servlet-mapping>
+ <servlet-name>GlobalPhpCGIServlet</servlet-name>
+ <url-pattern>*.php</url-pattern>
+ </servlet-mapping>

<!-- The servlet mappings for the built in servlets defined above. Note -->
<!-- that, by default, the CGI and SSI servlets are *not* mapped. You -->

</web-app>


  To test the above settings create a directory testapp and copy the test.php file from the JavaBridge.war into this folder. Type cd testapp; jar cf ../testapp.war * and copy the testapp.war into the tomcat webapps folder. Restart tomcat, browse to http://yourHost.com:8080/testapp/test.php.

  Check if the PHP Fast-CGI server is running. The process list should display 20 (default) PHP instances waiting in the PHP Fast-CGI pool. If not, check if your PHP binary has been compiled with Fast-CGI enabled. Copy a Fast-CGI enabled binary into the webapps/JavaBridge/WEB-INF/cgi/ folder, if necessary.

• How do I create a standalone PHP web application for distribution and how can users deploy it into tomcat?

  Create a directory myApplication, create the directories myApplication/WEB-INF/lib/ and myApplication/WEB-INF/cgi/. Download the J2EE binary and copy the JavaBridge.jar and the php-servlet.jar from the JavaBridge.war to the myApplication/WEB-INF/lib/ folder. Copy the contents of the cgi folder to myApplication/WEB-INF/cgi/. Create the file myApplication/WEB-INF/web.xml with the following content:

  
<web-app>
<!-- PHP Servlet -->
<servlet>
<servlet-name>PhpJavaServlet</servlet-name>
<servlet-class>php.java.servlet.PhpJavaServlet</servlet-class>
</servlet>
<!-- PHP CGI processing servlet, used when Apache/IIS are not available -->
<servlet>
<servlet-name>PhpCGIServlet</servlet-name>
<servlet-class>php.java.servlet.PhpCGIServlet</servlet-class>
</servlet>

<!-- PHP Servlet Mapping -->
<servlet-mapping>
<servlet-name>PhpJavaServlet</servlet-name>
<url-pattern>*.phpjavabridge</url-pattern>
</servlet-mapping>
<!--PHP CGI Servlet Mapping -->
<servlet-mapping>
<servlet-name>PhpCGIServlet</servlet-name>
<url-pattern>*.php</url-pattern>
</servlet-mapping>

<!-- Welcome files -->
<welcome-file-list>
<welcome-file>index.php</welcome-file>
</welcome-file-list>
</web-app>


  Copy the files sessionSharing.jsp and sessionSharing.php from the JavaBridge.war to myApplication and create myApplication.war, for example with the commands: cd myApplication; jar cf ../myApplication.war *.

  The web archive can now be distributed, copy it to the tomcat webapps directory and re-start tomcat. Visit http://localhost/myApplication/sessionSharing.php and http://localhost/myApplication/sessionSharing.jsp.

• I want to use Apache/IIS as a front-end and tomcat as a back end. How do I enable PHP for all my applications?

  Download and install the J2EE binary: copy JavaBridge.war into the tomcat webapps folder. Check if the tomcat webapps directory is shared with the Apache/IIS htdocs directory. If not, change the Apache/IIS setting, the following example is for Apache 2. Edit e.g. /etc/httpd/conf/httpd.conf as follows:

  # documents. By default, all requests are taken from this directory, but
# symbolic links and aliases may be used to point to other locations.
#
-DocumentRoot "/var/www/html"
+DocumentRoot "/var/lib/tomcat5/webapps"

#
# Each directory to which Apache has access can be configured with respect
#
# This should be changed to whatever you set DocumentRoot to.
#
-<Directory "/var/www/html">
+<Directory "/var/lib/tomcat5/webapps">


  Edit the php.ini or add a file php-tomcat.ini to the directory which contains the PHP module descriptions (usually /etc/php.d/), so that it contains:

  [java]
java.hosts = 127.0.0.1:8080
java.servlet = On


  To test the above settings create a directory testapp and copy the sessionSharing.php file from the JavaBridge.war into this folder. Type cd testapp; jar cf ../testapp.war * and copy the testapp.war into the tomcat webapps folder. Restart Apache or IIS and tomcat, browse to http://localhost/testapp, click on sessionSharing.php and check the generated cookie value. The path value must be /.

• I want to use Apache/IIS as a front-end and tomcat as a back end. How do I enable PHP and JSP for all my applications?

  Download the J2EE binary and copy the JavaBridge.jar and the php-servlet.jar from the JavaBridge.war into the tomcat shared/lib folder. Add the lines marked with a + to the tomcat conf/web.xml:

  
<!-- ================== Built In Servlet Definitions ==================== -->

+ <!-- PHP Servlet -->
+ <servlet>
+ <servlet-name>GlobalPhpJavaServlet</servlet-name>
+ <servlet-class>php.java.servlet.PhpJavaServlet</servlet-class>
+ </servlet>

<!-- The default servlet for all web applications, that serves static -->
<!-- resources. It processes all requests that are not mapped to other -->
[...]
<!-- ================ Built In Servlet Mappings ========================= -->

+ <!-- PHP Servlet Mapping -->
+ <servlet-mapping>
+ <servlet-name>GlobalPhpJavaServlet</servlet-name>
+ <url-pattern>*.phpjavabridge</url-pattern>
+ </servlet-mapping>

<!-- The servlet mappings for the built in servlets defined above. Note -->
<!-- that, by default, the CGI and SSI servlets are *not* mapped. You -->

</web-app>


  Check if the tomcat webapps directory is shared with the Apache/IIS htdocs directory. If not, change the Apache/IIS setting, the following example is for Apache 2. Edit e.g. /etc/httpd/conf/httpd.conf as follows:

  # documents. By default, all requests are taken from this directory, but
# symbolic links and aliases may be used to point to other locations.
#
-DocumentRoot "/var/www/html"
+DocumentRoot "/var/lib/tomcat5/webapps"

#
# Each directory to which Apache has access can be configured with respect
#
# This should be changed to whatever you set DocumentRoot to.
#
-<Directory "/var/www/html">
+<Directory "/var/lib/tomcat5/webapps">


  Now that tomcat knows how to handle PHP .phpjavabridge requests and Apache or IIS can access the tomcat webapps, connect the two components: Edit the php.ini or add a file php-tomcat.ini to the directory which contains the PHP module descriptions (usually /etc/php.d/), so that it contains:

  [java]
java.hosts = 127.0.0.1:8080
java.servlet = User


  The above User setting enables session sharing between PHP and JSP, it forwards from http://host/myApp/foo.php to the tomcat back end at 127.0.0.1:8080 using the request PUT /myApp/foo.phpjavabridge. This triggers the GlobalPhpJavaServlet configured in the tomcat web.xml.

  Now you need to do the same for JSP. Unlike the PHP/Java Bridge, which only forwards embedded java statements, the tomcat mod_jk adapter must forward all JSP requests. 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 && make && su -c "make install"


  Add the following lines to the end of the httpd.conf, the following example is for Apache 2:

  LoadModule jk_module modules/mod_jk.so
JkAutoAlias /var/lib/tomcat5/webapps
JkMount *.jsp ajp13


  To test the above settings create a directory testapp and copy the sessionSharing.php and sessionSharing.jsp from the JavaBridge.war into this folder. Type cd testapp; jar cf ../testapp.war * and copy the testapp.war into the tomcat webapps folder. Restart Apache or IIS and tomcat, browse to http://localhost/testapp, click on sessionSharing.php and check the generated cookie value. The path value must be /testapp. Click on sessionSharing.jsp.

• How does the bridge handle OutOfMemoryErrors?

  OutOfMemoryErrors may happen because a cached object cannot be released, either because

  1. the object is permanently referenced by a request-handling thread or
  2. the object has been entered into the session or application store or
  3. the object is referenced by a thread outside of the scope of the PHP/Java Bridge.

  When a java.lang.OutOfMemoryError reaches the request-handling thread, the PHP/Java Bridge thread pool removes the thread from its pool and writes a message FATAL: OutOfMemoryError to the PHP/Java Bridge log file. The session store is cleaned and all client connections are terminated without confirmation.

  If the OutOfMemoryError persists, this means that a thread outside of the PHP/Java Bridge has caused this error condition.

  The following code example could cause an OutOfMemoryError:
  
  <?php
session_start();
if(!$_SESSION["buffer"]) $_SESSION["buffer"]=new java("java.lang.StringBuffer");
$_SESSION["buffer"]->append(...);
?>

  OutOfMemory conditions can be debugged by running the back end with e.g.:
  
  java -agentlib:hprof=heap=sites -jar JavaBridge.jar


• The EJB example works with the Sun J2EE server, but in JBoss I get a ClassCastException, what's wrong?

  It's a JBoss problem, although this problem may also appear in other application servers which do not strictly separate the application/bean domains. The JavaBridge.war already contains the documentClient.jar as a library, so JBoss references the library classes instead of the bean classes. Just remove the documentClient.jar from the JavaBridge.war, re-deploy JavaBridge.war and run the test again.

  In JBoss' default setup the code:

  // access the home interface
$DocumentHome = new JavaClass("DocumentHome");
$PortableRemoteObject = new JavaClass("javax.rmi.PortableRemoteObject");
$home=$PortableRemoteObject->narrow($objref, $DocumentHome);


  refences the DocumentHome from the library, which is assignment-incompatible to DocumentHome from the enterprise bean (DocumentHome@WebAppClassLoader != DocumentHome@BeanClassLoader), so you get a ClassCastException in narrow.

  In contrast the Sun J2EE server correctly separates the beans/applications; the $objref is a unique proxy generated by a parent of the WebAppClassLoader, so that narrow can always cast the proxy to DocumentHome@WebAppClassLoader, even if a class with the same name is already available from the WebAppClassLoader.

• How do I install PHP into the Nutch, Spring, JSF, ..., Framework?

  By providing PHP beans and a description how to manage them, as usual. IOC (sometimes called "dependency injection") requires that you give up control so that the framework can call you when it becomes necessary. The code

  class Bean { ... }
java_context()->call(java_closure(new Bean())) || header("$framework");

  can be used to pass control from the web server to the framework running on a J2EE node.

  The standard java script interface or the proxy used by the invocable interface can be used to call from the framework running on a J2EE node into the allocated PHP scripts running on the web server. The following excerpt from the JSF implementation calls methods from the above PHP bean:

  ((Invocable)((PhpFacesContext)FacesContext.getCurrentInstance()).getScriptEngine(this, new URL(phpScript))).invoke(method, args);

  Please see the JSF implementation for a reference.

• How can PHP classes extend Java classes and Java methods?

  By using java_closure() and the visitor pattern for example. The tests.php5 folder contains a script_api.php example which shows how to implement java.lang.Runnable to run multiple PHP threads, concurrently accessing a shared resource.

• On Windows some PHP binaries do not support HTTPS/SSL

  If you see the message:

  Warning: fsockopen() [function.fsockopen]: unable to connect to ssl://127.0.0.1:8443 (Unable to find the socket transport "ssl" - did you forget to enable it when you configured PHP?)

  this means that PHP cannot connect back to the official SSL port. Please check the "Registered Stream Socket Transports" from the phpinfo() (see the test.php page), it should display: tcp, udp, ssl, sslv3, sslv2, tls. If not, please recompile PHP with SSL enabled, use the flag --with-openssl.

  A workaround is to use the official non-SSL port or to open a dedicated local port for the PHP-Java communication. The following example is for Tomcat:

  1. Disable override_hosts in the web application WEB-INF/web.xml:

     <init-param>
<param-name>override_hosts</param-name>
<param-value>Off</param-value>
</init-param>


  2. Open a local port in the tomcat conf/server.xml (only necessary if you have disabled the official non-SSL port):

     <Service name="Catalina">
[...]
<Connector port="9157" address="127.0.0.1" />
[...]
</Service>


  3. Set the communication port in the PHP .ini (the phpinfo() or test.php displays the location of the responsible .ini file):

     [java]
java.hosts = 127.0.0.1:9157
java.servlet = User


  If you want to use the official non-SSL port (usually port number 8080), change the java.hosts line accordingly.

  Restart the application server or servlet engine. Check the settings by running phpinfo() or by visiting the test.php page.

Related

• A PHP IDE.
• A commercial, free (GPL) PHP engine written in pure java.
• A commercial, non-free bridge which uses the same technology as the PHP/Java Bridge.
• Calling Enterprise Java Beans from PHP/SOAP.
• Calling Enterprise Java Beans from the PHP/Java Bridge.