PHP hello world module (jar version)

Introduction

One of the advantages of using Resin's implementation of PHP is that you can create your own library of functions written in Java and access them from within PHP.

There are two different ways of including java code in your PHP application running from within Resin. You can create either:

1. a module, or
2. a plain old java object.

There is very little difference in the way the two are constructed, but there is a BIG difference in how they are meant to be used from within your PHP application.

If you want to create a library of functions callable from anywhere within your PHP code, then you should create a module.

Here is the most important thing to remember when creating a module:

• The functions exposed in the module are available from within any PHP application running under Resin. So you need to be EXTREMELY careful about naming collisions. In fact, many of the existing PHP modules follow a naming convention where each function name is preceded by the module name and an underscore (ie: mysql_connect()). The module will be callable from within Resin's implementation of PHP whether or not you follow a careful naming convention, but ignore this warning at your own risk.

The tutorial PHP Hello World Class discusses the alternative way of incorporating java into your PHP application.

This tutorial also assumes that you have already properly installed Resin on your computer. Please see the related article PHP Hello World for more information on installing Resin for the first time.

The example that follows walks you through the steps of creating a module and also of "jar-ing" up the relevant files.

You should not be put off by all the small steps involved in this process for 2 reasons.

1. You do not have to "jar-up" the files. See the tutorial PHP Hello World Module for those steps.
2. There is an extremely popular free utility called Ant available at http://ant.apache.org/. At the end of this tutorial, we include the "build.xml" file you will need to create this jar. Ant takes care of all the nasty little details like creating directories and copying files for you. If you are going to do any serious java development, you probably should just learn how to use Ant at some point anyway.

Step 1: Create example.jar and place it in the appropriate directory

Create your development environment

The steps that follow assume you are working in a Windows environment. If you are working within Unix (or Linux or Mac), the same steps will work. Just be sure to modify the commands where necessary.

c:\Documents and Settings\Charles>cd c:\
c:\> md sandbox
c:\> cd sandbox
c:\sandbox> md src
c:\sandbox> md classes
c:\sandbox> cd src
c:\sandbox\src> md example
c:\sandbox\src> md META-INF
c:\sandbox\src> cd META-INF
c:\sandbox\src\META-INF> md services

Create HelloModule.java

Copy the following file into your favorite text editor (notepad will do) and save it to the c:\sandbox\src\example directory.

HelloModule.java

package example;

import com.caucho.quercus.module.AbstractQuercusModule;

public class HelloModule extends AbstractQuercusModule {

  /*
  ** Notice the careful use of the naming
  ** convention hello_test.  This is done
  ** in order to prevent name collisions
  ** among different libraries.
  */
  public String hello_test(String name)
  {
    return "Hello, " + name;
  }
}

Create com.caucho.quercus.QuercusModule

Copy the following one line file and save it to the c:\sandbox\src\META-INF\services directory. Make sure that the file name is exactly "com.caucho.quercus.QuercusModule"

com.caucho.quercus.QuercusModule

example.HelloModule

Compile and Jar the files

Navigate to c:\sandbox

C:\sandbox>javac -d classes -classpath c:\resin-3.0.13\lib\quercus.jar src\example\*.java

Note: In my installation of Resin, the file httpd.exe is located in c:\resin-3.0.13. If you have installed Resin in a different directory change the above classpath appropriately.

Create a META-INF\services directory within classes and copy com.caucho.quercus.QuercusModule.

c:\sandbox> cd classes
c:\sandbox\classes> md META-INF
c:\sandbox\classes> cd META-INF
c:\sandbox\classes\META-INF> md services
c:\sandbox\classes\META-INF> cd services
c:\sandbox\classes\META-INF\services> copy ..\..\..\src\META-INF\services\com.caucho.quercus.QuercusModule .

Change directory to c:\sandbox\classes and run the jar utility.

c:\sandbox\classes\META-INF\services> cd c:\sandbox\classes
c:\sandbox\classes> jar cvf example.jar example META-INF

Copy Example.jar to your working resin directory

c:\sandbox\classes> copy example.jar c:\resin-3.0.13\webapps\ROOT\WEB-INF\lib

Now restart Resin.

Step 2: Create and browse the PHP page

Save "javahello.php" into c:\resin-3.0.13\webapps\ROOT.

javahello.php

<?php

$name = hello_test("Charles");
echo $name;

?>

In your favorite browser type:

http://localhost:8080/javahello.php

You should see:

Hello, Charles

Voila!

Some simple trouble shooting

If you followed this tutorial, but you get an error like:

/c:/resin-3.0.13/webapps/ROOT/javahello.php:3: Fatal Error: 'hello_test' is an unknown function. [hello_test]

The first thing to do is make sure your logging is configured correctly. You can look for the entry within c:\resin-3.0.13\conf\resin.conf which deals with logging it will be near the top. Make sure it reads

<log name="" level="finer" path="log.txt" timestamp="[%H:%M:%S.%s] "/>

Now restart resin and check within the file c:\resin-3.0.13\log.txt for an entry that will look something like this:

[17:41:56.828] PHP loading module example.HelloModule

If you do not see this entry, then your module was not loaded by Resin. Recheck:

1. You have no typos in any of the files.
2. You have the same EXACT directory structure beneath c:\sandbox
3. You have run the jar utility from within c:\sandbox\classes
4. You have copied "example.jar" to the correct WEB-INF directory. There is more than one in a standard installation of Resin.

Conclusion

Quercus allows developers to incorporate java code into PHP web applications. The tutorial above takes you through the steps to create a simple helloworld application.

As you can see, there are a lot of small steps required to build a java project. However, as we mentioned above, there is a free and immensely popular utility called Ant available at http://ant.apache.org. If you are going to do development in Java, you need to know your way around Ant. Fear Not! It is simple to install, and not so hard to use.

Here's pretty much all you have to do:

1. Download and install Ant.

2. Copy the build.xml file below to c:\sandbox. The only change you will need to make is to change the vendor.dir property from "c:/resin-3.0.13" to whatever directory has the "httpd.exe" file.

build.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="HelloWorld" basedir="." default="jar">

    <property name="jar.name" value="example"/>
    <property name="src.dir" value="src"/>
    <property name="classes.dir" value="classes"/>
    <property name="vendor.dir" value="c:/resin-3.0.13"/>
    <property name="vendor.lib.dir" value="${vendor.dir}/lib"/>
    <property name="vendor.webapps.lib" value="${vendor.dir}/webapps/ROOT/WEB-INF/lib"/>
    <property name="src.META-INF.services" value="${src.dir}/META-INF/services"/>
    <property name="classes.META-INF.services" value="${classes.dir}/META-INF/services"/>

    <path id="project.classpath">
      <fileset dir="${vendor.lib.dir}">
        <include name="*.jar"/>
      </fileset>
    </path>

    <target name="clean" description="Delete all generated files">
        <delete dir="${classes.dir}" failonerror="false"/>
        <mkdir dir="${classes.dir}"/>
        <mkdir dir="${classes.META-INF.services}"/>
        <copy todir="${classes.META-INF.services}">
           <fileset dir ="${src.META-INF.services}"/>
        </copy>
        <delete file="${jar.name}.jar"/>
    </target>

    <target name="compile" description="Compiles PHP Hello World Module" depends="clean">
        <javac srcdir="${src.dir}" destdir="${classes.dir}">
          <classpath refid="project.classpath"/>
        </javac>
    </target>

    <target name="jar" description="JARs PHP Hello World Module" depends="compile">
        <jar destfile="${jar.name}.jar" basedir="${classes.dir}/"/>
        <copy file="${jar.name}.jar" todir="${vendor.webapps.lib}"/>
    </target>

</project>

3. Navigate to c:\sandbox and run ant:

c:\sandbox> ant

Ant will automatically take care of:

• Creating the directory structure under classes
• Compiling the appropriate files
• "Jar-ing" the appropriate files and directory structure
• Copying com.caucho.quercus.QuercusModule to the to "c:\sandbox\classes\META-INF\services"
• Copying example.jar to the "C:\resin-3.0.16\webapps\ROOT\WEB-INF\lib"

You are still responsible for creating the development environment (ie: everything from c:\sandbox\src on down). But the rest is down automatically by Ant. You can make any changes that you want to HelloModule.java, then just retype "ant" and everything will just work.

Happy Coding!