From 2b5d958b5105e06c6eef8381a418a64e3b8e983a Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Thu, 5 May 2016 09:46:47 -0500 Subject: [PATCH 1/4] Prepared documentation for publication - Converted from bookdown to mkdocs. - Renamed files to remove `zend.locator.` prefix. - Checked and corrected all headers. (Fixes #3) - Checked and corrected all code blocks. (Fixes #4) - Checked and corrected all tables. (Fixes #6) - Checked and corrected all blockquotes. (Fixes #7) - Reviewed and edited for content and formatting. (Fixes #5) --- README.md | 5 +- doc/book/autoloader-factory.md | 114 +++++++ doc/book/class-map-autoloader.md | 168 +++++++++++ doc/book/classmap-generator.md | 28 ++ doc/book/index.html | 10 + doc/book/index.md | 1 + doc/book/module-autoloader.md | 111 +++++++ doc/book/plugin-class-loader.md | 295 +++++++++++++++++++ doc/book/plugin-class-locator.md | 54 ++++ doc/book/short-name-locator.md | 67 +++++ doc/book/spl-autoloader.md | 131 ++++++++ doc/book/standard-autoloader.md | 244 +++++++++++++++ doc/book/zend.loader.autoloader-factory.md | 117 -------- doc/book/zend.loader.class-map-autoloader.md | 173 ----------- doc/book/zend.loader.classmap-generator.md | 43 --- doc/book/zend.loader.module-autoloader.md | 111 ------- doc/book/zend.loader.plugin-class-loader.md | 276 ----------------- doc/book/zend.loader.plugin-class-locator.md | 55 ---- doc/book/zend.loader.short-name-locator.md | 67 ----- doc/book/zend.loader.spl-autoloader.md | 128 -------- doc/book/zend.loader.standard-autoloader.md | 223 -------------- doc/bookdown.json | 15 - mkdocs.yml | 18 ++ 23 files changed, 1243 insertions(+), 1211 deletions(-) create mode 100644 doc/book/autoloader-factory.md create mode 100644 doc/book/class-map-autoloader.md create mode 100644 doc/book/classmap-generator.md create mode 100644 doc/book/index.html create mode 120000 doc/book/index.md create mode 100644 doc/book/module-autoloader.md create mode 100644 doc/book/plugin-class-loader.md create mode 100644 doc/book/plugin-class-locator.md create mode 100644 doc/book/short-name-locator.md create mode 100644 doc/book/spl-autoloader.md create mode 100644 doc/book/standard-autoloader.md delete mode 100644 doc/book/zend.loader.autoloader-factory.md delete mode 100644 doc/book/zend.loader.class-map-autoloader.md delete mode 100644 doc/book/zend.loader.classmap-generator.md delete mode 100644 doc/book/zend.loader.module-autoloader.md delete mode 100644 doc/book/zend.loader.plugin-class-loader.md delete mode 100644 doc/book/zend.loader.plugin-class-locator.md delete mode 100644 doc/book/zend.loader.short-name-locator.md delete mode 100644 doc/book/zend.loader.spl-autoloader.md delete mode 100644 doc/book/zend.loader.standard-autoloader.md delete mode 100644 doc/bookdown.json create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index 001c033..533f8ce 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,7 @@ [![Build Status](https://secure.travis-ci.org/zendframework/zend-loader.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-loader) [![Coverage Status](https://coveralls.io/repos/zendframework/zend-loader/badge.svg?branch=master)](https://coveralls.io/r/zendframework/zend-loader?branch=master) -`Zend\Loader` provides different strategies for autoloading PHP classes. - +zend-loader provides different strategies for autoloading PHP classes. - File issues at https://github.com/zendframework/zend-loader/issues -- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-loader +- Documentation is at https://zendframework.github.io/zend-loader/ diff --git a/doc/book/autoloader-factory.md b/doc/book/autoloader-factory.md new file mode 100644 index 0000000..775df5a --- /dev/null +++ b/doc/book/autoloader-factory.md @@ -0,0 +1,114 @@ +# The AutoloaderFactory + +zend-loader provides multiple autoloader strategies. +`Zend\Loader\AutoloaderFactory` allows you to define configuration for each +strategy you wish to use and register them at once. As an example, you may have +a class map for your most used classes, but want to use a PSR-0 style autoloader +for 3rd party libraries. The factory uses configuration, allowing you to cache +your autoloader definitions or define them centrally for your application. + +## Quick Start + +The `AutoloaderFactory` expects an array of configuration. + +```php +$config = [ + 'Zend\Loader\ClassMapAutoloader' => [ + 'application' => APPLICATION_PATH . '/.classmap.php', + 'zf' => APPLICATION_PATH . '/../library/Zend/.classmap.php', + ], + 'Zend\Loader\StandardAutoloader' => [ + 'namespaces' => [ + 'Phly\Mustache' => APPLICATION_PATH . '/../library/Phly/Mustache', + 'Doctrine' => APPLICATION_PATH . '/../library/Doctrine', + ], + ], +]; +``` + +Once you have your configuration in a PHP array, pass it to the +`AutoloaderFactory`: + +```php +// This example assumes that the AutoloaderFactory is itself autoloadable! +use Zend\Loader\AutoloaderFactory; + +AutoloaderFactory::factory($config); +``` + +The `AutoloaderFactory` will instantiate each autoloader with the given options, +and also call its `register()` method to register it with the SPL autoloader. + +## Configuration options + +The `AutoloaderFactory` expects an associative array or `Traversable` object. +Keys should be valid autoloader class names, and the values should be the +options that should be passed to the class constructor. + +Internally, the `AutoloaderFactory` checks to see if the autoloader class +referenced exists. If not, it will use the [StandardAutoloader](standard-autoloader.md) +to attempt to load the class via the [include_path](http://php.net/include_path). +If the class is not found, or does not implement the +[SplAutoloader](spl-autoloader.md) interface, an exception will be raised. + +## Available methods + +### factory + +```php +static factory(array|Traversable $options) : void +``` + +Instantiate and register autoloaders. + +This method is **static**, and is used to instantiate autoloaders and register them +with the SPL autoloader. It expects either an array or `Traversable` object as denoted in the +[options section](#configuration options). + +### getRegisteredAutoloaders + +```php +static getRegisteredAutoloaders() : SplAutoloader[] +``` + +Retrieve a list of all autoloaders registered using the factory. + +This method is **static**, and may be used to retrieve a list of all autoloaders +registered via the `factory()` method. It returns an array of `SplAutoloader` +instances. + +### getRegisteredAutoloader + +```php +static getRegisteredAutoloader($class) : SplAutoloader +``` + +Retrieve an autoloader by class name. + +This method is **static**, and is used to retrieve a specific autoloader by +class name. If the autoloader is not registered, an exception will be thrown. + +### unregisterAutoloaders + +```php +static unregisterAutoloaders() : void +``` + +Unregister all autoloaders registered via the factory. + +This method is **static**, and can be used to unregister all autoloaders that +were registered via the factory. Note that this will **not** unregister +autoloaders that were registered outside of the factory. + +### unregisterAutoloader + +```php +static unregisterAutoloader($class) : bool +``` + +Unregister an autoloader registered via the factory. + +This method is **static**, and can be used to unregister an autoloader that was +registered via the factory. Note that this will **not** unregister autoloaders +that were registered outside of the factory. If the autoloader is registered via +the factory, after unregistering it will return `TRUE`, otherwise `FALSE`. diff --git a/doc/book/class-map-autoloader.md b/doc/book/class-map-autoloader.md new file mode 100644 index 0000000..dceafbc --- /dev/null +++ b/doc/book/class-map-autoloader.md @@ -0,0 +1,168 @@ +# The ClassMapAutoloader + +The `ClassMapAutoloader` is designed with performance in mind. Instead of doing +a filesystem lookup, it checks the class against an in-memory classmap, loading +the file associated with that class on a match. This avoids unnecessary +filesystem operations, and can also ensure the autoloader "plays nice" with +opcode caches and PHP's realpath cache. + +The zend-loader component provides a tool for generating classmaps via +`bin/classmap_generator.php`; read the [tool's documentation](classmap-generator.md) for more details. + +## Quick Start + +The first step is to generate a class map file. You may run this over any +directory containing source code anywhere underneath it. + +```bash +$ php classmap_generator.php Some/Directory/ +``` + +This will create a file named `Some/Directory/autoload_classmap.php`, which is a +PHP file returning an associative array that represents the class map. + +Within your code, you will now instantiate the `ClassMapAutoloader`, and provide +it the location of the map. + +```php +// This example assumes the ClassMapAutoloader is autoloadable. +use Zend\Loader\ClassMapAutoloader; + +$loader = new ClassMapAutoloader(); + +// Register the class map: +$loader->registerAutoloadMap('Some/Directory/autoload_classmap.php'); + +// Register with spl_autoload: +$loader->register(); +``` + +At this point, you may now use any classes referenced in your class map. + +## Configuration Options + +The `ClassMapAutoloader` expects an array of options, where each option is +either a filename referencing a class map, or an associative array of class +name/filename pairs. + +As an example: + +```php +// Configuration defining both a file-based class map, and an array map +$config = [ + __DIR__ . '/library/autoloader_classmap.php', // file-based class map + [ // array class map + 'Application\Bootstrap' => __DIR__ . '/application/Bootstrap.php', + 'Test\Bootstrap' => __DIR__ . '/tests/Bootstrap.php', + ], +]; +``` + +## Available Methods + +### \_\_construct + +```php +__construct(array|Traversable $options = null) : void +``` + +Initialize and configure the object `__construct($options = null)`; `$options` +will be passed to [setOptions()](#setoptions). + +### setOptions + +```php +setOptions(array|Traversable $options) : void +``` + +Configures the state of the autoloader, including registering class maps. +`$options` will be passed to [registerAutoloadMaps()](#registerautoloadmaps). + +### registerAutoloadMap + +```php +registerAutoloadMap(string|array $map) : void +``` + +Registers a class map with the autoloader. `$map` may be either a string +referencing a PHP script that returns a class map, or an array defining a class +map. + +More than one class map may be registered; each will be merged with the +previous, meaning it's possible for a later class map to overwrite entries from +a previously registered map. + +### registerAutoloadMaps + +```php +registerAutoloadMaps(array|Traversable $maps) : void +``` + +Register multiple class maps with the autoloader, iterating over `$maps` and +passing each value to [registerAutoloadMap()](#registerautoloadmap). + +### getAutoloadMap + +```php +getAutoloadMap() : array +``` + +Retrieves the current class map as an associative array. + +### autoload + +```php +autoload(string $class) : false|string +``` + +Attempts to load the class specified. Returns a boolean `false` on failure, or a +string indicating the class loaded on success. + +### register + +```php +register() : void +``` + +Registers the `autoload()` method of the current instance with +`spl_autoload_register()`. + +## Examples + +### Using configuration to seed ClassMapAutoloader + +You can use configuration to seed a `ClassMapAutoloader`; values might come from +a configuration file, a cache, or even a PHP array. The following is an example +of a PHP array that could be used to configure the autoloader: + +```php +// Configuration defining both a file-based class map, and an array map +$config = [ + APPLICATION_PATH . '/../library/autoloader_classmap.php', // file-based class map + [ // array class map + 'Application\Bootstrap' => APPLICATION_PATH . '/Bootstrap.php', + 'Test\Bootstrap' => APPLICATION_PATH . '/../tests/Bootstrap.php', + ], +]; +``` + +Once you have your configuration, you can pass it either to the constructor of +the `ClassMapAutoloader`, to its `setOptions()` method, or to +`registerAutoloadMaps()`. + +```php +use Zend\Loader\ClassMapAutoloader; + +/* The following are all equivalent */ + +// To the constructor: +$loader = new ClassMapAutoloader($config); + +// To setOptions(): +$loader = new ClassMapAutoloader(); +$loader->setOptions($config); + +// To registerAutoloadMaps(): +$loader = new ClassMapAutoloader(); +$loader->registerAutoloadMaps($config); +``` diff --git a/doc/book/classmap-generator.md b/doc/book/classmap-generator.md new file mode 100644 index 0000000..bbaae2c --- /dev/null +++ b/doc/book/classmap-generator.md @@ -0,0 +1,28 @@ +# The Class Map Generator utility: bin/classmap\_generator.php + +The script `bin/classmap_generator.php` can be used to generate class map files for use with the +[ClassMapAutoloader](class-map-autoloader.md). + +Internally, it consumes both the [zend-console getopt functionality](https://zendframework.github.io/zend-console/getopt/intro/) +(for parsing command-line options) and the [zend-file ClassFileLocator](https://zendframework.github.io/zend-file/class-file-locator/) +for recursively finding all PHP class files in a given tree. + +## Quick Start + +You may run the script over any directory containing source code. By default, it +will look in the current directory, and will write the script to +`autoloader_classmap.php` in the directory you specify. + +```bash +$ php classmap_generator.php Some/Directory/ +``` + +## Configuration Options + +Option | Description +------------------ | ----------- +`--help | -h` | Returns the usage message. If any other options are provided, they will be ignored. +`--library | -l` | Expects a single argument, a string specifying the library directory to parse. If this option is not specified, it will assume the current working directory. +`--output | -o` | Where to write the autoload class map file. If not provided, assumes `autoload_classmap.php` in the library directory. +`--append | -a` | Append to autoload file if it exists. +`--overwrite | -w` | If an autoload class map file already exists with the name as specified via the `--output` option, you can overwrite it by specifying this flag. Otherwise, the script will not write the class map and return a warning. diff --git a/doc/book/index.html b/doc/book/index.html new file mode 100644 index 0000000..57dd99e --- /dev/null +++ b/doc/book/index.html @@ -0,0 +1,10 @@ +
+
+

zend-loader

+ +

Autoloading and plugin loading strategies.

+ + 
$ composer require zendframework/zend-loader
+
+
+ diff --git a/doc/book/index.md b/doc/book/index.md new file mode 120000 index 0000000..fe84005 --- /dev/null +++ b/doc/book/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/doc/book/module-autoloader.md b/doc/book/module-autoloader.md new file mode 100644 index 0000000..d86825a --- /dev/null +++ b/doc/book/module-autoloader.md @@ -0,0 +1,111 @@ +# The ModuleAutoloader + +`Zend\Loader\ModuleAutoloader` is a special implementation of the +[SplAutoloader](spl-autoloader.md) interface, and is consumed by +[zend-modulemanager](https://github.com/zendframework/zend-modulemanager) to +autoload `Module` classes from different locations. + +Apart from being able to autoload modules from directories, the +`ModuleAutoloader` can also autoload modules packaged as [Phar +archives](http://php.net/phar), which allows for packaging your modules in a +single file for easier distribution. Supported archive formats are: `.phar`, +`.phar.gz`, `.phar.bz2`, `.phar.tar`, `.phar.tar.gz`, `.phar.tar.bz2`, +`.phar.zip`, `.tar`, `tar.gz`, `.tar.bz2` and `.zip`. It is, however, +recommended to avoid compressing your packages (be it either gz, bz2 or zip +compression), as it introduces additional CPU overhead to every request. + +## Quickstart + +As the `ModuleAutoloader` is meant to be used with the `ModuleManager`, for +examples of it's usage and how to configure it, please see the +[Module Autoloader Usage](http://framework.zend.com/manual/current/en/modules/zend.module-manager.module-autoloader.html) +documentation. + +## Configuration Options + +The `ModuleAutoloader` expects an array of options, where each option is either +a path to scan for modules, or a key/value pair of explicit module paths. In the +case of explicit module paths, the key is the module's name, and the value is +the path to that module. + +```php +$options = [ + '/path/to/modules', + '/path/to/other/modules', + 'MyModule' => '/explicit/path/mymodule-v1.2' +]; +``` + +## Available Methods + +### \_\_construct + +```php +__construct(array|Traversable $options = null) : void +``` + +Initialize and configure the object; if `$options` are provided, they will be +passed to [setOptions()](#setoptions). + +### setOptions + +```php +setOptions(array|Traversable $options) : void +``` + +Configures the state of the autoloader, registering paths to modules. `$options` +will be passed to [registerPaths()](#registerpaths). + +### autoload + +```php +autoload(string $class) : false|string +``` + +Attempts to load the specified `Module` class. Returns a boolean `false` on +failure, or a string indicating the class loaded on success. + +### register + +```php +register() : void +``` + +Registers the `autoload()` method of the current instance with +`spl_autoload_register()`. + +### unregister + +```php +unregister() : void +``` + +Unregisters the `autoload()` method of the current instance with +`spl_autoload_unregister()`. + +### registerPaths + +```php +registerPaths(array|Traversable $paths) : void +``` + +Register paths to modules. For an example array, please see the +[Configuration options](#configuration-options) section. + +### registerPath + +```php +registerPath(string $path, string $moduleName = false) : void +``` + +Register a single path with the autoloader. The first parameter, `$path`, is +expected to be a string. The second parameter, `$moduleName`, is expected to be +a module name, which allows for registering an explicit path to that module. + +### getPaths + +```php +getPaths() : string[] +``` + +Returns an array of all the paths registered. diff --git a/doc/book/plugin-class-loader.md b/doc/book/plugin-class-loader.md new file mode 100644 index 0000000..976ffc9 --- /dev/null +++ b/doc/book/plugin-class-loader.md @@ -0,0 +1,295 @@ +# The PluginClassLoader + +Resolving plugin names to class names is a common requirement within +applications. The `PluginClassLoader` implements the interfaces +[PluginClassLocator](plugin-class-locator.md), +[ShortNameLocator](short-name-locator.md), and `IteratorAggregate`, providing a +mechanism for aliasing plugin names to classnames for later retrieval. + +While it can act as a standalone class, it is intended that developers will +extend the class to provide a per-component plugin map. This allows seeding the +map with the most often-used plugins, while simultaneously allowing the end-user +to overwrite existing or register new plugins. + +Additionally, `PluginClassLoader` provides the ability to statically seed all +new instances of a given `PluginClassLoader` or one of its extensions (via Late +Static Binding). If your application will always call for defining or overriding +particular plugin maps on given `PluginClassLoader` extensions, this is a +powerful capability. + +## Quick Start + +Typical use cases involve instantiating a `PluginClassLoader`, seeding it +with one or more plugin/class name associations, and then using it to retrieve +the class name associated with a given plugin name. + +```php +use Zend\Http\HeaderLoader; + +// Provide a global map, or override defaults: +HeaderLoader::addStaticMap([ + 'xrequestedfor' => 'My\Http\Header\XRequestedFor', +]); + +// Instantiate the loader: +$loader = new Zend\Http\HeaderLoader(); + +// Register a new plugin: +$loader->registerPlugin('xForwardedFor', 'My\Http\Header\XForwardedFor'); + +// Load/retrieve the associated plugin class: +$class = $loader->load('xrequestedfor'); // 'My\Http\Header\XRequestedFor' +``` + +> ### Case Sensitivity +> +> The `PluginClassLoader` is designed to do case-insensitive plugin name +> lookups. While the above example defines an "xForwardedFor" plugin name, +> internally, this will be stored as "xforwardedfor". If another plugin is +> registered with the same word but using a different casing structure, it will +> overwrite this entry. + +## Configuration Options + +The constructor may take a single option, an array or `Traversable` object of key/value pairs +corresponding to a plugin name and class name, respectively. + +## Available Methods + +### \_\_construct + +```php +__construct(string|array|Traversable $map = null) : void +``` + +The constructor is used to instantiate and initialize the plugin class loader. +If passed a string, an array, or a `Traversable` object, it will pass this to +the [registerPlugins()](#registerplugins) method in order to seed (or overwrite) +the plugin class map. + +### addStaticMap + +```php +static addStaticMap(array|Traversable $map) : void +``` + +Static method for globally pre-seeding the loader with a class map. It accepts +either an array or `Traversable` object of plugin name/class name pairs. + +When using this method, be certain you understand the precedence in which maps +will be merged; in decreasing order of preference: + +- Manually registered plugin/class name pairs (e.g., via + [registerPlugin()](#registerplugin) or + [registerPlugins()](#registerplugins). +- A map passed to the constructor. +- The static map. +- The map defined within the class itself. + +Also, please note that calling the method will **not** affect any instances +already created. + +### registerPlugin + +```php +registerPlugin(string $shortName, string $className) : void +``` + +Defined by the [PluginClassLocator](plugin-class-locator.md) interface. Expects +two string arguments, the plugin `$shortName`, and the class `$className` which +it represents. + +### registerPlugins + +```php +registerPlugins(string|array|Traversable $map) : void +``` + +If a string argument is provided, `registerPlugins()` assumes this is a class +name. If the class does not exist, an exception will be thrown. If it does, it +then instantiates the class and checks to see whether or not it implements +`Traversable`, iterating it if it does. + +Each key/value pair obtained during iteration is then passed to +[registerPlugin()](#registerPlugin) using the key as the plugin name and the +value as the class name. + +### unregisterPlugin + +```php +unregisterPlugin(string $shortName) : void +``` + +Defined by the `PluginClassLocator` interface; remove a plugin/class association +from the plugin class map. + +### getRegisteredPlugins + +```php +getRegisteredPlugins() : array +``` + +Defined by the `PluginClassLocator` interface; return the entire plugin class +map as an array. + +### isLoaded + +```php +isLoaded(string $name) : bool +``` + +Defined by the `ShortNameLocator` interface; determine if the given plugin has +been resolved to a class name. + +### getClassName + +```php +getClassName(string $name) : string +``` + +Defined by the `ShortNameLocator` interface; return the class name to which a +plugin name resolves. + +### load + +```php +load(string $name) : string|false +``` + +Defined by the `ShortNameLocator` interface; attempt to resolve a plugin name to +a class name. If successful, returns the class name; otherwise, returns a +boolean `false`. + +### getIterator + +```php +getIterator() : Traversable +``` + +Defined by the `IteratorAggregate` interface; allows iteration over the plugin +class map. This can come in useful for using `PluginClassLoader` instances to +other `PluginClassLoader` instances in order to merge maps. + +## Examples + +### Using Static Maps + +It's often convenient to provide global overrides or additions to the maps in a +`PluginClassLoader` instance. This can be done using the `addStaticMap()` +method: + +```php +use Zend\Loader\PluginClassLoader; + +PluginClassLoader::addStaticMap([ + 'xrequestedfor' => 'My\Http\Header\XRequestedFor', +]); +``` + +Any later instances created will now have this map defined, allowing you to load +that plugin. + +```php +use Zend\Loader\PluginClassLoader; + +$loader = new PluginClassLoader(); +$class = $loader->load('xrequestedfor'); // My\Http\Header\XRequestedFor +``` + +### Creating a pre-loaded map + +In many cases, you know exactly which plugins you may be drawing upon on a +regular basis, and which classes they will refer to. In this case, extend +the `PluginClassLoader` and define the map within the extending class. + +```php +namespace My\Plugins; + +use Zend\Loader\PluginClassLoader; + +class PluginLoader extends PluginClassLoader +{ + /** + * @var array Plugin map + */ + protected $plugins = [ + 'foo' => 'My\Plugins\Foo', + 'bar' => 'My\Plugins\Bar', + 'foobar' => 'My\Plugins\FooBar', + ]; +} +``` + +At this point, you can instantiate the map and immediately use it. + +```php +$loader = new My\Plugins\PluginLoader(); +$class = $loader->load('foobar'); // My\Plugins\FooBar +``` + +`PluginClassLoader` makes use of late static binding, allowing per-class static +maps. If you want to allow defining a [static map](#using-static-maps) specific +to this extending class, declare a protected static `$staticMap` property: + +```php +namespace My\Plugins; + +use Zend\Loader\PluginClassLoader; + +class PluginLoader extends PluginClassLoader +{ + protected static $staticMap = []; + + // ... +} +``` + +To inject the static map, call the `addStaticMap()` on the extension class: + +```php +PluginLoader::addStaticMap([ + 'baz' => 'My\Plugins\Baz', +]); +``` + +### Extending a plugin map using another plugin map + +In some cases, a general map class may already exist; as an example, several +Zend Framework components defining plugin brokers have an associated +`PluginClassLoader` extension defining the plugins available for that component +within the framework. What if you want to define some additions to these? Where +should that code go? + +One possibility is to define the map in a configuration file, and then inject +the configuration into an instance of the plugin loader. + +Another solution is to define a new plugin map class. The class name or an +instance of the class may then be passed to the constructor or +`registerPlugins()`. + +```php +namespace My\Plugins; + +use Zend\Loader\PluginClassLoader; +use Zend\Http\HeaderLoader; + +class PluginLoader extends PluginClassLoader +{ + /** + * @var array Plugin map + */ + protected $plugins = [ + 'foo' => 'My\Plugins\Foo', + 'bar' => 'My\Plugins\Bar', + 'foobar' => 'My\Plugins\FooBar', + ]; +} + +// Inject in constructor: +$loader = new HeaderLoader(PluginLoader::class); // as string class name +$loader = new HeaderLoader(new PluginLoader()); // as instance + +// Or via registerPlugins(): +$loader->registerPlugins(PluginLoader::class); // as string class name +$loader->registerPlugins(new PluginLoader()); // as instance +``` diff --git a/doc/book/plugin-class-locator.md b/doc/book/plugin-class-locator.md new file mode 100644 index 0000000..448536c --- /dev/null +++ b/doc/book/plugin-class-locator.md @@ -0,0 +1,54 @@ +# The PluginClassLocator interface + +The `PluginClassLocator` interface describes a component capable of maintaining +an internal map of plugin names to actual class names. Classes implementing this +interface can register and unregister plugin/class associations, and return the +entire map. + +## Quick Start + +Classes implementing the `PluginClassLocator` must implement the following three +methods: + +```php +namespace Zend\Loader; + +interface PluginClassLocator +{ + public function registerPlugin($shortName, $className); + public function unregisterPlugin($shortName); + public function getRegisteredPlugins(); +} +``` + +## Configuration Options + +This component defines no configuration options, as it is an interface. + +## Available Methods + +### registerPlugin + +```php +registerPlugin(string $shortName, string $className) : void +``` + +Implement this method to add or overwrite plugin name/class name associations in +the internal plugin map. `$shortName` will be aliased to `$className`. + +### unregisterPlugin + +```php +unregisterPlugin(string $shortName) : void +``` + +Implement this to allow removing an existing plugin mapping corresponding to +`$shortName`. + +### getRegisteredPlugins + +```php +getRegisteredPlugins() : array +``` + +Implement this to allow returning the plugin name/class name map. diff --git a/doc/book/short-name-locator.md b/doc/book/short-name-locator.md new file mode 100644 index 0000000..d5b3480 --- /dev/null +++ b/doc/book/short-name-locator.md @@ -0,0 +1,67 @@ +# The ShortNameLocator Interface + +We often do not wish to refer to plugins by their fully qualified class name, +but rather via a shorter, more memorable name: an alias. This also makes +providing alternate implementations possible, as developers can register custom +code under an existing alias. + +In the first case, consider the adapter pattern. It's often unwieldy to utilize +a full class name (e.g., `Zend\Cloud\DocumentService\Adapter\SimpleDb`); using +the short name of the adapter, `SimpleDb`, would be much simpler. + +In the second case, consider the case of helpers. Let us assume we have a "url" +helper; you may find that while the shipped helper does 90% of what you need, +you'd like to extend it or provide an alternate implementation. At the same +time, you don't want to change your code to reflect the new helper. In this +case, a short name allows you to alias an alternate class to utilize. + +Classes implementing the `ShortNameLocator` interface provide a mechanism for resolving a short name +to a fully qualified class name; how they do so is left to the implementers, and may combine +strategies defined by other interfaces, such as +[PluginClassLocator](plugin-class-locator.md). + +## Quick Start + +Implementing a `ShortNameLocator` requires defining three methods, as shown below. + +```php +namespace Zend\Loader; + +interface ShortNameLocator +{ + public function isLoaded($name); + public function getClassName($name); + public function load($name); +} +``` + +## Configuration Options + +This component defines no configuration options, as it is an interface. + +## Available Methods + +### isLoaded + +```php +isLoaded(string $name) : bool +``` + +Implement this method to return a boolean indicating whether or not the class +has been able to resolve the plugin name to a class. + +### getClassName + +```php +getClassName(string $name) : string +``` + +Implement this method to return the class name associated with a plugin name. + +### load + +```php +load($name) : string|false +``` + +This method should resolve a plugin name to a class name. diff --git a/doc/book/spl-autoloader.md b/doc/book/spl-autoloader.md new file mode 100644 index 0000000..5735a0a --- /dev/null +++ b/doc/book/spl-autoloader.md @@ -0,0 +1,131 @@ +# The SplAutoloader Interface + +While any valid PHP callback may be registered with `spl_autoload_register()`, +the autoloaders zend-loader provides offer more flexibility by being stateful +and allowing configuration. To provide a common interface for such autoloaders, +zend-loader provides the `SplAutoloader` interface. + +Objects implementing this interface provide a standard mechanism for +configuration, a method that may be invoked to attempt to load a class, and a +method for registering with the SPL autoloading mechanism. + +## Quick Start + +To create your own autoloading mechanism, create a class implementing the +`SplAutoloader` interface (you may review the methods defined in the [methods +section](#available-methods)). As an example, consider the following autoloader, +which will look for a class file named after the class within a list of +registered directories. + +```php +namespace Custom; + +use InvalidArgumentException; +use Traversable; +use Zend\Loader\SplAutoloader; + +class ModifiedIncludePathAutoloader implements SplAutoloader +{ + protected $paths = array(); + + public function __construct($options = null) + { + if (null !== $options) { + $this->setOptions($options); + } + } + + public function setOptions($options) + { + if (! is_array($options) && ! $options instanceof Traversable) { + throw new InvalidArgumentException(); + } + + foreach ($options as $path) { + if (! in_array($path, $this->paths)) { + $this->paths[] = $path; + } + } + } + + public function autoload($classname) + { + $filename = $classname . '.php'; + foreach ($this->paths as $path) { + $test = sprintf('%s/%s', $path, $filename); + if (file_exists($test)) { + return include($test); + } + } + return false; + } + + public function register() + { + spl_autoload_register([$this, 'autoload']); + } +} +``` + +To use this `ModifiedIncludePathAutoloader` from the previous example: + +```php +$options = [ + '/path/one', + '/path/two', +]; +$autoloader = new Custom\ModifiedIncludePathAutoloader($options); +$autoloader->register(); +``` + +## Configuration Options + +This component defines no configuration options, as it is an interface. + +## Available Methods + +### \_\_construct + +```php +__construct($options = null) : void +``` + +Autoloader constructors should optionally receive configuration. Typically, if +received, these will be passed to the `setOptions()` method to process. + +### setOptions + +```php +setOptions(array|Traversable $options) : void +``` + +Used to configure the autoloader. Typically, it should expect either an array or +a `Traversable` object, though validation of the options is left to +implementation. + +### autoload + +```php +autoload(string $class) : false|string +``` + +This method should be used to resolve a class name to the file defining it. When +a positive match is found, return the class name; otherwise, return a boolean +`false`. + +### register + +```php +register() : void +``` + +Should be used to register the autoloader instance with +`spl_autoload_register()`. Invariably, the method should look like the +following: + +```php +public function register() +{ + spl_autoload_register([$this, 'autoload']); +} +``` diff --git a/doc/book/standard-autoloader.md b/doc/book/standard-autoloader.md new file mode 100644 index 0000000..b28eeda --- /dev/null +++ b/doc/book/standard-autoloader.md @@ -0,0 +1,244 @@ +# The StandardAutoloader + +## Overview + +`Zend\Loader\StandardAutoloader` is designed as a +[PSR-0](http://www.php-fig.org/psr/psr-0/)-compliant +autoloader. It assumes a 1:1 mapping of the namespace+classname to the +filesystem, wherein namespace separators and underscores are translated to +directory separators. The following statement illustrates how resolution works: + +```php +$filename = str_replace( + ['_', '\\'], + DIRECTORY_SEPARATOR, + $classname +) . '.php'; +``` + +The `StandardAutoloader` requires that you explicitly register namespace/path +pairs (or vendor prefix/path pairs), and will only load a file if it exists +within the given path. Multiple pairs may be provided. + +As a measure of last resort, you may also use the `StandardAutoloader` as a +"fallback" autoloader — one that will look for classes of any namespace or +vendor prefix on the `include_path`. This practice is not recommended, however, +due to performance implications. + +Finally, as with all autoloaders in zend-loader, the `StandardAutoloader` is +capable of registering itself with PHP's SPL autoloader registry. + +> ### Vocabulary: Namespaces vs. Vendor Prefixes +> +> In terms of autoloading, a "namespace" corresponds to PHP's own definition of +> namespaces. +> +> A "vendor prefix" refers to the practice, popularized in PHP versions prior to +> 5.3, of providing a pseudo-namespace in the form of underscore-separated words +> in class names. As an example, the class `Phly_Couch_Document` uses a vendor +> prefix of `Phly`, and a component prefix of `Phly_Couch`, but it is a class +> sitting in the global namespace. +> +> The `StandardAutoloader` is capable of loading either namespaced or vendor +> prefixed class names, but treats them separately when attempting to match them +> to an appropriate path. + +## Quick Start + +Basic use of the `StandardAutoloader` requires registering namespace/path pairs. +This can either be done at instantiation, or via explicit method calls after the +object has been initialized. Calling `register()` will register the autoloader +with the SPL autoloader registry. + +### Manual Configuration + +```php +use Zend\Loader\StandardAutoloader; + +// This example assumes the StandardAutoloader is autoloadable. +$loader = new StandardAutoloader(); + +// Register the "Phly" namespace: +$loader->registerNamespace('Phly', APPLICATION_PATH . '/../library/Phly'); + +// Register the "Scapi" vendor prefix: +$loader->registerPrefix('Scapi', APPLICATION_PATH . '/../library/Scapi'); + +// Optionally, specify the autoloader as a "fallback" autoloader; +// this is not recommended. +$loader->setFallbackAutoloader(true); + +// Register with spl_autoload: +$loader->register(); +``` + +### Configuration at Instantiation + +The `StandardAutoloader` may also be configured at instantiation. Please note: + +- The argument passed may be either an array or a `Traversable` object. +- The argument passed should also be a valid argument for passing to the + `setOptions()` method. + +The following is equivalent to the previous example. + +```php +use Zend\Loader\StandardAutoloader; + +$loader = new StandardAutoloader([ + 'namespaces' => [ + 'Phly' => APPLICATION_PATH . '/../library/Phly', + ], + 'prefixes' => [ + 'Scapi' => APPLICATION_PATH . '/../library/Scapi', + ], + 'fallback_autoloader' => true, +]); + +// Register with spl_autoload: +$loader->register(); +``` + +## Configuration Options + +The `StandardAutoloader` defines the following options. + +### namespaces + +An associative array of namespace/path pairs. The path should be an absolute +path or path relative to the calling script, and contain only classes that live +in that namespace (or its subnamespaces). + +### prefixes + +An associative array of vendor prefix/path pairs. The path should be an absolute +path or path relative to the calling script, and contain only classes that begin +with the provided vendor prefix. + +### fallback_autoloader + +A boolean value indicating whether or not this instance should act as a +"fallback" autoloader (i.e., look for classes of any namespace or vendor prefix +on the `include_path`). By default, `false`. + +> ### autoregister_zf is deprecated +> +> One other option is available to the `StandardAutoloader`: `autoregister_zf`. +> We do not document it any longer, as it is no longer relevant. +> +> Starting with the 2.5.0 release of Zend Framework, the framework package +> itself is a "metapackage", defining only a `composer.json` file listing +> the packages for each component. +> +> As such, there is no single path in which all ZF files live, making the +> `autoregister_zf` flag useless for versions starting with 2.5.0; it will +> only register the zend-loader path! +> +> If you are using this feature, you should update your code. We recommend +> using [Composer](https://getcomposer.org)'s autoloader for autoloading +> Zend Framework classes. + +## Available Methods + +### \_\_construct + +```php +__construct(array|Traversable $options = null) : void +``` + +Create a new instance of the object. + +If `$options` is non-null, the argument is passed to +[setOptions()](#setoptions). + +### setOptions + +```php +setOptions(array|Traversable $options) : void +``` + +Set object state based on provided options. + +Recognized keys are detailed under [Configuration options](#configuration-options), +with the following behaviors: + +- The `namespaces` value will be passed to + [registerNamespaces()](#registernamespaces). +- The `prefixes` value will be passed to + [registerPrefixes()](#registerprefixes). +- The `fallback_autoloader` value will be passed to + [setFallbackAutoloader()](#setfallbackautoloader). + +### setFallbackAutoloader + +```php +setFallbackAutoloader(bool $flag) : void +``` + +Takes a boolean flag indicating whether or not to act as a fallback autoloader +when registered with the SPL autoloader. + +### isFallbackAutoloader + +```php +isFallbackAutoloader() : bool +``` + +Indicates whether or not this instance is flagged as a fallback autoloader. + +### registerNamespace + +```php +registerNamespace(string $namespace, string $directory) : void +``` + +Register a namespace with the autoloader, pointing it to a specific directory on +the filesystem for class resolution. For classes matching that initial +namespace, the autoloader will then perform lookups within that directory. + +### registerNamespaces + +```php +registerNamespaces(array|Traversable $namespaces) : void +``` + +Register multiple namespaces with the autoloader, iterating through +`$namespaces` and passing each key and item to [registerNamespace()](#registernamespace). + +### registerPrefix + +```php +registerPrefix(string $prefix, string $directory) : void +``` + +Register a vendor prefix with the autoloader, pointing it to a specific +directory on the filesystem for class resolution. For classes matching that +initial vendor prefix, the autoloader will then perform lookups within that +directory. + +### registerPrefixes + +```php +registerPrefixes(array|Traversable $prefixes) : void +``` + +Register many vendor prefixes with the autoloader, traversing `$prefixes` and +passing each key/value pair to [registerPrefix()](#registerprefix). + +### autoload + +```php +autoload(string $class) : false|string +``` + +Attempts to load the class specified. Returns a boolean `false` on failure, or a +string indicating the class loaded on success. + +### register + +```php +register() : void +``` + +Registers the `autoload()` method of the current instance with +`spl_autoload_register()`. diff --git a/doc/book/zend.loader.autoloader-factory.md b/doc/book/zend.loader.autoloader-factory.md deleted file mode 100644 index 9809c4a..0000000 --- a/doc/book/zend.loader.autoloader-factory.md +++ /dev/null @@ -1,117 +0,0 @@ -# The AutoloaderFactory - -## Overview - -Starting with version 2.0, Zend Framework now offers multiple autoloader strategies. Often, it will -be useful to employ multiple autoloading strategies; as an example, you may have a class map for -your most used classes, but want to use a PSR-0 style autoloader for 3rd party libraries. - -While you could potentially manually configure these, it may be more useful to define the autoloader -configuration somewhere and cache it. For these cases, the `AutoloaderFactory` will be useful. - -## Quick Start - -Configuration may be stored as a PHP array, or in some form of configuration file. As an example, -consider the following PHP array: - -```php -$config = array( - 'Zend\Loader\ClassMapAutoloader' => array( - 'application' => APPLICATION_PATH . '/.classmap.php', - 'zf' => APPLICATION_PATH . '/../library/Zend/.classmap.php', - ), - 'Zend\Loader\StandardAutoloader' => array( - 'namespaces' => array( - 'Phly\Mustache' => APPLICATION_PATH . '/../library/Phly/Mustache', - 'Doctrine' => APPLICATION_PATH . '/../library/Doctrine', - ), - ), -); -``` - -An equivalent INI-style configuration might look like the following: - -```php -Zend\Loader\ClassMapAutoloader.application = APPLICATION_PATH "/.classmap.php" -Zend\Loader\ClassMapAutoloader.zf = APPLICATION_PATH "/../library/Zend/.classmap.php" -Zend\Loader\StandardAutoloader.namespaces.Phly\Mustache = APPLICATION_PATH -"/../library/Phly/Mustache" -Zend\Loader\StandardAutoloader.namespaces.Doctrine = APPLICATION_PATH "/../library/Doctrine" -``` - -Once you have your configuration in a PHP array, you simply pass it to the `AutoloaderFactory`. - -```php -// This example assumes ZF is on your include_path. -// You could also load the factory class from a path relative to the -// current script, or via an absolute path. -require_once 'Zend/Loader/AutoloaderFactory.php'; -Zend\Loader\AutoloaderFactory::factory($config); -``` - -The `AutoloaderFactory` will instantiate each autoloader with the given options, and also call its -`register()` method to register it with the SPL autoloader. - -## Configuration Options - -**$options** -The `AutoloaderFactory` expects an associative array or `Traversable` object. Keys should be valid -autoloader class names, and the values should be the options that should be passed to the class -constructor. - -Internally, the `AutoloaderFactory` checks to see if the autoloader class referenced exists. If not, -it will use the \[StandardAutoloader\](zend.loader.standard-autoloader) to attempt to load the class -via the `include_path` (or, in the case of "Zend"-namespaced classes, using the Zend Framework -library path). If the class is not found, or does not implement the -\[SplAutoloader\](zend.loader.spl-autoloader) interface, an exception will be raised. - -## Available Methods - -factory -Instantiate and register autoloaders `factory($options)` - -**factory()** This method is **static**, and is used to instantiate autoloaders and register them -with the SPL autoloader. It expects either an array or `Traversable` object as denoted in the -Options section -<zend.loader.autoloader-factory.options>. - - - -getRegisteredAutoloaders -Retrieve a list of all autoloaders registered using the factory `getRegisteredAutoloaders()` - -**getRegisteredAutoloaders()** This method is **static**, and may be used to retrieve a list of all -autoloaders registered via the `factory()` method. It returns simply an array of autoloader -instances. - - - -getRegisteredAutoloader -Retrieve an autoloader by class name `getRegisteredAutoloader($class)` - -**getRegisteredAutoloader()** This method is **static**, and is used to retrieve a specific -autoloader. It expects a string with the autoloader class name. If the autoloader is not registered, -an exception will be thrown. - - - -unregisterAutoloaders -Unregister all autoloaders registered via the factory. `unregisterAutoloaders()` - -**unregisterAutoloaders()** This method is **static**, and can be used to unregister all autoloaders -that were registered via the factory. Note that this will **not** unregister autoloaders that were -registered outside of the factory. - - - -unregisterAutoloader -Unregister an autoloader registered via the factory. `unregisterAutoloader($class)` - -**unregisterAutoloader()** This method is **static**, and can be used to unregister an autoloader -that was registered via the factory. Note that this will **not** unregister autoloaders that were -registered outside of the factory. If the autoloader is registered via the factory, after -unregistering it will return `TRUE`, otherwise `FALSE`. - -## Examples - -Please see the \[Quick Start\](zend.loader.autoloader-factory.quick-start) for a detailed example. diff --git a/doc/book/zend.loader.class-map-autoloader.md b/doc/book/zend.loader.class-map-autoloader.md deleted file mode 100644 index 68273ae..0000000 --- a/doc/book/zend.loader.class-map-autoloader.md +++ /dev/null @@ -1,173 +0,0 @@ -# The ClassMapAutoloader - -## Overview - -The `ClassMapAutoloader` is designed with performance in mind. The idea behind it is simple: when -asked to load a class, see if it's in the map, and, if so, load the file associated with the class -in the map. This avoids unnecessary filesystem operations, and can also ensure the autoloader "plays -nice" with opcode caches and PHP's realpath cache. - -Zend Framework provides a tool for generating these class maps; you can find it in -`bin/classmap_generator.php` of the distribution. Full documentation of this is provided in the -Class Map -generator <zend.loader.classmap-generator> section. - -## Quick Start - -The first step is to generate a class map file. You may run this over any directory containing -source code anywhere underneath it. - -```php -php classmap_generator.php Some/Directory/ -``` - -This will create a file named `Some/Directory/autoload_classmap.php`, which is a PHP file returning -an associative array that represents the class map. - -Within your code, you will now instantiate the `ClassMapAutoloader`, and provide it the location of -the map. - -```php -// This example assumes ZF is on your include_path. -// You could also load the autoloader class from a path relative to the -// current script, or via an absolute path. -require_once 'Zend/Loader/ClassMapAutoloader.php'; -$loader = new Zend\Loader\ClassMapAutoloader(); - -// Register the class map: -$loader->registerAutoloadMap('Some/Directory/autoload_classmap.php'); - -// Register with spl_autoload: -$loader->register(); -``` - -At this point, you may now use any classes referenced in your class map. - -## Configuration Options - -The `ClassMapAutoloader` defines the following options. - -**$options** -The `ClassMapAutoloader` expects an array of options, where each option is either a filename -referencing a class map, or an associative array of class name/filename pairs. - -As an example: - -```php -// Configuration defining both a file-based class map, and an array map -$config = array( - __DIR__ . '/library/autoloader_classmap.php', // file-based class map - array( // array class map - 'Application\Bootstrap' => __DIR__ . '/application/Bootstrap.php', - 'Test\Bootstrap' => __DIR__ . '/tests/Bootstrap.php', - ), -); -``` - -## Available Methods - -\_\_construct -Initialize and configure the object `__construct($options = null)` - -**Constructor** Used during instantiation of the object. Optionally, pass options, which may be -either an array or `Traversable` object; this argument will be passed to setOptions() -<zend.loader.class-map-autoloader.methods.set-options>. - - - -setOptions -Configure the autoloader `setOptions($options)` - -**setOptions()** Configures the state of the autoloader, including registering class maps. Expects -an array or `Traversable` object; the argument will be passed to registerAutoloadMaps() -<zend.loader.class-map-autoloader.methods.register-autoload-maps>. - - - -registerAutoloadMap -Register a class map `registerAutoloadMap($map)` - -**registerAutoloadMap()** Registers a class map with the autoloader. `$map` may be either a string -referencing a PHP script that returns a class map, or an array defining a class map. - -More than one class map may be registered; each will be merged with the previous, meaning it's -possible for a later class map to overwrite entries from a previously registered map. - - - -registerAutoloadMaps -Register multiple class maps at once `registerAutoloadMaps($maps)` - -**registerAutoloadMaps()** Register multiple class maps with the autoloader. Expects either an array -or `Traversable` object; it then iterates over the argument and passes each value to -registerAutoloadMap() -<zend.loader.class-map-autoloader.methods.register-autoload-map>. - - - -getAutoloadMap -Retrieve the current class map `getAutoloadMap()` - -**getAutoloadMap()** Retrieves the state of the current class map; the return value is simply an -array. - - - -autoload -Attempt to load a class. `autoload($class)` - -**autoload()** Attempts to load the class specified. Returns a boolean `false` on failure, or a -string indicating the class loaded on success. - - - -register -Register with spl\_autoload. `register()` - -**register()** Registers the `autoload()` method of the current instance with -`spl_autoload_register()`. - -## Examples - -### Using configuration to seed ClassMapAutoloader - -Often, you will want to configure your `ClassMapAutoloader`. These values may come from a -configuration file, a cache (such as ShMem or memcached), or a simple PHP array. The following is an -example of a PHP array that could be used to configure the autoloader: - -```php -// Configuration defining both a file-based class map, and an array map -$config = array( - APPLICATION_PATH . '/../library/autoloader_classmap.php', // file-based class map - array( // array class map - 'Application\Bootstrap' => APPLICATION_PATH . '/Bootstrap.php', - 'Test\Bootstrap' => APPLICATION_PATH . '/../tests/Bootstrap.php', - ), -); -``` - -An equivalent INI style configuration might look like this: - -```php -classmap.library = APPLICATION_PATH "/../library/autoloader_classmap.php" -classmap.resources.Application\Bootstrap = APPLICATION_PATH "/Bootstrap.php" -classmap.resources.Test\Bootstrap = APPLICATION_PATH "/../tests/Bootstrap.php" -``` - -Once you have your configuration, you can pass it either to the constructor of the -`ClassMapAutoloader`, to its `setOptions()` method, or to `registerAutoloadMaps()`. - -```php -/* The following are all equivalent */ - -// To the constructor: -$loader = new Zend\Loader\ClassMapAutoloader($config); - -// To setOptions(): -$loader = new Zend\Loader\ClassMapAutoloader(); -$loader->setOptions($config); - -// To registerAutoloadMaps(): -$loader = new Zend\Loader\ClassMapAutoloader(); -$loader->registerAutoloadMaps($config); -``` diff --git a/doc/book/zend.loader.classmap-generator.md b/doc/book/zend.loader.classmap-generator.md deleted file mode 100644 index 0246b8d..0000000 --- a/doc/book/zend.loader.classmap-generator.md +++ /dev/null @@ -1,43 +0,0 @@ -# The Class Map Generator utility: bin/classmap\_generator.php - -## Overview - -The script `bin/classmap_generator.php` can be used to generate class map files for use with the -ClassMapAutoloader <zend.loader.class-map-autoloader>. - -Internally, it consumes both \[Zend\\Console\\Getopt\](zend.console.getopt.introduction) (for -parsing command-line options) and \[Zend\\File\\ClassFileLocator\](zend.file.class-file-locator) for -recursively finding all PHP class files in a given tree. - -## Quick Start - -You may run the script over any directory containing source code. By default, it will look in the -current directory, and will write the script to `autoloader_classmap.php` in the directory you -specify. - -```php -php classmap_generator.php Some/Directory/ -``` - -## Configuration Options - -**--help or -h** -Returns the usage message. If any other options are provided, they will be ignored. - -**--library or -l** -Expects a single argument, a string specifying the library directory to parse. If this option is not -specified, it will assume the current working directory. - -**--output or -o** -Where to write the autoload class map file. If not provided, assumes "autoload\_classmap.php" in the -library directory. - -**--append or -a** -Append to autoload file if it exists. - -**--overwrite or -w** -If an autoload class map file already exists with the name as specified via the `--output` option, -you can overwrite it by specifying this flag. Otherwise, the script will not write the class map and -return a warning. - - diff --git a/doc/book/zend.loader.module-autoloader.md b/doc/book/zend.loader.module-autoloader.md deleted file mode 100644 index e8a8731..0000000 --- a/doc/book/zend.loader.module-autoloader.md +++ /dev/null @@ -1,111 +0,0 @@ -# The ModuleAutoloader - -## Overview - -`Zend\Loader\ModuleAutoloader` is a special implementation of the Zend\\\\Loader\\\\SplAutoloader -<zend.loader.spl-autoloader> interface, used by -\[Zend\\ModuleManager\](zend.module-manager.intro) to autoload `Module` classes from different -sources. - -Apart from being able to autoload modules from directories, the `ModuleAutoloader` can also autoload -modules packaged as [Phar archives](http://php.net/phar), which allows for packaging your modules in -a single file for easier distribution. Supported archive formats are: `.phar`, `.phar.gz`, -`.phar.bz2`, `.phar.tar`, `.phar.tar.gz`, `.phar.tar.bz2`, `.phar.zip`, `.tar`, `tar.gz`, `.tar.bz2` -and `.zip`. It is, however, recommended to avoid compressing your packages (be it either gz, bz2 or -zip compression), as it introduces additional CPU overhead to every request. - -## Quickstart - -As the `ModuleAutoloader` is meant to be used with the `ModuleManager`, for examples of it's usage -and how to configure it, please see the Module Autoloader Usage -<zend.module-manager.module-autoloader.usage> section of the `ModuleManager` documentation. - -## Configuration Options - -The `ModuleAutoloader` defines the following options. - -**$options** -The `ModuleAutoloader` expects an array of options, where each option is either a path to scan for -modules, or a key/value pair of explicit module paths. In the case of explicit module paths, the key -is the module's name, and the value is the path to that module. - -```php -$options = array( - '/path/to/modules', - '/path/to/other/modules', - 'MyModule' => '/explicit/path/mymodule-v1.2' -); -``` - -## Available Methods - -\_\_construct -Initialize and configure the object `__construct($options = null)` - -**Constructor** Used during instantiation of the object. Optionally, pass options, which may be -either an array or `Traversable` object; this argument will be passed to setOptions() -<zend.loader.module-autoloader.methods.set-options>. - - - -setOptions -Configure the module autoloader `setOptions($options)` - -**setOptions()** Configures the state of the autoloader, registering paths to modules. Expects an -array or `Traversable` object; the argument will be passed to registerPaths() -<zend.loader.module-autoloader.methods.register-paths>. - - - -autoload -Attempt to load a `Module` class. `autoload($class)` - -**autoload()** Attempts to load the specified `Module` class. Returns a boolean `false` on failure, -or a string indicating the class loaded on success. - - - -register -Register with spl\_autoload. `register()` - -**register()** Registers the `autoload()` method of the current instance with -`spl_autoload_register()`. - - - -unregister -Unregister with spl\_autoload. `unregister()` - -**unregister()** Unregisters the `autoload()` method of the current instance with -`spl_autoload_unregister()`. - - - -registerPaths -Register multiple paths with the autoloader. `registerPaths($paths)` - -**registerPaths()** Register a paths to modules. Expects an array or `Traversable` object. For an -example array, please see the \[Configuration options\](zend.loader.module-autoloader.options) -section. - - - -registerPath -Register a single path with the autoloader. `registerPath($path, $moduleName=false)` - -**registerPath()** Register a single path with the autoloader. The first parameter, `$path`, is -expected to be a string. The second parameter, `$moduleName`, is expected to be a module name, which -allows for registering an explicit path to that module. - - - -getPaths -Get all paths registered with the autoloader. `getPaths()` - -**getPaths()** Returns an array of all the paths registered with the current instance of the -autoloader. - -## Examples - -Please review the \[examples in the quick start\](zend.loader.module-autoloader.quickstart) for -usage. diff --git a/doc/book/zend.loader.plugin-class-loader.md b/doc/book/zend.loader.plugin-class-loader.md deleted file mode 100644 index 211757e..0000000 --- a/doc/book/zend.loader.plugin-class-loader.md +++ /dev/null @@ -1,276 +0,0 @@ -# The PluginClassLoader - -## Overview - -Resolving plugin names to class names is a common requirement within Zend Framework applications. -The `PluginClassLoader` implements the interfaces -\[PluginClassLocator\](zend.loader.plugin-class-locator), -\[ShortNameLocator\](zend.loader.short-name-locator), and `IteratorAggregate`, providing a simple -mechanism for aliasing plugin names to classnames for later retrieval. - -While it can act as a standalone class, it is intended that developers will extend the class to -provide a per-component plugin map. This allows seeding the map with the most often-used plugins, -while simultaneously allowing the end-user to overwrite existing or register new plugins. - -Additionally, `PluginClassLoader` provides the ability to statically seed all new instances of a -given `PluginClassLoader` or one of its extensions (via Late Static Binding). If your application -will always call for defining or overriding particular plugin maps on given `PluginClassLoader` -extensions, this is a powerful capability. - -## Quick Start - -Typical use cases involve simply instantiating a `PluginClassLoader`, seeding it with one or more -plugin/class name associations, and then using it to retrieve the class name associated with a given -plugin name. - -```php -use Zend\Http\HeaderLoader; - -// Provide a global map, or override defaults: -HeaderLoader::addStaticMap(array( - 'xrequestedfor' => 'My\Http\Header\XRequestedFor', -)); - -// Instantiate the loader: -$loader = new Zend\Http\HeaderLoader(); - -// Register a new plugin: -$loader->registerPlugin('xForwardedFor', 'My\Http\Header\XForwardedFor'); - -// Load/retrieve the associated plugin class: -$class = $loader->load('xrequestedfor'); // 'My\Http\Header\XRequestedFor' -``` - -> ## Note -#### Case Sensitivity -The `PluginClassLoader` is designed to do case-insensitive plugin name lookups. While the above -example defines a "xForwardedFor" plugin name, internally, this will be stored as simply -"xforwardedfor". If another plugin is registered with simply a different word case, it will -overwrite this entry. - -## Configuration Options - -**$map** -The constructor may take a single option, an array or `Traversable` object of key/value pairs -corresponding to a plugin name and class name, respectively. - -## Available Methods - -\_\_construct -Instantiate and initialize the loader `__construct($map = null)` - -**\_\_construct()** The constructor is used to instantiate and initialize the plugin class loader. -If passed a string, an array, or a `Traversable` object, it will pass this to the registerPlugins() -<zend.loader.plugin-class-loader.methods.register-plugins> method in order to seed (or -overwrite) the plugin class map. - - - -addStaticMap -Statically seed the plugin loader map `addStaticMap($map)` - -**addStaticMap()** Static method for globally pre-seeding the loader with a class map. It accepts -either an array or `Traversable` object of plugin name/class name pairs. - -When using this method, be certain you understand the precedence in which maps will be merged; in -decreasing order of preference: - -- Manually registered plugin/class name pairs (e.g., via registerPlugin() - <zend.loader.plugin-class-loader.methods.register-plugin> or registerPlugins() - <zend.loader.plugin-class-loader.methods.register-plugins>). -- A map passed to the constructor . -- The static map. -- The map defined within the class itself. - -Also, please note that calling the method will **not** affect any instances already created. - - - -registerPlugin -Register a plugin/class association `registerPlugin($shortName, $className)` - -**registerPlugin()** Defined by the \[PluginClassLocator\](zend.loader.plugin-class-locator) -interface. Expects two string arguments, the plugin `$shortName`, and the class `$className` which -it represents. - - - -registerPlugins -Register many plugin/class associations at once `registerPlugins($map)` - -**registerPlugins()** Expects a string, an array or `Traversable` object of plugin name/class name -pairs representing a plugin class map. - -If a string argument is provided, `registerPlugins()` assumes this is a class name. If the class -does not exist, an exception will be thrown. If it does, it then instantiates the class and checks -to see whether or not it implements `Traversable`. - - - -unregisterPlugin -Remove a plugin/class association from the map `unregisterPlugin($shortName)` - -**unregisterPlugin()** Defined by the `PluginClassLocator` interface; remove a plugin/class -association from the plugin class map. - - - -getRegisteredPlugins -Return the complete plugin class map `getRegisteredPlugins()` - -**getRegisteredPlugins()** Defined by the `PluginClassLocator` interface; return the entire plugin -class map as an array. - - - -isLoaded -Determine if a given plugin name resolves `isLoaded($name)` - -**isLoaded()** Defined by the `ShortNameLocator` interface; determine if the given plugin has been -resolved to a class name. - - - -getClassName -Return the class name to which a plugin resolves `getClassName($name)` - -**getClassName()** Defined by the `ShortNameLocator` interface; return the class name to which a -plugin name resolves. - - - -load -Resolve a plugin name `load($name)` - -**load()** Defined by the `ShortNameLocator` interface; attempt to resolve a plugin name to a class -name. If successful, returns the class name; otherwise, returns a boolean `false`. - - - -getIterator -Return iterator capable of looping over plugin class map `getIterator()` - -**getIterator()** Defined by the `IteratorAggregate` interface; allows iteration over the plugin -class map. This can come in useful for using `PluginClassLoader` instances to other -`PluginClassLoader` instances in order to merge maps. - -## Examples - -### Using Static Maps - -It's often convenient to provide global overrides or additions to the maps in a `PluginClassLoader` -instance. This can be done using the `addStaticMap()` method: - -```php -use Zend\Loader\PluginClassLoader; - -PluginClassLoader::addStaticMap(array( - 'xrequestedfor' => 'My\Http\Header\XRequestedFor', -)); -``` - -Any later instances created will now have this map defined, allowing you to load that plugin. - -```php -use Zend\Loader\PluginClassLoader; - -$loader = new PluginClassLoader(); -$class = $loader->load('xrequestedfor'); // My\Http\Header\XRequestedFor -``` - -### Creating a pre-loaded map - -In many cases, you know exactly which plugins you may be drawing upon on a regular basis, and which -classes they will refer to. In this case, simply extend the `PluginClassLoader` and define the map -within the extending class. - -```php -namespace My\Plugins; - -use Zend\Loader\PluginClassLoader; - -class PluginLoader extends PluginClassLoader -{ - /** - * @var array Plugin map - */ - protected $plugins = array( - 'foo' => 'My\Plugins\Foo', - 'bar' => 'My\Plugins\Bar', - 'foobar' => 'My\Plugins\FooBar', - ); -} -``` - -At this point, you can simply instantiate the map and use it. - -```php -$loader = new My\Plugins\PluginLoader(); -$class = $loader->load('foobar'); // My\Plugins\FooBar -``` - -`PluginClassLoader` makes use of late static binding, allowing per-class static maps. If you want to -allow defining a \[static map\](zend.loader.plugin-class-loader.examples.static-maps) specific to -this extending class, simply declare a protected static `$staticMap` property: - -```php -namespace My\Plugins; - -use Zend\Loader\PluginClassLoader; - -class PluginLoader extends PluginClassLoader -{ - protected static $staticMap = array(); - - // ... -} -``` - -To inject the static map, use the extending class' name to call the static `addStaticMap()` method. - -```php -PluginLoader::addStaticMap(array( - 'baz' => 'My\Plugins\Baz', -)); -``` - -### Extending a plugin map using another plugin map - -In some cases, a general map class may already exist; as an example, most components in Zend -Framework that utilize a plugin broker have an associated `PluginClassLoader` extension defining the -plugins available for that component within the framework. What if you want to define some additions -to these? Where should that code go? - -One possibility is to define the map in a configuration file, and then inject the configuration into -an instance of the plugin loader. This is certainly trivial to implement, but removes the code -defining the plugin map from the library. - -An alternate solution is to define a new plugin map class. The class name or an instance of the -class may then be passed to the constructor or `registerPlugins()`. - -```php -namespace My\Plugins; - -use Zend\Loader\PluginClassLoader; -use Zend\Http\HeaderLoader; - -class PluginLoader extends PluginClassLoader -{ - /** - * @var array Plugin map - */ - protected $plugins = array( - 'foo' => 'My\Plugins\Foo', - 'bar' => 'My\Plugins\Bar', - 'foobar' => 'My\Plugins\FooBar', - ); -} - -// Inject in constructor: -$loader = new HeaderLoader('My\Plugins\PluginLoader'); -$loader = new HeaderLoader(new PluginLoader()); - -// Or via registerPlugins(): -$loader->registerPlugins('My\Plugins\PluginLoader'); -$loader->registerPlugins(new PluginLoader()); -``` diff --git a/doc/book/zend.loader.plugin-class-locator.md b/doc/book/zend.loader.plugin-class-locator.md deleted file mode 100644 index 7228c67..0000000 --- a/doc/book/zend.loader.plugin-class-locator.md +++ /dev/null @@ -1,55 +0,0 @@ -# The PluginClassLocator interface - -## Overview - -The `PluginClassLocator` interface describes a component capable of maintaining an internal map of -plugin names to actual class names. Classes implementing this interface can register and unregister -plugin/class associations, and return the entire map. - -## Quick Start - -Classes implementing the `PluginClassLocator` need to implement only three methods, as illustrated -below. - -```php -namespace Zend\Loader; - -interface PluginClassLocator -{ - public function registerPlugin($shortName, $className); - public function unregisterPlugin($shortName); - public function getRegisteredPlugins(); -} -``` - -## Configuration Options - -This component defines no configuration options, as it is an interface. - -## Available Methods - -registerPlugin -Register a mapping of plugin name to class name `registerPlugin($shortName, $className)` - -**registerPlugin()** Implement this method to add or overwrite plugin name/class name associations -in the internal plugin map. `$shortName` will be aliased to `$className`. - - - -unregisterPlugin -Remove a plugin/class name association `unregisterPlugin($shortName)` - -**unregisterPlugin()** Implement this to allow removing an existing plugin mapping corresponding to -`$shortName`. - - - -getRegisteredPlugins -Retrieve the map of plugin name/class name associations `getRegisteredPlugins()` - -**getRegisteredPlugins()** Implement this to allow returning the plugin name/class name map. - -## Examples - -Please see the \[Quick Start\](zend.loader.plugin-class-locator.quick-start) for the interface -specification. diff --git a/doc/book/zend.loader.short-name-locator.md b/doc/book/zend.loader.short-name-locator.md deleted file mode 100644 index 21c9e93..0000000 --- a/doc/book/zend.loader.short-name-locator.md +++ /dev/null @@ -1,67 +0,0 @@ -# The ShortNameLocator Interface - -## Overview - -Within Zend Framework applications, it's often expedient to provide a mechanism for using class -aliases instead of full class names to load adapters and plugins, or to allow using aliases for the -purposes of slipstreaming alternate implementations into the framework. - -In the first case, consider the adapter pattern. It's often unwieldy to utilize a full class name -(e.g., `Zend\Cloud\DocumentService\Adapter\SimpleDb`); using the short name of the adapter, -`SimpleDb`, would be much simpler. - -In the second case, consider the case of helpers. Let us assume we have a "url" helper; you may find -that while the shipped helper does 90% of what you need, you'd like to extend it or provide an -alternate implementation. At the same time, you don't want to change your code to reflect the new -helper. In this case, a short name allows you to alias an alternate class to utilize. - -Classes implementing the `ShortNameLocator` interface provide a mechanism for resolving a short name -to a fully qualified class name; how they do so is left to the implementers, and may combine -strategies defined by other interfaces, such as -\[PluginClassLocator\](zend.loader.plugin-class-locator). - -## Quick Start - -Implementing a `ShortNameLocator` is trivial, and requires only three methods, as shown below. - -```php -namespace Zend\Loader; - -interface ShortNameLocator -{ - public function isLoaded($name); - public function getClassName($name); - public function load($name); -} -``` - -## Configuration Options - -This component defines no configuration options, as it is an interface. - -## Available Methods - -isLoaded -Is the requested plugin loaded? `isLoaded($name)` - -**isLoaded()** Implement this method to return a boolean indicating whether or not the class has -been able to resolve the plugin name to a class. - - - -getClassName -Get the class name associated with a plugin name `getClassName($name)` - -**getClassName()** Implement this method to return the class name associated with a plugin name. - - - -load -Resolve a plugin to a class name `load($name)` - -**load()** This method should resolve a plugin name to a class name. - -## Examples - -Please see the \[Quick Start\](zend.loader.short-name-locator.quick-start) for the interface -specification. diff --git a/doc/book/zend.loader.spl-autoloader.md b/doc/book/zend.loader.spl-autoloader.md deleted file mode 100644 index c10d8e8..0000000 --- a/doc/book/zend.loader.spl-autoloader.md +++ /dev/null @@ -1,128 +0,0 @@ -# The SplAutoloader Interface - -## Overview - -While any valid PHP callback may be registered with `spl_autoload_register()`, Zend Framework -autoloaders often provide more flexibility by being stateful and allowing configuration. To provide -a common interface, Zend Framework provides the `SplAutoloader` interface. - -Objects implementing this interface provide a standard mechanism for configuration, a method that -may be invoked to attempt to load a class, and a method for registering with the SPL autoloading -mechanism. - -## Quick Start - -To create your own autoloading mechanism, simply create a class implementing the `SplAutoloader` -interface (you may review the methods defined in the \[Methods -section\](zend.loader.spl-autoloader.methods)). As a simple example, consider the following -autoloader, which will look for a class file named after the class within a list of registered -directories. - -```php -namespace Custom; - -use Zend\Loader\SplAutoloader; - -class ModifiedIncludePathAutoloader implements SplAutoloader -{ - protected $paths = array(); - - public function __construct($options = null) - { - if (null !== $options) { - $this->setOptions($options); - } - } - - public function setOptions($options) - { - if (!is_array($options) && !($options instanceof \Traversable)) { - throw new \InvalidArgumentException(); - } - - foreach ($options as $path) { - if (!in_array($path, $this->paths)) { - $this->paths[] = $path; - } - } - return $this; - } - - public function autoload($classname) - { - $filename = $classname . '.php'; - foreach ($this->paths as $path) { - $test = $path . DIRECTORY_SEPARATOR . $filename; - if (file_exists($test)) { - return include($test); - } - } - return false; - } - - public function register() - { - spl_autoload_register(array($this, 'autoload')); - } -} -``` - -To use this `ModifiedIncludePathAutoloader` from the previous example: - -```php -$options = array( - '/path/one', - '/path/two' -); -$autoloader = new Custom\ModifiedIncludePathAutoloader($options); -$autoloader->register(); -``` - -## Configuration Options - -This component defines no configuration options, as it is an interface. - -## Available Methods - -\_\_construct -Initialize and configure an autoloader `__construct($options = null)` - -**Constructor** Autoloader constructors should optionally receive configuration options. Typically, -if received, these will be passed to the `setOptions()` method to process. - - - -setOptions -Configure the autoloader state `setOptions($options)` - -**setOptions()** Used to configure the autoloader. Typically, it should expect either an array or a -`Traversable` object, though validation of the options is left to implementation. Additionally, it -is recommended that the method return the autoloader instance in order to implement a fluent -interface. - - - -autoload -Attempt to resolve a class name to the file defining it `autoload($classname)` - -**autoload()** This method should be used to resolve a class name to the file defining it. When a -positive match is found, return the class name; otherwise, return a boolean false. - - - -register -Register the autoloader with the SPL autoloader `register()` - -**register()** Should be used to register the autoloader instance with `spl_autoload_register()`. -Invariably, the method should look like the following: - -```php -public function register() -{ - spl_autoload_register(array($this, 'autoload')); -} -``` - -## Examples - -Please see the \[Quick Start\](zend.loader.spl-autoloader.quick-start) for a complete example. diff --git a/doc/book/zend.loader.standard-autoloader.md b/doc/book/zend.loader.standard-autoloader.md deleted file mode 100644 index 626ced2..0000000 --- a/doc/book/zend.loader.standard-autoloader.md +++ /dev/null @@ -1,223 +0,0 @@ -# The StandardAutoloader - -## Overview - -`Zend\Loader\StandardAutoloader` is designed as a -[PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)-compliant -autoloader. It assumes a 1:1 mapping of the namespace+classname to the filesystem, wherein namespace -separators and underscores are translated to directory separators. A simple statement that -illustrates how resolution works is as follows: - -```php -$filename = str_replace(array('_', '\\'), DIRECTORY_SEPARATOR, $classname) - . '.php'; -``` - -Previous incarnations of PSR-0-compliant autoloaders in Zend Framework have relied upon the -`include_path` for file lookups. This has led to a number of issues: - -- Due to the use of `include`, if the file is not found, a warning is raised -- even if another -autoloader is capable of resolving the class later. -- Documenting how to setup the `include_path` has proven to be a difficult concept to convey. -- If multiple Zend Framework installations exist on the `include_path`, the first one on the path -wins -- even if that was not the one the developer intended. - -To solve these problems, the `StandardAutoloader` by default requires that you explicitly register -namespace/path pairs (or vendor prefix/path pairs), and will only load a file if it exists within -the given path. Multiple pairs may be provided. - -As a measure of last resort, you may also use the `StandardAutoloader` as a "fallback" autoloader -- -one that will look for classes of any namespace or vendor prefix on the `include_path`. This -practice is not recommended, however, due to performance implications. - -Finally, as with all autoloaders in Zend Framework, the `StandardAutoloader` is capable of -registering itself with PHP's SPL autoloader registry. - -> ## Note -#### Vocabulary: Namespaces vs. Vendor Prefixes -In terms of autoloading, a "namespace" corresponds to PHP's own definition of namespaces in PHP -versions 5.3 and above. -A "vendor prefix" refers to the practice, popularized in PHP versions prior to 5.3, of providing a -pseudo-namespace in the form of underscore-separated words in class names. As an example, the class -`Phly_Couch_Document` uses a vendor prefix of "Phly", and a component prefix of "Phly\_Couch" -- but -it is a class sitting in the global namespace within PHP 5.3. -The `StandardAutoloader` is capable of loading either namespaced or vendor prefixed class names, but -treats them separately when attempting to match them to an appropriate path. - -## Quick Start - -Basic use of the `StandardAutoloader` requires simply registering namespace/path pairs. This can -either be done at instantiation, or via explicit method calls after the object has been initialized. -Calling `register()` will register the autoloader with the SPL autoloader registry. - -If the option key 'autoregister\_zf' is set to true then the class will register the "Zend" -namespace to the directory above where its own classfile is located on the filesystem. - -### Manual Configuration - -```php -// This example assumes ZF is on your include_path. -// You could also load the autoloader class from a path relative to the -// current script, or via an absolute path. -require_once 'Zend/Loader/StandardAutoloader.php'; -$loader = new Zend\Loader\StandardAutoloader(array('autoregister_zf' => true)); - -// Register the "Phly" namespace: -$loader->registerNamespace('Phly', APPLICATION_PATH . '/../library/Phly'); - -// Register the "Scapi" vendor prefix: -$loader->registerPrefix('Scapi', APPLICATION_PATH . '/../library/Scapi'); - -// Optionally, specify the autoloader as a "fallback" autoloader; -// this is not recommended. -$loader->setFallbackAutoloader(true); - -// Register with spl_autoload: -$loader->register(); -``` - -### Configuration at Instantiation - -The `StandardAutoloader` may also be configured at instantiation. Please note: - -- The argument passed may be either an array or a `Traversable` object. -- The argument passed is also a valid argument for passing to the `setOptions()` method. - -The following is equivalent to the previous example. - -```php -require_once 'Zend/Loader/StandardAutoloader.php'; -$loader = new Zend\Loader\StandardAutoloader(array( - 'autoregister_zf' => true, - 'namespaces' => array( - 'Phly' => APPLICATION_PATH . '/../library/Phly', - ), - 'prefixes' => array( - 'Scapi' => APPLICATION_PATH . '/../library/Scapi', - ), - 'fallback_autoloader' => true, -)); - -// Register with spl_autoload: -$loader->register(); -``` - -## Configuration Options - -The `StandardAutoloader` defines the following options. - -**namespaces** -An associative array of namespace/path pairs. The path should be an absolute path or path relative -to the calling script, and contain only classes that live in that namespace (or its subnamespaces). -By default, the "Zend" namespace is registered, pointing to the parent directory of the file -defining the `StandardAutoloader`. - -**prefixes** -An associative array of vendor prefix/path pairs. The path should be an absolute path or path -relative to the calling script, and contain only classes that begin with the provided vendor prefix. - -**fallback\_autoloader** -A boolean value indicating whether or not this instance should act as a "fallback" autoloader (i.e., -look for classes of any namespace or vendor prefix on the `include_path`). By default, `false`. - -**autoregister\_zf** -An boolean value indicating that the class should register the "Zend" namespace to the directory -above where its own classfile is located on the filesystem. - -## Available Methods - -\_\_construct -Initialize a new instance of the object `__construct($options = null)` - -**Constructor** Takes an optional `$options` argument. This argument may be an associative array or -`Traversable` object. If not null, the argument is passed to -\[setOptions()\](zend.loader.standard-autoloader.methods.set-options). - - - -setOptions -Set object state based on provided options. `setOptions($options)` - -**setOptions()** Takes an argument of either an associative array or `Traversable` object. -Recognized keys are detailed under \[Configuration -options\](zend.loader.standard-autoloader.options), with the following behaviors: - -- The `namespaces` value will be passed to registerNamespaces() - <zend.loader.standard-autoloader.methods.register-namespaces>. -- The `prefixes` value will be passed to registerPrefixes() - <zend.loader.standard-autoloader.methods.register-prefixes>. -- The `fallback_autoloader` value will be passed to setFallbackAutoloader() - <zend.loader.standard-autoloader.methods.set-fallback-autoloader>. - - - -setFallbackAutoloader -Enable/disable fallback autoloader status `setFallbackAutoloader($flag)` - -**setFallbackAutoloader()** Takes a boolean flag indicating whether or not to act as a fallback -autoloader when registered with the SPL autoloader. - - - -isFallbackAutoloader -Query fallback autoloader status `isFallbackAutoloader()` - -**isFallbackAutoloader()** Indicates whether or not this instance is flagged as a fallback -autoloader. - - - -registerNamespace -Register a namespace with the autoloader `registerNamespace($namespace, $directory)` - -**registerNamespace()** Register a namespace with the autoloader, pointing it to a specific -directory on the filesystem for class resolution. For classes matching that initial namespace, the -autoloader will then perform lookups within that directory. - - - -registerNamespaces -Register multiple namespaces with the autoloader `registerNamespaces($namespaces)` - -**registerNamespaces()** Accepts either an array or `Traversable` object. It will then iterate -through the argument, and pass each item to -\[registerNamespace()\](zend.loader.standard-autoloader.methods.register-namespace). - - - -registerPrefix -Register a vendor prefix with the autoloader. `registerPrefix($prefix, $directory)` - -**registerPrefix()** Register a vendor prefix with the autoloader, pointing it to a specific -directory on the filesystem for class resolution. For classes matching that initial vendor prefix, -the autoloader will then perform lookups within that directory. - - - -registerPrefixes -Register many vendor prefixes with the autoloader `registerPrefixes($prefixes)` - -**registerPrefixes()** Accepts either an array or `Traversable` object. It will then iterate through -the argument, and pass each item to -\[registerPrefix()\](zend.loader.standard-autoloader.methods.register-prefix). - - - -autoload -Attempt to load a class. `autoload($class)` - -**autoload()** Attempts to load the class specified. Returns a boolean `false` on failure, or a -string indicating the class loaded on success. - - - -register -Register with spl\_autoload. `register()` - -**register()** Registers the `autoload()` method of the current instance with -`spl_autoload_register()`. - -## Examples - -Please review the \[examples in the quick start\](zend.loader.standard-autoloader.quick-start) for -usage. diff --git a/doc/bookdown.json b/doc/bookdown.json deleted file mode 100644 index 2bd5b88..0000000 --- a/doc/bookdown.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "title": "Zend\\Loader", - "target": "html/", - "content": [ - "book/zend.loader.autoloader-factory.md", - "book/zend.loader.standard-autoloader.md", - "book/zend.loader.class-map-autoloader.md", - "book/zend.loader.module-autoloader.md", - "book/zend.loader.spl-autoloader.md", - "book/zend.loader.plugin-class-loader.md", - "book/zend.loader.short-name-locator.md", - "book/zend.loader.plugin-class-locator.md", - "book/zend.loader.classmap-generator.md" - ] -} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6385a0d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,18 @@ +docs_dir: doc/book +site_dir: doc/html +pages: + - index.md + - Reference: + - AutoloaderFactory: autoloader-factory.md + - StandardAutoloader: standard-autoloader.md + - ClassMapAutoloader: class-map-autoloader.md + - ModuleAutoloader: module-autoloader.md + - SplAutoloader: spl-autoloader.md + - PluginClassLoader: plugin-class-loader.md + - ShortNameLocator: short-name-locator.md + - PluginClassLocator: plugin-class-locator.md + - "ClassMap Generator": classmap-generator.md +site_name: zend-loader +site_description: zend-loader +repo_url: 'https://github.com/zendframework/zend-loader' +copyright: 'Copyright (c) 2016 Zend Technologies USA Inc.' From 88c3f56fea158acf07a653ad3d45b513b67f5b3e Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Thu, 5 May 2016 09:54:49 -0500 Subject: [PATCH 2/4] Added documentation build automation --- .gitignore | 4 +++- .travis.yml | 19 ++++++++++++++++++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index a7fc91d..d41a109 100644 --- a/.gitignore +++ b/.gitignore @@ -6,10 +6,12 @@ .*.sw* .*.un~ nbproject +doc/html/ tmp/ +vendor/ +zf-mkdoc-theme/ clover.xml composer.lock coveralls-upload.json phpunit.xml -vendor diff --git a/.travis.yml b/.travis.yml index 73f4c14..e5d5a80 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,12 +4,23 @@ language: php branches: except: - - /^release-.*$/ + - /^release-\d+\.\d+\.\d+.*$/ - /^ghgfk-.*$/ cache: directories: - $HOME/.composer/cache + - vendor + - $HOME/.local + - zf-mkdoc-theme + +env: + global: + - SITE_URL: https://zendframework.github.io/zend-loader + - GH_USER_NAME: "Matthew Weier O'Phinney" + - GH_USER_EMAIL: matthew@weierophinney.net + - GH_REF: github.com/zendframework/zend-loader.git + - secure: "ChmsX2Olq+bR36Fqtm9xJv3+19hBJr4kG4cgFfZoAzJm9GQS6N4iQNmAkZLBjLN3qskBW6sl4pDXGuyCBMOMPdBnQr1d6OE37NzcIXDrmFmZTNuRi8dWqJDuKDsY/ifcZe3HwsavP+/2y4RzbaxXIyyAcIbVCrI/3RnrMl11XB7TIh/UBRBrxtOad+SvKtpJBidRM41Tp919K3VQscYIAlsmBIWx7gbnc6ZQUbL0p0H0uVbHng9w7RmznGKZDQcoPhXE3/p4ify09WUqK2JKPqoTvQf3E1pF5MNxSNoLjZtrXTs4AmzMfw9Fxxpxx85clUKejfdoiI4kjWsJdUd5E4oNuUf+rnjIyPSg8SmhbQVz9Fiuj2vh16x9uacFgi2QBWfKK4MQpcmWlB+zjMCfP5PMyBWlXswMe3hbFdGvYDhjbxoV3cswjp8JivLh7Gh3C7aFLW5EoJPonsS2FtkJt5IZOofwiauS9lVwbTX7y2r2BBUPAEcW3ffnhaDTiO0cnli47I4ZemKaMrHCtucimMZ3SCuTIIGLU4/tE0obVAetE530TX5Y1mZ4Os23qm5KEO9Yb5Surm2zcNJhAdmTzNjlpYHW9ZI5Q9LnA//lUaTlt6eCq0B4MsswN0ijJUhu+Wrc+gSEMRzMq0bv4I2kbgVwapi0dL0raDdkmvc5dGQ=" matrix: fast_finish: true @@ -20,6 +31,8 @@ matrix: - php: 5.6 env: - EXECUTE_TEST_COVERALLS=true + - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)" + - PATH="$HOME/.local/bin:$PATH" - php: 7 - php: hhvm allow_failures: @@ -42,6 +55,10 @@ script: - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi + - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi + +after_success: + - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi after_script: - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi From 84893b21826ace2b1c213ce5c41d89b2372c00d1 Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Thu, 5 May 2016 09:57:12 -0500 Subject: [PATCH 3/4] Added CHANGELOG for #8 --- CHANGELOG.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b2ef2c0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog + +All notable changes to this project will be documented in this file, in reverse chronological order by release. + +## 2.5.2 - TBD + +### Added + +- [#8](https://github.com/zendframework/zend-loader/pull/8) adds + documentation at https://zendframework.github.io/zend-loader/ + +### Deprecated + +- Nothing. + +### Removed + +- Nothing. + +### Fixed + +- Nothing. From 450876682fcb15c55a8ebfad4b765eaa1ec38b45 Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Thu, 5 May 2016 09:58:30 -0500 Subject: [PATCH 4/4] Updated deps - Use `^5.5 || ^7.0` for PHP version. - Use `^4.8` for PHPUnit version. --- .travis.yml | 1 - composer.json | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.travis.yml b/.travis.yml index e5d5a80..6668f5a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -36,7 +36,6 @@ matrix: - php: 7 - php: hhvm allow_failures: - - php: 7 - php: hhvm notifications: diff --git a/composer.json b/composer.json index 031bfc3..d5720fb 100644 --- a/composer.json +++ b/composer.json @@ -13,7 +13,7 @@ } }, "require": { - "php": ">=5.5" + "php": "^5.5 || ^7.0" }, "minimum-stability": "dev", "prefer-stable": true, @@ -30,6 +30,6 @@ }, "require-dev": { "fabpot/php-cs-fixer": "1.7.*", - "phpunit/PHPUnit": "~4.0" + "phpunit/PHPUnit": "^4.8" } -} \ No newline at end of file +}