PHP/Java Bridge SvnRepo

207 lines (141 with data), 6.8 kB

Overview
--------

The J2EE interface associates a PHP web context or the entire J2EE
server with a managed and persistent PHP executable or an external
HTTP server running PHP.

This document describes how to call Java methods from PHP. And how to
embed PHP applications into a pure Java application server or servlet
engine. Please see the INSTALL.J2SE document for details how to call
PHP methods from a pure Java application.

The PHP/Java Bridge can be installed with one copy operation:

* the JavaBridge.war (renamed to "myPhpApp.war") should be copied into
  the autodeploy folder of the J2EE server.


Development
-----------

* Extract the JavaBridge.jar from the JavaBridge.war zip file from the
  PHP/Java Bridge binary ("php-java-bridge*_j2ee.zip") download. For
  example with the command:

    java -classpath JavaBridge.war TestInstallation

  Double-click on JavaBridge.jar or type:

    java -jar JavaBridge.jar

  and click "OK" to start a servlet engine back end for all computers
  on the local network. Type:

    java -jar JavaBridge.jar --help 

  to see the list of available options.


* Link Java.inc and your Java libraries into PHP at run-time. Example:
  
   <?php
    require_once("java/Java.inc");

    // call Java libraries using the provided Java class...
    java_require("myLibs/myLib.jar;dependentLib1.jar;...);

    $SystemClazz =     Java("java.lang.System"); 
    echo $SystemClazz->getProperties();

    $myInstance  = NEW Java("myPackage.MyClass", ...); 
    $myInstance->callSomething(...);
   ?>


* Create a PHP web archive for distribution, for example with the commands:

  mkdir JavaBridge
  cd JavaBridge
  jar xvf ../JavaBridge.war

  cd ../myPhpApp
  cp -r ../JavaBridge/WEB-INF JavaBridge/java .
  cp -r MYLIBS/*.jar WEB-INF/lib
  jar cvf ../myPhpApp.war *
  

Deployment
----------

* Install a J2EE application server or servlet engine, for example
  Apache Geronimo, Tomcat, Glassfish, ...


* Copy your web application myPhpApp.war to the autodeploy folder of
  your J2EE server or servlet engine. If you don't have a myPhpApp.war
  yet, simply rename "JavaBridge.war" to "myPhpApp.war".

  Example for Tomcat on Unix:
  
    cp myPhpApp.war $CATALINA_HOME/webapps/

  Example for Apache Geronimo on Windows:

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

  Wait until the "myPhpApp" directory appears (restart your J2EE
  server, if necessary).


* If you want to run PHP as a sub component of the J2EE server or
  servlet engine, visit http://localhost:8080/myPhpApp and click on
  test.php. 

* If you want to run PHP as a sub component of Apache or IIS or from
  the command line, copy the directory which contains the web
  application "myPhpApp" over to the Apache/IIS document root or to
  the some local directory accessible by the PHP command line
  executable. Example for Apache Tomcat on Unix:

    cp -r $CATALINA_HOME/webapps/myPhpApp/ /var/www/html/


* Edit the copied web application, if necessary. For example edit
  DOCUMENT_ROOT/myPhpApp/java/Java.inc so that it connects PHP with
  the Java VM "127.0.0.1:8080/myPhpApp". For example:

    define("JAVA_HOSTS", "127.0.0.1:8080"); 
    define("JAVA_SERVLET", "/myPhpApp/JavaBridge.phpjavabridge"); 

  Or set JAVA_PARSE_INI_FILE and use the following java.ini file:

    [java]
    java.servlet=/myPhpApp/JavaBridge.phpjavabridge
    
    <?php define ("JAVA_PARSE_INI_FILE", true);
          require_once("java/Java.inc");
      ...
    ?>

* Firewall-out the J2EE/Servlet port 8080, if necessary. Or modify the
  J2EE/Servlet so that it listens only on the local interface. Note that
  in the default setup the PHP/Java Bridge rejects requests from non-local
  PHP clients. For a intranet server start the J2EE/Servlet VM with the
  parameter -Dphp.java.bridge.promiscuous=true or set the "promiscuous"
  init-param in the J2EE WEB-INF/web.xml and make sure that your
  computer cannot be accessed from the internet. At least firewall-out
  the ports 8080 and all ports in the range [9267,...,[9367 and read the
  "security" sections from README.


JSR 223 Script API
------------------

* It is possible to run PHP scripts in servlets. The examples below
  use JSP to demonstrate the features (in JSP "this" is the Servlet,
  "application" is the ServletContext and "request", "response" the
  HttpServletRequest and HttpServletResponse objects.

  The web application needs a context listener declared in 
  WEB-INF/web.xml:

   <listener>
       <listener-class>php.java.servlet.ContextLoaderListener</listener-class>
   </listener>
   <listener>
       <listener-class>php.java.servlet.RequestListener</listener-class>
   </listener>

  And the JavaBridge.jar, php-servlet.jar, php-script.jar, script-api.jar
  must be available in the WEB-INF/lib directory.

  Servlets can then access PHP scripts as follows:

  <%
    javax.script.ScriptEngine e = 
      php.java.script.servlet.EngineFactory.getPhpScriptEngine (this, 
                                                        application, 
                                                        request, response);
    e.getContext().setWriter (out);
    e.eval ("<?php phpinfo(); ?>");
    e.eval (new java.io.FileReader("otherScript.php"));
    ...
  %>
  
  The script engine reserves up to three continuations, one for the
  JSP, one for PHP (PhpCGIServlet) and a optional Java continuation
  (PhpJavaServlet).  If the servlet engine thread pool cannot allocate
  three threads, a PhpScriptTemporarilyOutOfResourcesException is
  thrown.
  

  The InvocablePhpScriptEngine can be accessed as follows:

  <%
    javax.script.ScriptEngine e = 
      php.java.script.servlet.EngineFactory.getInvocablePhpScriptEngine (this, 
                                                        application, 
                                                        request, response);
    e.getContext().setWriter (out);
    e.eval ("<?php function hello() {echo "hello";}; ?>");
    javax.script.Invocable i = (javax.script.Invocable) e;
    i.invokeFunction ("hello", new Object[]{});
    ...
    e.eval ((java.io.Reader)null);
  %>

  The script engine reserves three continuations, one for the JSP, one
  for PHP (PhpCGIServlet) and a Java continuation (PhpJavaServlet). If
  the servlet engine thread pool cannot allocate three threads, a
  PhpScriptTemporarilyOutOfResourcesException is thrown.


Further information
-------------------

Our FAQ contains examples which show how to create a distributable PHP
web application, how to enable PHP for all Tomcat web applications and
and how to set up a load balancer for a Tomcat cluster.


* Please report bugs/problems to the mailing list:

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