rfc:splclassloader
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
rfc:splclassloader [2011/10/25 01:46] – [Example implementation] guilhermeblanco | rfc:splclassloader [2012/11/19 06:42] – [Request for Comments: SplClassLoader] levim | ||
---|---|---|---|
Line 3: | Line 3: | ||
* Date: 2010-03-22 | * Date: 2010-03-22 | ||
* Author: Guilherme Blanco < | * Author: Guilherme Blanco < | ||
- | * Status: | + | * Status: |
+ | * Voting results at https:// | ||
* First Published at: http:// | * First Published at: http:// | ||
Line 25: | Line 26: | ||
* Each namespace can have as many sub-namespaces as it wishes. | * 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 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. | + | * Each " |
* The fully-qualified namespace and class is suffixed with " | * The fully-qualified namespace and class is suffixed with " | ||
* Alphabetic characters in vendor names, namespaces, and class names may be of any combination of lower case and upper case. | * Alphabetic characters in vendor names, namespaces, and class names may be of any combination of lower case and upper case. | ||
- | ===== Usage Examples ===== | + | ===== Extended Rules for Proposal ===== |
+ | |||
+ | Together with PSR-0 rules, for SplClassLoader we would also include a few valid rules that must be implemented, | ||
+ | |||
+ | * Allow a namespace to be mapped through multiple paths. | ||
+ | * Make SplClassLoader silently fails if class is not found. This one is useful when using multiple instances of SplClassLoader in a single script. | ||
+ | * Allow SplClassLoader to lookup in include_path. This is useful for projects that define their own on include_path, | ||
+ | |||
+ | ===== Flexibility of a Rule ===== | ||
+ | |||
+ | Even though PSR-0 is strict, PHP cannot force php extension. Ideally, the file extension is customizable, | ||
+ | |||
+ | ===== Initial missing support ===== | ||
+ | |||
+ | PHP does not provide a single approach for any OO based autoloader, so initially a new interface is required, for anyone interested to implement their own Autoloader. From now on, let's name it as SplAutoloader. | ||
+ | The purpose of this interface is to bring the minimum contract that any interested to autoload their resources should follow. | ||
+ | Here is the proposed implementation: | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * SplAutoloader defines the contract that any OO based autoloader must follow. | ||
+ | * | ||
+ | * @author Guilherme Blanco < | ||
+ | */ | ||
+ | interface SplAutoloader | ||
+ | { | ||
+ | /** | ||
+ | * Defines autoloader to work silently if resource is not found. | ||
+ | * | ||
+ | * @const | ||
+ | */ | ||
+ | const MODE_SILENT = 0; | ||
+ | |||
+ | /** | ||
+ | * Defines autoloader to work normally (requiring an un-existent resource). | ||
+ | * | ||
+ | * @const | ||
+ | */ | ||
+ | const MODE_NORMAL = 1; | ||
+ | |||
+ | /** | ||
+ | * Defines autoloader to work in debug mode, loading file and validating requested resource. | ||
+ | * | ||
+ | * @const | ||
+ | */ | ||
+ | const MODE_DEBUG = 2; | ||
+ | |||
+ | /** | ||
+ | * Define the autoloader work mode. | ||
+ | * | ||
+ | * @param integer $mode Autoloader work mode. | ||
+ | */ | ||
+ | public function setMode($mode); | ||
+ | |||
+ | /** | ||
+ | * Add a new resource lookup path. | ||
+ | * | ||
+ | * @param string $resourceName Resource name, namespace or prefix. | ||
+ | * @param mixed $resourcePath Resource single path or multiple paths (array). | ||
+ | */ | ||
+ | public function add($resourceName, | ||
+ | |||
+ | /** | ||
+ | * Load a resource through provided resource name. | ||
+ | * | ||
+ | * @param string $resourceName Resource name. | ||
+ | */ | ||
+ | public function load($resourceName); | ||
+ | |||
+ | /** | ||
+ | * Register this as an autoloader instance. | ||
+ | * | ||
+ | * @param boolean Whether to prepend the autoloader or not in autoloader' | ||
+ | */ | ||
+ | public function register($prepend = false); | ||
+ | |||
+ | /** | ||
+ | * Unregister this autoloader instance. | ||
+ | * | ||
+ | */ | ||
+ | public function unregister(); | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===== 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. | 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. | ||
Line 46: | Line 131: | ||
* / | * / | ||
- | ===== Example implementation ===== | + | ===== Examples of usage ===== |
+ | |||
+ | Autoloading Doctrine 2: | ||
+ | |||
+ | <code php> | ||
+ | $classLoader = new \SplClassLoader(); | ||
+ | $classLoader-> | ||
+ | '/ | ||
+ | )); | ||
+ | $classLoader-> | ||
+ | </ | ||
+ | |||
+ | Autoloading PEAR1: | ||
+ | |||
+ | <code php> | ||
+ | $classLoader = new \SplClassLoader(); | ||
+ | $classLoader-> | ||
+ | $classLoader-> | ||
+ | $classLoader-> | ||
+ | $classLoader-> | ||
+ | </ | ||
+ | |||
+ | Autoloading in debug mode: | ||
+ | |||
+ | <code php> | ||
+ | $classLoader = new \SplClassLoader(); | ||
+ | $classLoader-> | ||
+ | $classLoader-> | ||
+ | $classLoader-> | ||
+ | $classLoader-> | ||
+ | </ | ||
+ | |||
+ | ===== Example | ||
Below is an example function to simply demonstrate how the above proposed standards are autoloaded. | Below is an example function to simply demonstrate how the above proposed standards are autoloaded. | ||
Line 56: | Line 173: | ||
$fileName | $fileName | ||
$namespace = ''; | $namespace = ''; | ||
+ | | ||
if ($lastNsPos = strripos($className, | if ($lastNsPos = strripos($className, | ||
$namespace = substr($className, | $namespace = substr($className, | ||
Line 61: | Line 179: | ||
$fileName | $fileName | ||
} | } | ||
+ | | ||
$fileName .= str_replace(' | $fileName .= str_replace(' | ||
Line 66: | Line 185: | ||
} | } | ||
</ | </ | ||
+ | |||
+ | ===== 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. | ||
+ | |||
+ | <code php> | ||
+ | /** | ||
+ | * SplClassLoader implementation that implements the technical interoperability | ||
+ | * standards for PHP 5.3 namespaces and class names. | ||
+ | * | ||
+ | * https:// | ||
+ | * | ||
+ | * Example usage: | ||
+ | * | ||
+ | | ||
+ | * | ||
+ | | ||
+ | | ||
+ | * | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | * | ||
+ | | ||
+ | | ||
+ | * | ||
+ | | ||
+ | | ||
+ | * | ||
+ | | ||
+ | | ||
+ | * | ||
+ | | ||
+ | | ||
+ | * | ||
+ | | ||
+ | | ||
+ | * | ||
+ | * @author Guilherme Blanco < | ||
+ | * @author Jonathan H. Wage < | ||
+ | * @author Roman S. Borschel < | ||
+ | * @author Matthew Weier O' | ||
+ | * @author Kris Wallsmith < | ||
+ | * @author Fabien Potencier < | ||
+ | */ | ||
+ | class SplClassLoader implements SplAutoloader | ||
+ | { | ||
+ | /** | ||
+ | * @var string | ||
+ | */ | ||
+ | private $fileExtension = ' | ||
+ | | ||
+ | /** | ||
+ | * @var boolean | ||
+ | */ | ||
+ | private $includePathLookup = false; | ||
+ | | ||
+ | /** | ||
+ | * @var array | ||
+ | */ | ||
+ | private $resources = array(); | ||
+ | | ||
+ | /** | ||
+ | * @var integer | ||
+ | */ | ||
+ | private $mode = self:: | ||
+ | |||
+ | /** | ||
+ | * {@inheritdoc} | ||
+ | */ | ||
+ | public function setMode($mode) | ||
+ | { | ||
+ | if ($mode & self:: | ||
+ | throw new \InvalidArgumentException( | ||
+ | sprintf(' | ||
+ | ); | ||
+ | } | ||
+ | | ||
+ | $this-> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * Define the file extension of resource files in the path of this class loader. | ||
+ | * | ||
+ | * @param string $fileExtension | ||
+ | */ | ||
+ | public function setFileExtension($fileExtension) | ||
+ | { | ||
+ | $this-> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * Retrieve the file extension of resource files in the path of this class loader. | ||
+ | * | ||
+ | * @return string | ||
+ | */ | ||
+ | public function getFileExtension() | ||
+ | { | ||
+ | return $this-> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * Turns on searching the include for class files. Allows easy loading installed PEAR packages. | ||
+ | * | ||
+ | * @param boolean $includePathLookup | ||
+ | */ | ||
+ | public function setIncludePathLookup($includePathLookup) | ||
+ | { | ||
+ | $this-> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * Gets the base include path for all class files in the namespace of this class loader. | ||
+ | * | ||
+ | * @return boolean | ||
+ | */ | ||
+ | public function getIncludePathLookup() | ||
+ | { | ||
+ | return $this-> | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * {@inheritdoc} | ||
+ | */ | ||
+ | public function register($prepend = false) | ||
+ | { | ||
+ | spl_autoload_register(array($this, | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * {@inheritdoc} | ||
+ | */ | ||
+ | public function unregister() | ||
+ | { | ||
+ | spl_autoload_unregister(array($this, | ||
+ | } | ||
+ | | ||
+ | /** | ||
+ | * {@inheritdoc} | ||
+ | */ | ||
+ | public function add($resource, | ||
+ | { | ||
+ | $this-> | ||
+ | } | ||
+ | | ||
+ | /** | ||
+ | * {@inheritdoc} | ||
+ | */ | ||
+ | public function load($resourceName) | ||
+ | { | ||
+ | $resourceAbsolutePath = $this-> | ||
+ | | ||
+ | switch (true) { | ||
+ | case ($this-> | ||
+ | if ($resourceAbsolutePath !== false) { | ||
+ | require $resourceAbsolutePath; | ||
+ | } | ||
+ | break; | ||
+ | | ||
+ | case ($this-> | ||
+ | default: | ||
+ | require $resourceAbsolutePath; | ||
+ | break; | ||
+ | } | ||
+ | | ||
+ | if ($this-> | ||
+ | throw new \RuntimeException( | ||
+ | sprintf(' | ||
+ | ); | ||
+ | } | ||
+ | } | ||
+ | | ||
+ | /** | ||
+ | * Transform resource name into its absolute resource path representation. | ||
+ | * | ||
+ | * @params string $resourceName | ||
+ | * | ||
+ | * @return string Resource absolute path. | ||
+ | */ | ||
+ | private function getResourceAbsolutePath($resourceName) | ||
+ | { | ||
+ | $resourceRelativePath = $this-> | ||
+ | | ||
+ | foreach ($this-> | ||
+ | if (strpos($resourceName, | ||
+ | continue; | ||
+ | } | ||
+ | | ||
+ | foreach ($resourcesPath as $resourcePath) { | ||
+ | $resourceAbsolutePath = $resourcePath . DIRECTORY_SEPARATOR . $resourceRelativePath; | ||
+ | | ||
+ | if (is_file($resourceAbsolutePath)) { | ||
+ | return $resourceAbsolutePath; | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | | ||
+ | if ($this-> | ||
+ | return $resourceAbsolutePath; | ||
+ | } | ||
+ | | ||
+ | return false; | ||
+ | } | ||
+ | | ||
+ | /** | ||
+ | * Transform resource name into its relative resource path representation. | ||
+ | * | ||
+ | * @params string $resourceName | ||
+ | * | ||
+ | * @return string Resource relative path. | ||
+ | */ | ||
+ | private function getResourceRelativePath($resourceName) | ||
+ | { | ||
+ | // We always work with FQCN in this context | ||
+ | $resourceName = ltrim($resourceName, | ||
+ | $resourcePath = ''; | ||
+ | | ||
+ | if (($lastNamespacePosition = strrpos($resourceName, | ||
+ | // Namespaced resource name | ||
+ | $resourceNamespace = substr($resourceName, | ||
+ | $resourceName | ||
+ | $resourcePath | ||
+ | } | ||
+ | | ||
+ | return $resourcePath . str_replace(' | ||
+ | } | ||
+ | | ||
+ | /** | ||
+ | * Check if resource is declared in user space. | ||
+ | * | ||
+ | * @params string $resourceName | ||
+ | * | ||
+ | * @return boolean | ||
+ | */ | ||
+ | private function isResourceDeclared($resourceName) | ||
+ | { | ||
+ | return class_exists($resourceName, | ||
+ | || interface_exists($resourceName, | ||
+ | || (function_exists(' | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | If any interested wants to customize the public methods, like caching through APC to reduce I/O, it should be possible to extend SplClassLoader and overwrite the public methods. | ||
===== Proposal and Patch ===== | ===== Proposal and Patch ===== | ||
- | The proposal and PHP implementation | + | The final release version of PSR-0 is available |
- | Main purpose of this proposal | + | |
+ | < | ||
+ | |||
+ | An extension | ||
- | A C extension | + | Main purpose of this proposal |
===== Changelog ===== | ===== Changelog ===== | ||
- | 2010-03-22 Guilherme Blanco: Initial RFC creation. | + | * 2011-11-09 Christian Kaps: Update examples to use the new interface(setMode) |
+ | * 2011-11-08 Guilherme Blanco: Removed constructor prototype and created setMode. | ||
+ | * 2011-11-08 Guilherme Blanco: Updated SplClassLoader implementation. | ||
+ | * 2011-11-07 Guilherme Blanco: Expanded extended rules. | ||
+ | * 2011-10-25 David Coallier: Added the new SPL patch information and feature request link. | ||
+ | * 2011-10-24 Guilherme Blanco: Expanded RFC documentation. Put it as ready for review. | ||
+ | * 2010-03-22 Guilherme Blanco: Initial RFC creation. | ||
+ | ===== Comments ===== | ||
+ | * laruence : I have already got a similar loader implemented in Yaf, called Yaf_Loader, you can found the source here: [[http:// |
rfc/splclassloader.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1