Skip to content
This repository was archived by the owner on Jan 30, 2020. It is now read-only.

Commit dcacfc3

Browse files
weierophinneyweierophinney
committed
Merge branch 'feature/documentation' into develop
Forward port #8
2 parents dd6c933 + 4508766 commit dcacfc3

27 files changed

+1289
-1217
lines changed

‎.gitignore

+3-1
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@
66
.*.sw*
77
.*.un~
88
nbproject
9+
doc/html/
910
tmp/
11+
vendor/
12+
zf-mkdoc-theme/
1013

1114
clover.xml
1215
composer.lock
1316
coveralls-upload.json
1417
phpunit.xml
15-
vendor

‎.travis.yml

+18-2
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,23 @@ language: php
44

55
branches:
66
except:
7-
- /^release-.*$/
7+
- /^release-\d+\.\d+\.\d+.*$/
88
- /^ghgfk-.*$/
99

1010
cache:
1111
directories:
1212
- $HOME/.composer/cache
13+
- vendor
14+
- $HOME/.local
15+
- zf-mkdoc-theme
16+
17+
env:
18+
global:
19+
- SITE_URL: https://zendframework.github.io/zend-loader
20+
- GH_USER_NAME: "Matthew Weier O'Phinney"
21+
- GH_USER_EMAIL: [email protected]
22+
- GH_REF: github.com/zendframework/zend-loader.git
23+
- secure: "ChmsX2Olq+bR36Fqtm9xJv3+19hBJr4kG4cgFfZoAzJm9GQS6N4iQNmAkZLBjLN3qskBW6sl4pDXGuyCBMOMPdBnQr1d6OE37NzcIXDrmFmZTNuRi8dWqJDuKDsY/ifcZe3HwsavP+/2y4RzbaxXIyyAcIbVCrI/3RnrMl11XB7TIh/UBRBrxtOad+SvKtpJBidRM41Tp919K3VQscYIAlsmBIWx7gbnc6ZQUbL0p0H0uVbHng9w7RmznGKZDQcoPhXE3/p4ify09WUqK2JKPqoTvQf3E1pF5MNxSNoLjZtrXTs4AmzMfw9Fxxpxx85clUKejfdoiI4kjWsJdUd5E4oNuUf+rnjIyPSg8SmhbQVz9Fiuj2vh16x9uacFgi2QBWfKK4MQpcmWlB+zjMCfP5PMyBWlXswMe3hbFdGvYDhjbxoV3cswjp8JivLh7Gh3C7aFLW5EoJPonsS2FtkJt5IZOofwiauS9lVwbTX7y2r2BBUPAEcW3ffnhaDTiO0cnli47I4ZemKaMrHCtucimMZ3SCuTIIGLU4/tE0obVAetE530TX5Y1mZ4Os23qm5KEO9Yb5Surm2zcNJhAdmTzNjlpYHW9ZI5Q9LnA//lUaTlt6eCq0B4MsswN0ijJUhu+Wrc+gSEMRzMq0bv4I2kbgVwapi0dL0raDdkmvc5dGQ="
1324

1425
matrix:
1526
fast_finish: true
@@ -20,10 +31,11 @@ matrix:
2031
- php: 5.6
2132
env:
2233
- EXECUTE_TEST_COVERALLS=true
34+
- DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
35+
- PATH="$HOME/.local/bin:$PATH"
2336
- php: 7
2437
- php: hhvm
2538
allow_failures:
26-
- php: 7
2739
- php: hhvm
2840

2941
notifications:
@@ -42,6 +54,10 @@ script:
4254
- if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi
4355
- if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi
4456
- if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi
57+
- 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
58+
59+
after_success:
60+
- if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
4561

4662
after_script:
4763
- if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi

‎CHANGELOG.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file, in reverse chronological order by release.
4+
5+
## 2.5.2 - TBD
6+
7+
### Added
8+
9+
- [#8](https://github.com/zendframework/zend-loader/pull/8) adds
10+
documentation at https://zendframework.github.io/zend-loader/
11+
12+
### Deprecated
13+
14+
- Nothing.
15+
16+
### Removed
17+
18+
- Nothing.
19+
20+
### Fixed
21+
22+
- Nothing.

‎README.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
[![Build Status](https://secure.travis-ci.org/zendframework/zend-loader.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-loader)
44
[![Coverage Status](https://coveralls.io/repos/zendframework/zend-loader/badge.svg?branch=master)](https://coveralls.io/r/zendframework/zend-loader?branch=master)
55

6-
`Zend\Loader` provides different strategies for autoloading PHP classes.
7-
6+
zend-loader provides different strategies for autoloading PHP classes.
87

98
- File issues at https://github.com/zendframework/zend-loader/issues
10-
- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-loader
9+
- Documentation is at https://zendframework.github.io/zend-loader/

‎composer.json

+3-3
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
}
1414
},
1515
"require": {
16-
"php": ">=5.5"
16+
"php": "^5.5 || ^7.0"
1717
},
1818
"minimum-stability": "dev",
1919
"prefer-stable": true,
@@ -30,6 +30,6 @@
3030
},
3131
"require-dev": {
3232
"fabpot/php-cs-fixer": "1.7.*",
33-
"phpunit/PHPUnit": "~4.0"
33+
"phpunit/PHPUnit": "^4.8"
3434
}
35-
}
35+
}

‎doc/book/autoloader-factory.md

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# The AutoloaderFactory
2+
3+
zend-loader provides multiple autoloader strategies.
4+
`Zend\Loader\AutoloaderFactory` allows you to define configuration for each
5+
strategy you wish to use and register them at once. As an example, you may have
6+
a class map for your most used classes, but want to use a PSR-0 style autoloader
7+
for 3rd party libraries. The factory uses configuration, allowing you to cache
8+
your autoloader definitions or define them centrally for your application.
9+
10+
## Quick Start
11+
12+
The `AutoloaderFactory` expects an array of configuration.
13+
14+
```php
15+
$config = [
16+
'Zend\Loader\ClassMapAutoloader' => [
17+
'application' => APPLICATION_PATH . '/.classmap.php',
18+
'zf' => APPLICATION_PATH . '/../library/Zend/.classmap.php',
19+
],
20+
'Zend\Loader\StandardAutoloader' => [
21+
'namespaces' => [
22+
'Phly\Mustache' => APPLICATION_PATH . '/../library/Phly/Mustache',
23+
'Doctrine' => APPLICATION_PATH . '/../library/Doctrine',
24+
],
25+
],
26+
];
27+
```
28+
29+
Once you have your configuration in a PHP array, pass it to the
30+
`AutoloaderFactory`:
31+
32+
```php
33+
// This example assumes that the AutoloaderFactory is itself autoloadable!
34+
use Zend\Loader\AutoloaderFactory;
35+
36+
AutoloaderFactory::factory($config);
37+
```
38+
39+
The `AutoloaderFactory` will instantiate each autoloader with the given options,
40+
and also call its `register()` method to register it with the SPL autoloader.
41+
42+
## Configuration options
43+
44+
The `AutoloaderFactory` expects an associative array or `Traversable` object.
45+
Keys should be valid autoloader class names, and the values should be the
46+
options that should be passed to the class constructor.
47+
48+
Internally, the `AutoloaderFactory` checks to see if the autoloader class
49+
referenced exists. If not, it will use the [StandardAutoloader](standard-autoloader.md)
50+
to attempt to load the class via the [include_path](http://php.net/include_path).
51+
If the class is not found, or does not implement the
52+
[SplAutoloader](spl-autoloader.md) interface, an exception will be raised.
53+
54+
## Available methods
55+
56+
### factory
57+
58+
```php
59+
static factory(array|Traversable $options) : void
60+
```
61+
62+
Instantiate and register autoloaders.
63+
64+
This method is **static**, and is used to instantiate autoloaders and register them
65+
with the SPL autoloader. It expects either an array or `Traversable` object as denoted in the
66+
[options section](#configuration options).
67+
68+
### getRegisteredAutoloaders
69+
70+
```php
71+
static getRegisteredAutoloaders() : SplAutoloader[]
72+
```
73+
74+
Retrieve a list of all autoloaders registered using the factory.
75+
76+
This method is **static**, and may be used to retrieve a list of all autoloaders
77+
registered via the `factory()` method. It returns an array of `SplAutoloader`
78+
instances.
79+
80+
### getRegisteredAutoloader
81+
82+
```php
83+
static getRegisteredAutoloader($class) : SplAutoloader
84+
```
85+
86+
Retrieve an autoloader by class name.
87+
88+
This method is **static**, and is used to retrieve a specific autoloader by
89+
class name. If the autoloader is not registered, an exception will be thrown.
90+
91+
### unregisterAutoloaders
92+
93+
```php
94+
static unregisterAutoloaders() : void
95+
```
96+
97+
Unregister all autoloaders registered via the factory.
98+
99+
This method is **static**, and can be used to unregister all autoloaders that
100+
were registered via the factory. Note that this will **not** unregister
101+
autoloaders that were registered outside of the factory.
102+
103+
### unregisterAutoloader
104+
105+
```php
106+
static unregisterAutoloader($class) : bool
107+
```
108+
109+
Unregister an autoloader registered via the factory.
110+
111+
This method is **static**, and can be used to unregister an autoloader that was
112+
registered via the factory. Note that this will **not** unregister autoloaders
113+
that were registered outside of the factory. If the autoloader is registered via
114+
the factory, after unregistering it will return `TRUE`, otherwise `FALSE`.

‎doc/book/class-map-autoloader.md

+168
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# The ClassMapAutoloader
2+
3+
The `ClassMapAutoloader` is designed with performance in mind. Instead of doing
4+
a filesystem lookup, it checks the class against an in-memory classmap, loading
5+
the file associated with that class on a match. This avoids unnecessary
6+
filesystem operations, and can also ensure the autoloader "plays nice" with
7+
opcode caches and PHP's realpath cache.
8+
9+
The zend-loader component provides a tool for generating classmaps via
10+
`bin/classmap_generator.php`; read the [tool's documentation](classmap-generator.md) for more details.
11+
12+
## Quick Start
13+
14+
The first step is to generate a class map file. You may run this over any
15+
directory containing source code anywhere underneath it.
16+
17+
```bash
18+
$ php classmap_generator.php Some/Directory/
19+
```
20+
21+
This will create a file named `Some/Directory/autoload_classmap.php`, which is a
22+
PHP file returning an associative array that represents the class map.
23+
24+
Within your code, you will now instantiate the `ClassMapAutoloader`, and provide
25+
it the location of the map.
26+
27+
```php
28+
// This example assumes the ClassMapAutoloader is autoloadable.
29+
use Zend\Loader\ClassMapAutoloader;
30+
31+
$loader = new ClassMapAutoloader();
32+
33+
// Register the class map:
34+
$loader->registerAutoloadMap('Some/Directory/autoload_classmap.php');
35+
36+
// Register with spl_autoload:
37+
$loader->register();
38+
```
39+
40+
At this point, you may now use any classes referenced in your class map.
41+
42+
## Configuration Options
43+
44+
The `ClassMapAutoloader` expects an array of options, where each option is
45+
either a filename referencing a class map, or an associative array of class
46+
name/filename pairs.
47+
48+
As an example:
49+
50+
```php
51+
// Configuration defining both a file-based class map, and an array map
52+
$config = [
53+
__DIR__ . '/library/autoloader_classmap.php', // file-based class map
54+
[ // array class map
55+
'Application\Bootstrap' => __DIR__ . '/application/Bootstrap.php',
56+
'Test\Bootstrap' => __DIR__ . '/tests/Bootstrap.php',
57+
],
58+
];
59+
```
60+
61+
## Available Methods
62+
63+
### \_\_construct
64+
65+
```php
66+
__construct(array|Traversable $options = null) : void
67+
```
68+
69+
Initialize and configure the object `__construct($options = null)`; `$options`
70+
will be passed to [setOptions()](#setoptions).
71+
72+
### setOptions
73+
74+
```php
75+
setOptions(array|Traversable $options) : void
76+
```
77+
78+
Configures the state of the autoloader, including registering class maps.
79+
`$options` will be passed to [registerAutoloadMaps()](#registerautoloadmaps).
80+
81+
### registerAutoloadMap
82+
83+
```php
84+
registerAutoloadMap(string|array $map) : void
85+
```
86+
87+
Registers a class map with the autoloader. `$map` may be either a string
88+
referencing a PHP script that returns a class map, or an array defining a class
89+
map.
90+
91+
More than one class map may be registered; each will be merged with the
92+
previous, meaning it's possible for a later class map to overwrite entries from
93+
a previously registered map.
94+
95+
### registerAutoloadMaps
96+
97+
```php
98+
registerAutoloadMaps(array|Traversable $maps) : void
99+
```
100+
101+
Register multiple class maps with the autoloader, iterating over `$maps` and
102+
passing each value to [registerAutoloadMap()](#registerautoloadmap).
103+
104+
### getAutoloadMap
105+
106+
```php
107+
getAutoloadMap() : array
108+
```
109+
110+
Retrieves the current class map as an associative array.
111+
112+
### autoload
113+
114+
```php
115+
autoload(string $class) : false|string
116+
```
117+
118+
Attempts to load the class specified. Returns a boolean `false` on failure, or a
119+
string indicating the class loaded on success.
120+
121+
### register
122+
123+
```php
124+
register() : void
125+
```
126+
127+
Registers the `autoload()` method of the current instance with
128+
`spl_autoload_register()`.
129+
130+
## Examples
131+
132+
### Using configuration to seed ClassMapAutoloader
133+
134+
You can use configuration to seed a `ClassMapAutoloader`; values might come from
135+
a configuration file, a cache, or even a PHP array. The following is an example
136+
of a PHP array that could be used to configure the autoloader:
137+
138+
```php
139+
// Configuration defining both a file-based class map, and an array map
140+
$config = [
141+
APPLICATION_PATH . '/../library/autoloader_classmap.php', // file-based class map
142+
[ // array class map
143+
'Application\Bootstrap' => APPLICATION_PATH . '/Bootstrap.php',
144+
'Test\Bootstrap' => APPLICATION_PATH . '/../tests/Bootstrap.php',
145+
],
146+
];
147+
```
148+
149+
Once you have your configuration, you can pass it either to the constructor of
150+
the `ClassMapAutoloader`, to its `setOptions()` method, or to
151+
`registerAutoloadMaps()`.
152+
153+
```php
154+
use Zend\Loader\ClassMapAutoloader;
155+
156+
/* The following are all equivalent */
157+
158+
// To the constructor:
159+
$loader = new ClassMapAutoloader($config);
160+
161+
// To setOptions():
162+
$loader = new ClassMapAutoloader();
163+
$loader->setOptions($config);
164+
165+
// To registerAutoloadMaps():
166+
$loader = new ClassMapAutoloader();
167+
$loader->registerAutoloadMaps($config);
168+
```

0 commit comments

Comments
 (0)