Prepare documentation for publication

.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

.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: [email protected]
+    - 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

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/

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`.

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);
+```

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.

doc/book/index.html

@@ -0,0 +1,10 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-loader</h1>
+
+    <p>Autoloading and plugin loading strategies.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-loader</code></pre>
+  </div>
+</div>
+

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md