Docs ExtLibs

Table of Contents Integrating third party libraries Using the PEAR class loader Using the PAT class loader Create your own foreign class loader

Integrating third party libraries

Stubbles supports the integration of other libraries through the concept of foreign class loaders.

A foreign class loader allows to load classes via the Stubbles class loader without putting those classes into the src/main/php directory or into a star file in the lib directory. This can be classes from PEAR or any other repository. Stubbles itself already delivers three foreign class loaders: one for PEAR classes, one for PAT classes and one for classes of the XP-Framework.

A foreign class loader is associated with a given namespace. Let's assume this is examples.foo and there is a foreign class loader registered in the Stubbles class loader, all subsequent requests to stubClassLoader::load() that load classes in the examples.foo namespace will be redirected to the foreign class loader.

Using the PEAR class loader

To make a PEAR class available to the PEAR class loader install the appropiate PEAR package with the default command pear install [PACKAGENAME]. The designated namespace for the PEAR classes is net.php.pear. To load the class XML_Serializer the resulting namespace is net.php.pear.XML.Serializer. Due to the nature of PEAR package names may have to be written fully or partly in uppercase.

#php
<?php
require 'path/to/config/php/config.php';
require stubConfig::getLibPath() . DIRECTORY_SEPARATOR . 'stubbles.php';
stubClassLoader::load('net::stubbles::util::ext::stubPearClassLoader');
stubClassLoader::registerForeignClassLoader(new stubPearClassLoader());
stubClassLoader::load('net::php::pear::XML::Serializer');
var_dump(class_exists('XML_Serializer'));
?>

Using the PAT class loader

To make a PAT class available to the PAT class loader, download and unpack the package from the PAT website or install it using the PEAR package manager.

If you downloaded the package manually, use the following code:

#php
<?php
require 'path/to/config/php/config.php';
require stubConfig::getLibPath() . DIRECTORY_SEPARATOR . 'stubbles.php';
stubClassLoader::load('net::stubbles::util::ext::stubPhpToolClassLoader');
$loader = new stubPearClassLoader('path/to/downloaded/files');

stubClassLoader::registerForeignClassLoader($loader);
stubClassLoader::load('net::php-tools::patError');
var_dump(class_exists('patError'));
?>

If you installed the packages via PEAR installer, you only need to adjust the path, that is passed to the constructor of the class loader:

#php
<?php
require 'path/to/config/php/config.php';
require stubConfig::getLibPath() . DIRECTORY_SEPARATOR . 'stubbles.php';
stubClassLoader::load('net::stubbles::util::ext::stubPhpToolClassLoader');
$loader = new stubPearClassLoader('/path/to/pear/pat');

stubClassLoader::registerForeignClassLoader($loader);
stubClassLoader::load('net::php-tools::patError');
var_dump(class_exists('patError'));
?>

Create your own foreign class loader

To create your own foreign class loader you simply have to implement the [source:trunk/src/main/php/net/stubbles/stubClassLoader.php] interface. The interface must not be loaded, it is always available. The interface consists of three methods:

public function setNamespace($namespace);

Allows to set the namespace where the foreign class loader is responsible for. However it is advisable to set a namespace internally inside the implementing class and use this method only if there is really a need to change the namespace. Warning: changing the namespace after registering the foreign class loader in the Stubbles class loader can result in undefined behaviour.

public function getNamespace();

Returns the namespace where the foreign class loader is responsible for.

public function load($fqClassName)

This method gets a full qualified class name, e.g. your.namespace.YourClass. It is the responsibility of the foreign class loader to check if a class with this name already exists (in case the class has been loaded before but not with the Stubbles class loader) and to load the class if this is not the case.

To register the foreign class loader simply create a new instance of your foreign class loader and register it in the Stubbles class loader:

stubClassLoader::registerForeignClassLoader(new YourClassLoader());