Introduction to Quercus

What is Quercus

Quercus implements PHP 5 and is internationalization/localization (i18n/l10n) aware. Quercus natively supports Unicode and the new Unicode syntax of the up-and-coming PHP 6. Quercus implements a growing list of PHP extensions (i.e. APC, iconv, GD, gettext, JSON, MySQL, Oracle, PDF, Postgres, etc.). Many popular PHP applications will run as well as, if not better, than the standard PHP interpreter straight out of the box.

Benefits of Quercus

Quercus and Quercus' PHP libraries are written entirely in Java, thereby taking the advantages of Java applications and infusing them into PHP. PHP applications running on Quercus are simply faster, easier to develop, more capable, more secure, and more scalable than any other PHP solution.

Quercus gives both Java and PHP developers a fast, safe, and powerful alternative to the standard PHP intepreter. Developers ambitious enough to use PHP in combination with Java will benefit the most from what Quercus has to offer.

Existing PHP applications on Quercus

Killer Apps: Mediawiki, Wordpress

Caucho has designated a few applications as Quercus "killer apps". For these applications, we take extra time to test that each new application version works well with Quercus. Any issues raised with the killer apps have priority over other Quercus bugs.

• http://wiki.caucho.com/Mediawiki
• http://wiki.caucho.com/Wordpress

Other applications

• http://wiki.caucho.com
• DokuWiki
• Drupal
• Gallery2
• Mantis
• Mediawiki
• Openads
• PHP-Nuke
• phpMyAdmin
• PHProjekt
• Vanilla
• Wordpress

Configuring Quercus

php.ini

Individial PHP initialization values can be set in resin-web.xml. For example, to set the settings for sending mail:

<web-app xmlns="http://caucho.com/ns/resin">
  <servlet-mapping url-pattern="*.php"
                   servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <php-ini>
        <sendmail_from>my_email_address</sendmail_from>
        <smtp_username>my_email_username</smtp_username>
        <smtp_password>my_email_password</smtp_password>
      </php-ini>
    </init>
  </servlet-mapping>
</web-app>

A PHP style ini file can also be specified:

<web-app xmlns="http://caucho.com/ns/resin">
  <servlet-mapping url-pattern="*.php"
                   servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <ini-file>WEB-INF/php.ini</ini-file>
    </init>
  </servlet-mapping>
</web-app>

Character Encoding

Quercus 3.1.0 supports PHP6 and has full support for Unicode. But like PHP6, Quercus 3.1.3 has its Unicode support turned off by default for compatibility with legacy PHP applications. Unicode support can be enabled with the php ini unicode.semantics.

With unicode semantics off, Quercus will intrepret bytes in the default ISO-8859-1 encoding. Quercus will behave just as PHP5 would. With it on, PHP5 applications may break and you need to be concerned with the following three encodings options: script-encoding, unicode.output_encoding, and unicode.runtime_encoding. By default, Quercus uses UTF-8 for all three.

Script encoding indicates the encoding of PHP script source files. If the source code for an application is not encoded in UTF-8, Quercus may give invalid UTF-8 conversions errors when it tries to convert bytes read to UTF-8. The solution is to tell Quercus to parse PHP scripts using the correct character set (ISO-8859-1 for most applications). For example, to tell Quercus to use ISO-8859-1, add <script-encoding> to the init tag of QuercusServlet:

<web-app xmlns="http://caucho.com/ns/resin">

  <servlet-mapping url-pattern="*.php"
                   servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <script-encoding>ISO-8859-1</script-encoding>
    </init>
  </servlet-mapping>

</web-app>

If the PHP application also expects conversion from binary to string using a character encoding that is not UTF-8, then the unicode.runtime_encoding is used to specify the encoding. In PHP 6, there are two types of strings, Unicode and binary. A binary string is a string where the data is binary, the encoding is unknown, or the encoding is not Unicode (UTF-16). If you ever use a function that will likely return a binary string, then you probably need to set unicode.runtime_encoding. Quercus may convert your binary string to Unicode and then to your output encoding for output to the browser. If your runtime encoding is wrong, then you would see garbage in your browser.

<web-app xmlns="http://caucho.com/ns/resin">

  <servlet-mapping url-pattern="*.php"
                   servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <script-encoding>iso-8859-1</script-encoding>
      <php-ini>
        <unicode.runtime_encoding>iso-8859-1</unicode.runtime_encoding>
      </php-ini>
    </init>
  </servlet-mapping>

</web-app>

unicode.output_encoding is the charset used to display output to the browser. You can set it in your resin-web.xml:

<web-app xmlns="http://caucho.com/ns/resin">
  <servlet-mapping url-pattern="*.php"
                  servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <script-encoding>iso-8859-1</script-encoding>
      <php-ini>
        <unicode.output_encoding>iso-8859-1</unicode.output_encoding>
        <unicode.runtime_encoding>iso-8859-1</unicode.runtime_encoding>
      </php-ini>
    </init>
  </servlet-mapping>
</web-app>

Compiling PHP Scripts for Increased Performance

Quercus will automatically compile PHP scripts into Java classes for better performance. This is available only in Resin Professional.

The default behaviour in Resin Professional is to execute the PHP script in interpreted mode, and to compile the script in the background. When the compiled version is ready, it is used instead of the interpreted version. To force compilation, use the <compile> tag within the <init> tag:

<web-app xmlns="http://caucho.com/ns/resin">
  <servlet-mapping url-pattern="*.php"
                   servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <compile>true</compile>
    </init>
  </servlet-mapping>
</web-app>

Using Databases

JDBC drivers are required to use databases in Quercus. There are JDBC drivers for MySQL, Oracle, SQLite, and many other database engines. The desired JDBC driver should be downloaded into Resin's ${resin.root}/lib directory. Resin will automatically load jars in the lib directory upon startup.

The database support in Quercus supports robust database connection pooling since Quercus runs in Resin, a fast Java application server. All PHP database access automatically uses JDBC-pooled connections. PHP code does not need changing to take advantage of this capability.

The PHP database apis supported include PDO (portable database objects), mysql, mysql improved, postgres and oracle. Any JDBC-compliant database is available to PHP scripts using PDO.

<php

$db = new PDO("java:comp/env/jdbc/my-database");

...
?>

<?php

  // standard PHP
  //mysql_connect($host, $username, $password, $dbname);

  // using JNDI lookup
  mysql_connect("java:comp/env/jdbc/myDatabaseName");

?>

<web-app xmlns="http://caucho.com/ns/resin">
  <database jndi-name="jdbc/mysql">
    <driver type="org.gjt.mm.mysql.Driver">
      <url>jdbc:mysql://localhost:3306/test</url>
      <user></user>
      <password></password>
    </driver>
  </database>

  <servlet-mapping url-pattern="*.php"
                   servlet-class="com.caucho.quercus.servlet.QuercusServlet">
    <init>
      <database>java:comp/env/jdbc/myDatabaseName</database>
    </init>
  </servlet-mapping>
</web-app>

Java/PHP integration

Using Java services from PHP: Resin-IoC/WebBeans

If you're already using Resin-IoC/WebBeans to organize your application into services, your PHP script can grab a reference to the service with the registered name. Calling java_bean with a singleton bean's name will return the singleton, and calling java_bean with a component's name will return a new instance of the component. Quercus will automatically marshal PHP calls to the bean's Java methods, so your service's entire functionality will be available to the PHP script.

<?php

  $house_manager = java_bean("houseManager");

  $house = $house_manager->findHouse("Gryffindor");

  foreach ($house->getPrefects() as $prefect) {
    echo $prefect . "\n";
  }

?>

WebBeans (JSR-299) is an inversion-of-control/dependency-injection framework specification for JavaEE 6 which is designed to organize Java services, and also integrate with scripting frameworks. WebBeans integrates tightly with the newest EJB and persistence specifications, so PHP applications using the WebBeans interface will gain the latest, cleanest integration with Java applications. Resin-IoC is Caucho's implementation of the WebBeans framework, and serves as the underlying architecture of Resin itself, as well as the Resin EJB implementation.

Working with Java classes in PHP

<?php

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

  echo $a->time;

?>

<?php

  import java.util.Date;

  $a = new Date(123);

  echo $a->time;
?>

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());
?>

Calling Java 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)
?>

<?php

import java.util.Calendar;

$calendar = Calendar::getInstance();

var_dump($calendar);
?>

<?php

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

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

?>

Java method overloading

Quercus allows overloaded Java methods to be called from within PHP code. The number of arguments is most important, followed by the argument types. 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).

Because the PHP language itself does not support overloading, the Quercus overloading of Java methods may not be exact. Therefore, it's best to keep overloading to a minimum. Overloading by the number of arguments will always work, but overloading by types is trickier.

Example: MyModule.java

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)
  {
  }
}

example.php

<?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.

Note

Only Java methods with the same amount of arguments will be considered.

Modules: Adding PHP functions

The core PHP functions are implemented inside Quercus modules. Quercus modules are the Java equivalent of PHP modules.

All Quercus modules need to implement AbstractQuercusModule. Functions defined in your modules are callable from within PHP script by using just the function name. Function names need to be distinct in order to prevent name collisions, though Quercus does support function overloading (for Java functions only).

A typical Quercus module looks like:

package example;

import com.caucho.quercus.env.Env;
import com.caucho.quercus.module.AbstractQuercusModule;

public class HelloModule extends AbstractQuercusModule
{
  /**
   * @param env provides Quercus environment resources.
   * @param str
   */
  public void hello_test(Env env, String str)
  {
    // 'echos' the string
    env.println("hello " + str);
  }
}

<?php

  // PHP 5 is case-insensitive
  // just prints "hello me" to the browser.
  hello_test("me");

?>

For a tutorial on how to implement your own Quercus module, see the Quercus module tutorial.

Marshalling: PHP to Java conversions

HttpServletRequest and HttpSession

QuercusServlet automatically creates the $request variable for PHP scripts. It contains the 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");
?>

PHP Module highlights

Standard modules

Quercus implements the standard PHP libraries (arrays, strings, date, regexp, etc). It also supports extension libraries like zip and zlib for compression, mcrypt for encryption, mail (implemented with JavaMail), and bcmath for large numbers.

APC (object caching)

For PHP object caching, Quercus implements the APC module. PHP applications can use the APC functions to save PHP objects without resorting to serialization and database persistence. Because Quercus runs in Resin, a Java web server, the saved objects are quickly available to any thread running PHP. In other words, unlike Apache which makes sharing across different PHP processes difficult, Quercus can just store a singleton cache of the APC-cached objects.

Because Quercus compiles PHP to Java code, PHP scripts get the opcode caching of APC for free. At this time, performance of Quercus is roughtly comparable with performance of mod_php with APC, i.e. it is significantly faster (3-5 times) than mod_php running by itself.

Image support ('gd')

Quercus provides the image module, so users can use image manipulation functions like watermarking and thumbnail generation in any PHP script on Quercus. .jpg, .png, and .gif files are currently supported. Java users will also find these libraries convenient.

PDF generation (PDFlib api)

PDF generation in Quercus follows the PDFlib API. Since the Quercus PDF implementation is a new implementation in Java, no special downloads are needed to use PDF.

AJAX (JSON)

Quercus also includes the JSON module for encoding and decoding AJAX-style requests. The JSON modules is an excellent example of the benefits of writing modules in Java. Because Java supports garbage collection and protects from pointer overruns, the JSON module implementation is straightforward and reliable, without having to worry about all the possible memory problem in a C library.

Gettext (localization)

Quercus supports the gettext API and .po and .mo files. gettext is a portable API for localization, i.e. translation of program messages. In the future, the Quercus gettext implementation will support Java message bundles so Java applications using PHP can use standard Java localization techniques.

ResinModule

jndi_lookup

Retrives an object from JNDI. jndi_lookup is useful in a SOA (Service Oriented Architecture) system to locate a Java service.

<?php

$conn = jndi_lookup("java:comp/env/jms/jms-connection-factory");
$queue = jndi_lookup("java:comp/env/jms/test-queue");

...
?>

mbean_explode

Explodes a JMX ObjectName into an array.

<?php

var_dump(mbean_explode("resin:type=WebApp,name=/foo,Host=bar.com"));

?>

array(4) {
  [":domain:"]=>
  string(5) "resin"
  ["Host"]=>
  string(7) "bar.com"
  ["name"]=>
  string(4) "/foo"
  ["type"]=>
  string(6) "WebApp"
}

mbean_implode

Creates a JMX ObjectName from an array.

<?php

$a = array(":domain:"=>"resin", "type" => "ThreadPool");

var_dump(mbean_implode($a));

?>

resin:type=ThreadPool

MBeanServer

An object representing a JMX MBeanServer.

<?php

$mbeanServer = new MBeanServer();

$threadPool = $mbeanServer->lookup("resin:type=ThreadPool");

echo "thread-max: " . $threadPool->threadMax;

<?php

$mbeanServer = new MBeanServer();

$threadPool = $mbeanServer->lookup("resin:type=ThreadPool");

<?php

$mbeanServer = new MBeanServer();

foreach ($webApp in $mbeanServer->query("resin:type=WebApp,*")) {
  echo $webApp->name . "<br>\n";
}

resin_debug

Write debugging information to the log. The log is at INFO level.

<?php

$a = array("a", "b");

resin_debug("ARRAY: $a[0]");

?>

resin_thread_dump

Produce a thread_dump to the logs. The log is at INFO level.

<?php

$a = array("a"=>"b");

resin_thread_dump();

?>

resin_call_stack

Returns an array containing the current PHP function call stack.

<?php

function foo()
{
  bar();
}

function bar()
{
  var_dump(resin_call_stack());
}

foo();

?>

resin_var_dump

Produce a var_dump to the logs. The log is at INFO level.

<?php

$a = array("a"=>"b");

resin_var_dump($a);

?>

resin_version

Returns the version of Resin running Quercus.

<?php

var_dump(resin_version());

?>

xa_begin

Starts a distributed transaction. All database connections will automatically participate in the transaction. Returns TRUE for success, FALSE for failure.

<?php

xa_begin();

...

xa_commit();
?>

xa_commit

Commits a distributed transaction. All database connections will automatically participate in the transaction. Returns TRUE for success, FALSE for failure.

<?php

xa_begin();

...

xa_commit();
?>

xa_rollback

Rolls back a distributed transaction. All database connections will automatically participate in the transaction. Returns TRUE for success, FALSE for failure.

<?php

xa_begin();

...

xa_rollback();
?>

xa_rollback_only

Marks the current distributed transaction as rollback only. Subsequent attempts to commit the transaction will fail with a warning. Returns TRUE for success, FALSE for failure.

See Also