PHP hello world module (jar version)

From Resin 3.0

Revision as of 17:12, 7 December 2005 by Creich (Talk | contribs)
Jump to: navigation, search


Contents

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 version) 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 (non-jar version) 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

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/javatest.php:3: Fatal Error: 'hello_test' is an unknown function. [hello_test]

The first thing to do is make sure your error 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

Enjoy

Personal tools