Quercus types, Java-Quercus type mappings, working with Java Classes in PHP

Introduction

Integrating PHP and Java

Quercus Types

For every PHP type, there is a Quercus type that is used internally to represent the corresponding PHP value. All Quercus types extend Value.

Quercus natively supports Unicode and is compatible with the new PHP 6 syntax.

Java Method Arguments

In Quercus, Java methods can be called from within PHP. Java arguments for Java methods need to be marshaled to the correct type from the PHP parameters that were passed in.

When the Java argument type is declared to be Object, the value will be marshaled to a Java object. For example, a PHP int (LongValue) will be marshaled to an Integer. The only exceptions are PHP arrays and objects: they are passed in as-is without marshaling.

When the Java argument type is declared to be a Quercus Value, the PHP value is passed in directly without marshaling.

If the Java argument type is an object, passing in a PHP NULL will result in a null Java argument.

Java Method Returns

When a Java method is called from PHP code, the return value of that Java method needs to be marshaled into a valid Quercus value.

Java objects like Calendar and Map are placed inside JavaValues and then returned to the PHP environment. A JavaValue is just a wrapper that exposes the object's Java methods to PHP. For example, if $url is holding a Java URL object, then we can use $url->getHost() to call the URL's getHost() method.

Some Java objects may have an effective PHP value. Take for instance, Date. A Date object is, for practical purposes, a PHP int with it's value pegged to Date.getTime().

Collection, List, and Map behave just like PHP arrays. Suppose $map holds a Java HashMap, then it's certainly valid to do $map["foo"] = "bar". However, there are some limitations that are dependant on the underlying Java type. For example, $list[-1] = 5 will not be possible for a Java List because List indexes start at 0.

Working with Java Classes in PHP

Instantiating Objects

To get new instances of Java ojects, use new java() by passing in the class name and any constructor arguments.

<?php

  $a = new java("java.util.Date", 123);

  echo $a->nanoTime();

?>

Accessing static members and functions

To get the class of the Java object without calling the constructor, use java_class().

<?php

  $class = java_class("java.lang.System");

  // System.in
  $in = $class->in;
  
  // System.currentTimeInMillis();
  $time = $class->currentTimeInMillis();

?>

Special Quercus Keywords

import Keyword in PHP

Quercus supports the import keyword to fasciliate Java coding in PHP. User classes should be placed in the webapp's WEB-INF/classes directory.

<?php

  import java.util.Vector;
  import java.util.Date;

  $vector = new java("Vector");
  $date = new Date(123);

?>

The import keyword will also work on PHP classes but it has a different functionality than for Java classes. import will try to autoload PHP classes/files by including {classname}.php from the webapp's WEB-INF/classes directory.

Java Method Overloading

Quercus allows overloaded Java methods to be called from within PHP code. Quercus will try to use the method whose arguments are the most easily marshaled (i.e. a PHP string easily goes into a Java String whereas a PHP array is a mismatch for a Java int).

import com.caucho.quercus.module.AbstractQuercusModule;

public class MyModule extends AbstractQuercusModule
{
  public static void foo(String a, boolean b)
  {
  }

  public static void foo(String a, String b)
  {
  }
}

<?php

  foo('abc', false);

?>

In the example above, the first Java method public static void foo(String a, boolean b) would be called because it requires the least amount of type coersion.