The Stubbles class loader

In Stubbles, classes are organized in packages (like Java), which are represented by directories. When ever loading a class from a Stubbles package, we advise you to use the stubClassLoader class instead of require or include. This has several advantages:

• The class loader knows, where to find the classes, regardless of the include_path setting
• The class loader remembers, which classes already had been loaded and does not load or search for a class twice
• All Stubbles classes use the Stubbles class loader and by using it in your own files, you prevent conflicts

Usage

The only time, you should use the require statement is when loading the class loader:

<?php
require 'path/to/config/php/config.php'; // contains class stubConfig
require stubConfig::getLibPath() . '/stubbles.php';
?>

From now own, use the load() method of the stubClassLoader class:

<?php
stubClassLoader::load('net::stubbles::reflection::stubReflectionClass');
?>

You may also pass more than one class to this method:

<?php
stubClassLoader::load('net::stubbles::reflection::stubReflectionClass',
                      'net::stubbles::xml::stubDomStreamWriter'
);
?>

Most of the Stubbles packages provide one file that you can use to bootstrap all of the important classes of the package:

<?php
stubClassLoader::load('net::stubbles::event::event');
?>

Advanced Features

XJConf and automatic class loading

If you want to use Stubbles classes via XJConf, you may use the net::stubbles::util::xjconf::stubXJConfLoader.

Class Registry

The stubClassLoader can be used as a class registry as well. It knows the non- and the full qualified class name of every class that was loaded via the stubClassLoader.

<?php
// displays 'MyExampleClass'
echo stubClassLoader::getNonQualifiedClassName('example::MyExampleClass');

// displays 'null'
var_dump(stubClassLoader::getFullQualifiedClassName('MyExampleClass'));
stubClassLoader::load('example::MyExampleClass');
// displays 'example::MyExampleClass (length=22)'
var_dump(stubClassLoader::getFullQualifiedClassName('MyExampleClass'));
?>

It is possible to translate full qualified class names into non qualified class names at every time. However it is not possible to translate a non qualified class name into a full qualified class name until the class has been loaded via the load() method.

Static initializing

If the class to load contains a __static() method the stubClassLoader will execute this method right after loading the class. The method signature has to be public static function __static(), else this will fail or result in undefined behaviour. Because stubClassLoader takes care that every class is only loaded once this method will only be executed once, at the first loading of the class.

Assume the following class:

<?php
class WithStatic
{
    private static $called = 0;
    
    public static function __static()
    {
        self::$called++;
    }
    
    public static function getCalled()
    {
        echo 'WithStatic::__static() has been called ' . self::$called . ' times.';
    }
}
?>

Now we load the class:

<?php
stubClassLoader::load('example::WithStatic');
stubClassLoader::load('example::WithStatic'); // load a second time to demonstrate the behaviour
WithStatic::getCalled();
?>

The result will be:

WithStatic::__static() has been called 1 times.

Foreign class loaders

Foreign class loaders allow you to load classes from any other framework or library through the Stubbles class loader mechanism. See the documentation on integrating third party libraries for more information.