• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..28-Mar-2019-

Test/Unit/H28-Mar-2019-1,072817

.StateH A D27-Mar-201910 21

.travis.ymlH A D27-Mar-20191.7 KiB5849

Autoloader.phpH A D27-Mar-20197.5 KiB261109

CHANGELOG.mdH A D27-Mar-20192.8 KiB5239

Consistency.phpH A D27-Mar-20199.5 KiB364213

Exception.phpH A D27-Mar-20191.9 KiB526

Prelude.phpH A D27-Mar-20193.8 KiB10555

README.mdH A D27-Mar-20199.4 KiB276207

Xcallable.phpH A D27-Mar-20198.6 KiB317160

composer.jsonH A D27-Mar-20191.3 KiB4645

README.md

1<p align="center">
2  <img src="https://static.hoa-project.net/Image/Hoa.svg" alt="Hoa" width="250px" />
3</p>
4
5---
6
7<p align="center">
8  <a href="https://travis-ci.org/hoaproject/Consistency"><img src="https://img.shields.io/travis/hoaproject/Consistency/master.svg" alt="Build status" /></a>
9  <a href="https://coveralls.io/github/hoaproject/Consistency?branch=master"><img src="https://img.shields.io/coveralls/hoaproject/Consistency/master.svg" alt="Code coverage" /></a>
10  <a href="https://packagist.org/packages/hoa/consistency"><img src="https://img.shields.io/packagist/dt/hoa/consistency.svg" alt="Packagist" /></a>
11  <a href="https://hoa-project.net/LICENSE"><img src="https://img.shields.io/packagist/l/hoa/consistency.svg" alt="License" /></a>
12</p>
13<p align="center">
14  Hoa is a <strong>modular</strong>, <strong>extensible</strong> and
15  <strong>structured</strong> set of PHP libraries.<br />
16  Moreover, Hoa aims at being a bridge between industrial and research worlds.
17</p>
18
19# Hoa\Consistency
20
21[![Help on IRC](https://img.shields.io/badge/help-%23hoaproject-ff0066.svg)](https://webchat.freenode.net/?channels=#hoaproject)
22[![Help on Gitter](https://img.shields.io/badge/help-gitter-ff0066.svg)](https://gitter.im/hoaproject/central)
23[![Documentation](https://img.shields.io/badge/documentation-hack_book-ff0066.svg)](https://central.hoa-project.net/Documentation/Library/Consistency)
24[![Board](https://img.shields.io/badge/organisation-board-ff0066.svg)](https://waffle.io/hoaproject/consistency)
25
26This library provides a thin layer between PHP VMs and libraries to ensure
27consistency accross VM versions and library versions.
28
29[Learn more](https://central.hoa-project.net/Documentation/Library/Consistency).
30
31## Installation
32
33With [Composer](https://getcomposer.org/), to include this library into
34your dependencies, you need to
35require [`hoa/consistency`](https://packagist.org/packages/hoa/consistency):
36
37```sh
38$ composer require hoa/consistency '~1.0'
39```
40
41For more installation procedures, please read [the Source
42page](https://hoa-project.net/Source.html).
43
44## Testing
45
46Before running the test suites, the development dependencies must be installed:
47
48```sh
49$ composer install
50```
51
52Then, to run all the test suites:
53
54```sh
55$ vendor/bin/hoa test:run
56```
57
58For more information, please read the [contributor
59guide](https://hoa-project.net/Literature/Contributor/Guide.html).
60
61## Quick usage
62
63We propose a quick overview of how the consistency API ensures foreward and
64backward compatibility, also an overview of the [PSR-4
65autoloader](http://www.php-fig.org/psr/psr-4/) and the xcallable API.
66
67### Foreward and backward compatibility
68
69The `Hoa\Consistency\Consistency` class ensures foreward and backward
70compatibility.
71
72#### Example with keywords
73
74The `Hoa\Consistency\Consistency::isKeyword` checks whether a specific word is
75reserved by PHP or not. Let's say your current PHP version does not support the
76`callable` keyword or type declarations such as `int`, `float`, `string` etc.,
77the `isKeyword` method will tell you if they are reserved keywords: Not only
78for your current PHP version, but maybe in an incoming version.
79
80```php
81$isKeyword = Hoa\Consistency\Consistency::isKeyword('yield');
82```
83
84It avoids to write algorithms that might break in the future or for your users
85living on the edge.
86
87#### Example with identifiers
88
89PHP identifiers are defined by a regular expression. It might change in the
90future. To prevent breaking your algorithms, you can use the
91`Hoa\Consistency\Consistency::isIdentifier` method to check an identifier is
92correct regarding current PHP version:
93
94```php
95$isValidIdentifier = Hoa\Consistency\Consistency::isIdentifier('foo');
96```
97
98#### Flexible entities
99
100Flexible entities are very simple. If we declare `Foo\Bar\Bar` as a flexible
101entity, we will be able to access it with the `Foo\Bar\Bar` name or `Foo\Bar`.
102This is very useful if your architecture evolves but you want to keep the
103backward compatibility. For instance, it often happens that you create a
104`Foo\Bar\Exception` class in the `Foo/Bar/Exception.php` file. But after few
105versions, you realise other exceptions need to be introduced, so you need an
106`Exception` directory. In this case, `Foo\Bar\Exception` should move as
107`Foo\Bar\Exception\Exception`. If this latter is declared as a flexible entity,
108backward compatibility will be kept.
109
110```php
111Hoa\Consistency\Consistency::flexEntity('Foo\Bar\Exception\Exception');
112```
113
114Another example is the “entry-class” (informal naming).
115`Hoa\Consistency\Consistency` is a good example. This is more convenient to
116write `Hoa\Consistency` instead of `Hoa\Consistency\Consistency`. This is
117possible because this is a flexible entity.
118
119#### Throwable & co.
120
121The `Throwable` interface has been introduced to represent a whole new exception
122architecture in PHP. Thus, to be compatible with incoming PHP versions, you
123might want to use this interface in some cases. Hopefully, the `Throwable`
124interface will be created for you if it does not exists.
125
126```php
127try {
128129} catch (Throwable $e) {
130131}
132```
133
134### Autoloader
135
136`Hoa\Consistency\Autoloader` is a [PSR-4
137compatible](http://www.php-fig.org/psr/psr-4/) autoloader. It simply works as
138follows:
139  * `addNamespace` is used to map a namespace prefix to a directory,
140  * `register` is used to register the autoloader.
141
142The API also provides the `load` method to force the load of an entity,
143`unregister` to unregister the autoloader, `getRegisteredAutoloaders` to get
144a list of all registered autoloaders etc.
145
146For instance, to map the `Foo\Bar` namespace to the `Source/` directory:
147
148```php
149$autoloader = new Hoa\Consistency\Autoloader();
150$autoloader->addNamespace('Foo\Bar', 'Source');
151$autoloader->register();
152
153$baz = new Foo\Bar\Baz(); // automatically loaded!
154```
155
156### Xcallable
157
158Xcallables are “extended callables”. It is a unified API to invoke callables of
159any kinds, and also extends some Hoa's API (like
160[`Hoa\Event`](https://central.hoa-project.net/Resource/Library/Event)
161or
162[`Hoa\Stream`](https://central.hoa-project.net/Resource/Library/Stream)). It
163understands the following kinds:
164  * `'function'` as a string,
165  * `'class::method'` as a string,
166  * `'class', 'method'` as 2 string arguments,
167  * `$object, 'method'` as 2 arguments,
168  * `$object, ''` as 2 arguments, the “able” is unknown,
169  * `function (…) { … }` as a closure,
170  * `['class', 'method']` as an array of strings,
171  * `[$object, 'method']` as an array.
172
173To use it, simply instanciate the `Hoa\Consistency\Xcallable` class and use it
174as a function:
175
176```php
177$xcallable = new Hoa\Consistency\Xcallable('strtoupper');
178var_dump($xcallable('foo'));
179
180/**
181 * Will output:
182 *     string(3) "FOO"
183 */
184```
185
186The `Hoa\Consistency\Xcallable::distributeArguments` method invokes the callable
187but the arguments are passed as an array:
188
189```php
190$xcallable->distributeArguments(['foo']);
191```
192
193This is also possible to get a unique hash of the callable:
194
195```php
196var_dump($xcallable->getHash());
197
198/**
199 * Will output:
200 *     string(19) "function#strtoupper"
201 */
202```
203
204Finally, this is possible to get a reflection instance of the current callable
205(can be of kind [`ReflectionFunction`](http://php.net/ReflectionFunction),
206[`ReflectionClass`](http://php.net/ReflectionClass),
207[`ReflectionMethod`](http://php.net/ReflectionMethod) or
208[`ReflectionObject`](http://php.net/ReflectionObject)):
209
210```php
211var_dump($xcallable->getReflection());
212
213/**
214 * Will output:
215 *     object(ReflectionFunction)#42 (1) {
216 *       ["name"]=>
217 *       string(10) "strtoupper"
218 *     }
219 */
220```
221
222When the object is set but not the method, the latter will be deduced if
223possible. If the object is of kind
224[`Hoa\Stream`](http://central.hoa-project.net/Resource/Library/Stream), then
225according to the type of the arguments given to the callable, the
226`writeInteger`, `writeString`, `writeArray` etc. method will be used. If the
227argument is of kind `Hoa\Event\Bucket`, then the method name will be deduced
228based on the data contained inside the event bucket. This is very handy. For
229instance, the following example will work seamlessly:
230
231```php
232Hoa\Event\Event::getEvent('hoa://Event/Exception')
233    ->attach(new Hoa\File\Write('Exceptions.log'));
234```
235
236The `attach` method on `Hoa\Event\Event` transforms its argument as an
237xcallable. In this particular case, the method to call is unknown, we only have
238an object (of kind `Hoa\File\Write`). However, because this is a stream, the
239method will be deduced according to the data contained in the event bucket fired
240on the `hoa://Event/Exception` event channel.
241
242## Documentation
243
244The
245[hack book of `Hoa\Consistency`](https://central.hoa-project.net/Documentation/Library/Consistency)
246contains detailed information about how to use this library and how it works.
247
248To generate the documentation locally, execute the following commands:
249
250```sh
251$ composer require --dev hoa/devtools
252$ vendor/bin/hoa devtools:documentation --open
253```
254
255More documentation can be found on the project's website:
256[hoa-project.net](https://hoa-project.net/).
257
258## Getting help
259
260There are mainly two ways to get help:
261
262  * On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject)
263    IRC channel,
264  * On the forum at [users.hoa-project.net](https://users.hoa-project.net).
265
266## Contribution
267
268Do you want to contribute? Thanks! A detailed [contributor
269guide](https://hoa-project.net/Literature/Contributor/Guide.html) explains
270everything you need to know.
271
272## License
273
274Hoa is under the New BSD License (BSD-3-Clause). Please, see
275[`LICENSE`](https://hoa-project.net/LICENSE) for details.
276