Working with Java classes in PHP, Quercus types, and Java to Quercus type mappings.

Working with Java classes in PHP

Importing classes

Quercus supports the use of an import statement in PHP. import makes any java class available to the PHP script with it's unqualified name.

<?php

  import java.util.Date;

  $a = new Date(123);

  echo $a->time;
?>

Instantiating objects by class name

An alternative to import is to use new Java(...) with the class name and any constructor arguments.

<?php

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

  echo $a->time;

?>

Calling methods

PHP syntax is used for invoking methods. PHP property syntax can be used for invoking getters and setters of Java objects.

<?php

  import java.util.Date;

  $a = new Date(123);

  echo $a->getTime();    # calls getTime()
  echo $a->setTime(456); # calls setTime(456)

  echo $a->time;      # calls getTime()
  $a->time = 456;     # calls setTime(456)
?>

Static members and methods

Static methods and members are available using PHP syntax if the Java class has been imported.

<?php

import java.util.Calendar;

$calendar = Calendar::getInstance();

var_dump($calendar);
?>

An alternative to import is to use java_class() to access static members and methods.

<?php

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

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

?>

import keyword in PHP

Quercus supports the use of an import statement in PHP. import makes any java class available to the PHP script with it's unqualified name.

<?php

  import java.util.Date;

  $date = new Date(123);

?>

User classes can be placed in the webapp's WEB-INF/classes directory.

package example;

public class MyBean
{
  int _value;

  public MyBean(int value)
  {
    _value = value;
  }

  public int getValue()
  {
    return _value;
  }

  public String makeMessage()
  {
    return "Hello, my value is " + _value;
  }
}

<?php

  import example.MyBean;

  $bean = new MyBean(123);

  var_dump($bean);
  var_dump($bean->value);
  var_dump($bean->makeMessage());
?>

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 by including the file WEB-INF/classes/classname.php from the application's WEB-INF/classes directory.

HttpServletRequest and HttpSession

QuercusServlet automatically creates the $request variable for PHP scripts. It contains the javax.servlet.http.HttpServletRequest object.

PHP sessions are not shared with servlet sessions. The $request variable can be used to obtain the servlet session if required.

<?php
  $session = $request->getSession(true);

  $foo = $session->getAttribute("foo");
?>

Quercus types

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

Java method arguments

In Quercus, Java methods can be called from within PHP. Java arguments for Java methods are 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 is marshaled into a valid PHP value.

Java objects like Calendar and Map are placed inside JavaValues and then returned to the PHP environment. A JavaValue is 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 dependent on the underlying Java type. For example, $list[-1] = 5 will not be possible for a Java List because List indexes start at 0.

Java method overloading

Quercus allows overloaded Java methods to be called from within PHP code. Quercus will 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) is called because it requires the least amount of type coercion.