rfc:splclassloader

This is an old revision of the document!


Request for Comments: SplClassLoader

Introduction

PHP 5 introduced the concept of autoloading classes.

However, many different projects adopted their own approach for class loader. In the mid of 2009, several lead developers started an initiative called PHP Standards Group (aka. Framework Interoperability Group), which is mainly focused on interoperability between different Open Source projects.

After an extensive discussions, group came with the primary interoperability between them, which is formally named as PHP Standards Recommendation #0 (or PSR-0).

PSR-0 focus on a flexible autoloader that could be used or shared between projects, structuring and organizing Object Oriented code. So any project that decides to be PSR-0 compliant just need to follow the defines rules defined in the next topic.

Rules

The following rules must be implemented in order to make a project be compliant to PSR-0:

  • A fully-qualified namespace and class must have the following structure \<Vendor Name>\(<Namespace>\)*<Class Name>
  • Each namespace must have a top-level namespace (“Vendor Name”).
  • Each namespace can have as many sub-namespaces as it wishes.
  • Each namespace separator is converted to a DIRECTORY_SEPARATOR when loading from the file system.
  • Each “\_” character in the CLASS NAME is converted to a DIRECTORY_SEPARATOR. The “\_” character has no special meaning in the namespace.
  • The fully-qualified namespace and class is suffixed with “.php” when loading from the file system.
  • Alphabetic characters in vendor names, namespaces, and class names may be of any combination of lower case and upper case.

Usage Examples

The standards we set here should be the lowest common denominator for painless autoloader interoperability. You can test that you are following these standards by utilizing this sample SplClassLoader implementation which is able to load PHP 5.3 classes.

  • \Doctrine\Common\IsolatedClassLoader
    • /path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php
  • \Symfony\Core\Request
    • /path/to/project/lib/vendor/Symfony/Core/Request.php
  • \Zend\Acl
    • /path/to/project/lib/vendor/Zend/Acl.php
  • \Zend\Mail\Message
    • /path/to/project/lib/vendor/Zend/Mail/Message.php
  • \namespace\package\Class_Name
    • /path/to/project/lib/vendor/namespace/package/Class/Name.php
  • \namespace\package_name\Class_Name
    • /path/to/project/lib/vendor/namespace/package_name/Class/Name.php

Example implementation

Below is an example function to simply demonstrate how the above proposed standards are autoloaded.

function autoload($className)
{
    $className = ltrim($className, '\\');
    $fileName  = '';
    $namespace = '';
    if ($lastNsPos = strripos($className, '\\')) {
        $namespace = substr($className, 0, $lastNsPos);
        $className = substr($className, $lastNsPos + 1);
        $fileName  = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
    }
    $fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
 
    require $fileName;
}

SplClassLoader implementation

The following class is a sample SplClassLoader implementation that can load your classes if you follow the autoloader interoperability standards proposed above. It is the current recommended way to load PHP 5.3 classes that follow these standards.

<?php
 
/**
 * SplClassLoader implementation that implements the technical interoperability
 * standards for PHP 5.3 namespaces and class names.
 *
 * http://groups.google.com/group/php-standards/web/final-proposal
 *
 * // Example which loads classes for the Doctrine Common package in the
 * // Doctrine\Common namespace.
 * $classLoader = new SplClassLoader('Doctrine\Common', '/path/to/doctrine');
 * $classLoader->register();
 *
 * @author Jonathan H. Wage <jonwage@gmail.com>
 * @author Roman S. Borschel <roman@code-factory.org>
 * @author Matthew Weier O'Phinney <matthew@zend.com>
 * @author Kris Wallsmith <kris.wallsmith@gmail.com>
 * @author Fabien Potencier <fabien.potencier@symfony-project.org>
 */
class SplClassLoader
{
    private $_fileExtension = '.php';
    private $_namespace;
    private $_includePath;
    private $_namespaceSeparator = '\\';
 
    /**
     * Creates a new <tt>SplClassLoader</tt> that loads classes of the
     * specified namespace.
     *
     * @param string $ns The namespace to use.
     */
    public function __construct($ns = null, $includePath = null)
    {
        $this->_namespace = $ns;
        $this->_includePath = $includePath;
    }
 
    /**
     * Sets the namespace separator used by classes in the namespace of this class loader.
     *
     * @param string $sep The separator to use.
     */
    public function setNamespaceSeparator($sep)
    {
        $this->_namespaceSeparator = $sep;
    }
 
    /**
     * Gets the namespace seperator used by classes in the namespace of this class loader.
     *
     * @return void
     */
    public function getNamespaceSeparator()
    {
        return $this->_namespaceSeparator;
    }
 
    /**
     * Sets the base include path for all class files in the namespace of this class loader.
     *
     * @param string $includePath
     */
    public function setIncludePath($includePath)
    {
        $this->_includePath = $includePath;
    }
 
    /**
     * Gets the base include path for all class files in the namespace of this class loader.
     *
     * @return string $includePath
     */
    public function getIncludePath()
    {
        return $this->_includePath;
    }
 
    /**
     * Sets the file extension of class files in the namespace of this class loader.
     *
     * @param string $fileExtension
     */
    public function setFileExtension($fileExtension)
    {
        $this->_fileExtension = $fileExtension;
    }
 
    /**
     * Gets the file extension of class files in the namespace of this class loader.
     *
     * @return string $fileExtension
     */
    public function getFileExtension()
    {
        return $this->_fileExtension;
    }
 
    /**
     * Installs this class loader on the SPL autoload stack.
     */
    public function register()
    {
        spl_autoload_register(array($this, 'loadClass'));
    }
 
    /**
     * Uninstalls this class loader from the SPL autoloader stack.
     */
    public function unregister()
    {
        spl_autoload_unregister(array($this, 'loadClass'));
    }
 
    /**
     * Loads the given class or interface.
     *
     * @param string $className The name of the class to load.
     * @return void
     */
    public function loadClass($className)
    {
        if (null === $this->_namespace || $this->_namespace . $this->_namespaceSeparator === substr($className, 0, strlen($this->_namespace . $this->_namespaceSeparator))) {
            $fileName = '';
            $namespace = '';
            if (false !== ($lastNsPos = strripos($className, $this->_namespaceSeparator))) {
                $namespace = substr($className, 0, $lastNsPos);
                $className = substr($className, $lastNsPos + 1);
                $fileName = str_replace($this->_namespaceSeparator, DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
            }
            $fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . $this->_fileExtension;
 
            require ($this->_includePath !== null ? $this->_includePath . DIRECTORY_SEPARATOR : '') . $fileName;
        }
    }
}

Example usage

$classLoader = new SplClassLoader('Doctrine\Common', '/path/to/doctrine');
$classLoader->register();

Proposal and Patch

The final release version of PSR-0 is available at: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md

A C extension is already available for usage, and can be grabbed at http://github.com/metagoto/splclassloader

Main purpose of this proposal is to suport both PEAR style directory organization and also Namespace directory organization.

Changelog

2011-10-24 Guilherme Blanco: Expanded RFC documentation. 2010-03-22 Guilherme Blanco: Initial RFC creation.

rfc/splclassloader.1319508109.txt.gz · Last modified: 2017/09/22 13:28 (external edit)