Examples

Injection in REST handlers

2013-03-01T11:11:42+01:00

The new REST API brings XPCLI-like @inject handling to REST handlers. Although this is not a full-featured IOC container, you can have the log categories, properties and the invocation context injected into your REST resource handler class.

To accomplish this, decorate methods with the afforementioned @inject annotation. Here's an example:

  /**
   * Sets a logger category for debugging
   */
  #[@inject(name = 'trace')]
  public function setTrace(LogCategory $cat= NULL) {
    $this->cat= $cat;
  }

Some more details:

Properties can be injected via util.Properties and must supply a name
Log categories are retrieved via util.log.LogCategory and can supply a name - if omitted, the scriptlet's trace is used (this is previously set via debug="TRACE" inside web.ini).
The invocation context can be used for marshalling and exception mapping customizations. Its type is webservices.rest.srv.RestContext

New Package::getComment() method

2012-06-07T15:38:00+02:00

With the implementation of the feature suggested in pull request #139, there's now a new method in the lang.reflect.Package class, public string getComment(). It returns the api doc comment of the package-info.xp file, if existant, NULL otherwise.

Example
To add package documentation (this is also picked up by the doclet API and te api doc generator!), add a file called package-info.xp alongside with the package directory. Here's an example (goes in net/xp_framework/tutorial/package-info.xp):

<?php
/* This file is part of the XP framework
 *
 * $Id$
 */
  
/**
 * The XP tutorial package
 *
 * @see  http://xp-framework.net/
 */
package net.xp_framework.tutorial {
}
?>

Invoking Package::forName('net.xp_framework.tutorial')->getComment() will then return the string "The XP tutorial package".

One possible use could be XP Tools: Command line reflection + "-v" and "-vv".

PHP Namespaces and the XP Framework

2012-01-06T15:31:22+01:00

With the implementation of RFC #0222, we have added optional PHP namespaces support to the XP Framework. Optional means the XP Framework itself will neither depend on PHP 5.3 (still supporting PHP 5.2.10 upward at least for the 5.9-SERIES) nor will it change any of its classes to use them. That doesn't mean you can't use them, though

Here's a quick-start guide:

PHP namespaces use the backslash (\). These translate 1:1 to the package separator in the XP Framework, the dot (.).
Classes with PHP namespaces, fully-qualified and non-qualified XP classes may be mixed in one project. The XP group recommends migrating complete packages.
Inside classes using PHP namespaces, other XP classes need to be either addressed by their absolute fully-qualified names (e.g. \lang\Object) or imported via the use statement by their fully-qualified names; uses() may not be used there.
Inside classes not using PHP namespaces, namespaced classes must be added to the uses() list and addressed in their namespaced version.

As an example, if we have the following in de/thekid/tools/SQL.class.php:

  namespace de\thekid\tools;
  use rdbms\DriverManager;
  
  class SQL extends \lang\Object {
    public static function main(array $args) {
      $conn= DriverManager::getConnection($args[0]);
      // ...
    }
  }

To run this class, use xp de.thekid.tools.SQL ... as you would with a non-namespaced class.

Available database drivers

2011-01-16T22:45:39+01:00

Here's how to find out which database drivers are available (keys) - and what classes they're implemented by (values):

Console::writeLine(DriverManager::getInstance()->drivers);This will yield, depending on the PHP installation and configuration, something along the lines of:
[ mysql => lang.XPClass<rdbms.mysql.MySQLConnection> pgsql => lang.XPClass<rdbms.pgsql.PostgreSQLConnection> sqlite => lang.XPClass<rdbms.sqlite.SQLiteConnection> ]

ZIP files now support Unicode filenames

2011-01-16T17:15:50+01:00

The XP Framework's io.archive.zip package allows reading and creating ZIP files and is tested against zip archives created by Info-ZIP 3.0, PHP's Zip class, 7-zip, WinRAR and Windows' "compressed folders".

In SVN head, we have made a couple of adjustments to be able to support files written by Java's java.util.zip package (which is internally used by the jar command):

Reading the central directory to find the compressed and uncompressed lengths, Java doesn't write this into the local file header - making it impossible to stream those files
Supporting character set detection on extraction - up until JDK7 Build 57, the Java API was incorrectly writing entry names in UTF-8 but not setting the so-called "Language Encoding bit (EFS)".
Supporting to write archives with Unicode names - a JDK build downloaded yesterday still chokes on non-Unicode filenames inside ZIP archives when no charset is given (default is "CP437" here).

This way we can now create JAR files, for example.

The new lang.Closeable interface and ARM blocks

2010-12-31T09:41:43+01:00

The new lang.Closeable interface and the io.streams classes being retrofitted to implement it may not seem very useful on the first glance, although they serve the purpose of supporting the so-called ARM blocks. These are a feature supported by XP Language and reuse the try keyword:

  try ($expression[, $expression[, ...]]) {
    // Statements
  }

Any of the expressions are expected to be instanceof lang.Closeable and their close() methods are guaranteed to be called in the declaration order regardless of whether the block raises an exception or not.

Hudson and the xml.meta API

2010-12-30T21:48:23+01:00

I'm currently working on a Hudson remoting API to be able to remotely configure our continuous integration projects. An example usecase occurred today: A co-worker had created a Hudson plugin which helps us distinguish projects with no tests at all from projects with tests exist: It display a different icon in the "weather" column and sets the build status to unstable. Now what we want to do is to enable this plugins in all projects, which would mean clicking through an odyssee of "Select Project - Configure - Enable - Save" more than 70 times in the frontend.

Hudson contains a PHP: 62 characters to see all MySQL queries, I thought I'd post a similar use case solution here. The task is to log all SQL queries and a backtrace of where they're executed from. In Ulf's post, this is accomplished by an extension function written in C, which needs to be compiled and loaded into PHP.

Altough a nice feature, this way has several downsides, first of all, the compilation, a hurdle big enough to keep me from trying it out, and second, it's only going to work with MySQL databases (and to be precise, only those newer than 4.0, because mysqlnd doesn't support MySQL's old password protocol handshake).

First steps with the XP Language

2010-09-24T10:22:00+02:00

The XP language is not completely different from the way PHP works, it keeps the flexibility and the general "look and feel" while adding syntactical support for features PHP doesn't support or doesn't support in all versions the XP Framework runs on.

Like in the XP framework, the entry point is always a class. In their most simple form, these classes have a static main() method. An example:

  public class HelloWorld {
    public static void main(string[] $args) {
      util.cmd.Console::writeLine('Hello World from ', self::class.getName(), '!');
    }
  }

OK, this doesn't look too unfamiliar, does it?

5.8 Feature showcase: Accessing class interna

2010-08-30T08:40:33+02:00

The XP Framework's 5.8-SERIES contains a feature that will allow the reflection API to access private and protected members. Of course, just because you can, doesn't mean you should, as this does allow you to // OK
$v[]= "Hello";

// Throws a lang.IllegalArgumentException
$v[]= 1;
Primitives can also be used in other generic collections types, e.g. Set and Map implementations as well as Stack and Queue.

Fluent XML with the XP Framework

2010-06-22T10:00:00+02:00

To create an XML tree programmatically, the XP Framework has offered the xml.Tree class since its beginning in 2001. Recently, we've added a fluent interface to it, allowing for the following:

  $t= create(new Tree())->withRoot(create(new Node('book'))
    ->withChild(new Node('author', 'Timm'))
    ->withChild(new Node('isbn', '978-0000000000'))
    ->withChild(new Node('title', 'Fluent XML with the XP Framework'))
  );

Merging XAR files

2010-01-30T15:05:05+01:00

With the 5.7.7-RELEASE there has a nitfy small feature been added to the xar command: merging multiple XAR files. XAR files are the archives in which XP Framework applications can ship their classes and/or resource files in a way comparable to Java`s .jar-files.

Combining multiple xar files into one can be handy one the one hand, because you can merge all dependencies and the application itself into one single file and only have to provide the one. On the other hand, for applications where startup or I/O performance is a concern, it can be useful: each xar file involved in an application comes with a startup time penalty - the file must be opened, the index must be read before the first file can be retrieved. Here, a single file instead of many files mean increased startup performance and less I/O calls of an application.

This is how it works:


Alex@mobile ~/dev/xp.public/trunk
$ xar cf one.xar ChangeLog

Alex@mobile ~/dev/xp.public/trunk
$ xar cf two.xar skeleton/VERSION=VERSION

Alex@mobile ~/dev/xp.public/trunk
$ xar mf merge.xar one.xar two.xar

Alex@mobile ~/dev/xp.public/trunk
$ xar tvf merge.xar
    58.978 ChangeLog
        10 VERSION

Reading gzip'ed websites

2010-01-08T20:44:56+01:00

To reduce bandwidth some servers have their content zipped using solutions such as Apache's mod_deflate. This is done only if the Accept-Encoding request header contains the string gzip. Combining the XP Framework's peer.http API with the new io.streams.GzDecompressingInputStream one can accomplish this compression:

  $conn= new HttpConnection($args[0]);
  $response= $conn->get(array(), array('Accept-Encoding' => 'gzip'));
  
  if ('gzip' == $response->getHeader('Content-Encoding')) {
    $in= new GzDecompressingInputStream($r->getInputStream());
  } else {
    $in= $r->getInputStream();
  }
  
  // Now read $in as with any other stream...

Compressing data

2010-01-06T17:09:40+01:00

The possibly easiest way to compress data in PHP is to use the string-in, string-out functions such as gzdeflate or bzcompress. For small number of bytes being passed in, this is fast and convenient, but it doesn't do well when working with large files, for example:

  FileUtil::setContents(
    $out, 
    gzdeflate(FileUtil::getContents($in))
  );

In one test I ran here, this piece of code used roughly 50MB peaks to compress a 26 MB input file. As of 5.7.7, the XP Framework will provide compressing output streams enabling you to compress one chunk at a time and saving more than 90% of memory:

  $is= $in->getInputStream();
  $os= new DeflatingOutputStream($out->getOutputStream());
  while ($is->available() > 0) {
    $os->write($is->read());
  }
  $is->close();
  $os->close()@inject annotation you no longer have to specify the type parameter if you use a so-called "type hint" - so instead of writing the following:
  #[@inject(type= 'rdbms.DBConnection', name= 'caffeine')]
  public function setConnection(DBConnection $conn) { ... }...you can now omit the type part - it will be inferred from the first parameter's type:
  #[@inject(name= 'caffeine')]
  public function setConnection(DBConnection $conn) { ... }



New xml.Node::withChild() method
2009-09-21T15:04:34+02:00
To easily create XML documents, the xml.Node class has been extended with a new withChild() method complementing addChild(). In contrast to the latter, withChild() returns the node the child was added to instead of the added child.


Unified runners in the web
2009-08-11T17:30:00+02:00
The XP framework had offered developers the power of an easy class loading setup via the new XP runners that are delivered with every release since several releases now. These runners have proven themselves very useful in day-to-day business, so we're working on porting them to the web!

With the so-called web-runners these new cool and useful features will become available for you:
Easier classpath setup
Classpaths will be constructed from .pth files, in the same manner as xpcli does it.

No boilerplate "index.php"s any more
you won't need the same index.php over and over in every project again; even more: you don't need any entrypoint .php any more even for SOAP- or JSON-endpoints.

Multiple etc/ configuration directories
you can switch between multipe etc/, eg. one for the test server and one for production, by changing a single file

Overwrite arbitrary settings for special servers
you can overwrite settings, eg. debugging settings, based on where your application runs - eg. on the development machine, you can have debugging enabled, while on production it's disabled. You don't need to have different files for them - no more mistakenly committed debug settings.

This article shows you how you can make use of the web runners in a XP application. Read on for more information!


Redirecting console output
2009-07-12T18:11:38+02:00
To capture output written by any of the PHP functions the ouput control functions can be used (ob_start(), ob_get_contents() and friends). These functions do not affect the output made by the util.cmd.Console class as this writes directly to the standard out and error streams. To redirect these, you can use the following:

  // Save original stream in variable, change output stream to $stream
  $out= Console::$out->getStream();
  Console::$out->setStream($stream);
  
  // Write "Hello" and a newline, this will trigger $stream's write() method
  Console::writeLine('Hello');
  
  // Finally, restore original output stream  
  Console::$out->setStream($out);
This can be useful in unittests, when running command line applications inside a web container or inside GUIs, or whatever other usecase you can invent