Hoa is a modular, extensible and
structured set of PHP libraries.

Moreover, Hoa aims at being a bridge between industrial and research worlds.

Hoa\Consistency

This library provides a thin layer between PHP VMs and libraries to ensure
consistency accross VM versions and library versions.

Learn more.

Installation

With Composer, to include this library into
your dependencies, you need to
require hoa/consistency:

$ composer require hoa/consistency '~2.0'

For more installation procedures, please read the Source
page.

Testing

Before running the test suites, the development dependencies must be installed:

$ composer install

Then, to run all the test suites:

$ vendor/bin/hoa test:run

For more information, please read the contributor
guide.

Quick usage

We propose a quick overview of how the consistency API ensures foreward and
backward compatibility, also an overview of the PSR-4
autoloader and the xcallable API.

Foreward and backward compatibility

The Hoa\Consistency\Consistency class ensures foreward and backward
compatibility.

Example with keywords

The Hoa\Consistency\Consistency::isKeyword checks whether a specific word is
reserved by PHP or not. Let’s say your current PHP version does not support the
callable keyword or type declarations such as int, float, string etc.,
the isKeyword method will tell you if they are reserved keywords: Not only
for your current PHP version, but maybe in an incoming version.

$isKeyword = Hoa\Consistency\Consistency::isKeyword('yield');

It avoids to write algorithms that might break in the future or for your users
living on the edge.

Example with identifiers

PHP identifiers are defined by a regular expression. It might change in the
future. To prevent breaking your algorithms, you can use the
Hoa\Consistency\Consistency::isIdentifier method to check an identifier is
correct regarding current PHP version:

$isValidIdentifier = Hoa\Consistency\Consistency::isIdentifier('foo');

Flexible entities

Flexible entities are very simple. If we declare Foo\Bar\Bar as a flexible
entity, we will be able to access it with the Foo\Bar\Bar name or Foo\Bar.
This is very useful if your architecture evolves but you want to keep the
backward compatibility. For instance, it often happens that you create a
Foo\Bar\Exception class in the Foo/Bar/Exception.php file. But after few
versions, you realise other exceptions need to be introduced, so you need an
Exception directory. In this case, Foo\Bar\Exception should move as
Foo\Bar\Exception\Exception. If this latter is declared as a flexible entity,
backward compatibility will be kept.

Hoa\Consistency\Consistency::flexEntity('Foo\Bar\Exception\Exception');

Another example is the “entry-class” (informal naming).
Hoa\Consistency\Consistency is a good example. This is more convenient to
write Hoa\Consistency instead of Hoa\Consistency\Consistency. This is
possible because this is a flexible entity.

Throwable & co.

The Throwable interface has been introduced to represent a whole new exception
architecture in PHP. Thus, to be compatible with incoming PHP versions, you
might want to use this interface in some cases. Hopefully, the Throwable
interface will be created for you if it does not exists.

try {
    …
} catch (Throwable $e) {
    …
}

Autoloader

Hoa\Consistency\Autoloader is a PSR-4
compatible autoloader. It simply works as
follows:

• addNamespace is used to map a namespace prefix to a directory,
• register is used to register the autoloader.

The API also provides the load method to force the load of an entity,
unregister to unregister the autoloader, getRegisteredAutoloaders to get
a list of all registered autoloaders etc.

For instance, to map the Foo\Bar namespace to the Source/ directory:

$autoloader = new Hoa\Consistency\Autoloader();
$autoloader->addNamespace('Foo\Bar', 'Source');
$autoloader->register();
$baz = new Foo\Bar\Baz(); // automatically loaded!

Xcallable

Xcallables are “extended callables”. It is a unified API to invoke callables of
any kinds, and also extends some Hoa’s API (like
Hoa\Event
or
Hoa\Stream). It
understands the following kinds:

• 'function' as a string,
• 'class::method' as a string,
• 'class', 'method' as 2 string arguments,
• $object, 'method' as 2 arguments,
• $object, '' as 2 arguments, the “able” is unknown,
• function (…) { … } as a closure,
• ['class', 'method'] as an array of strings,
• [$object, 'method'] as an array.

To use it, simply instanciate the Hoa\Consistency\Xcallable class and use it
as a function:

$xcallable = new Hoa\Consistency\Xcallable('strtoupper');
var_dump($xcallable('foo'));
/**
 * Will output:
 *     string(3) "FOO"
 */

The Hoa\Consistency\Xcallable::distributeArguments method invokes the callable
but the arguments are passed as an array:

$xcallable->distributeArguments(['foo']);

This is also possible to get a unique hash of the callable:

var_dump($xcallable->getHash());
/**
 * Will output:
 *     string(19) "function#strtoupper"
 */

Finally, this is possible to get a reflection instance of the current callable
(can be of kind ReflectionFunction,
ReflectionClass,
ReflectionMethod or
ReflectionObject):

var_dump($xcallable->getReflection());
/**
 * Will output:
 *     object(ReflectionFunction)#42 (1) {
 *       ["name"]=>
 *       string(10) "strtoupper"
 *     }
 */

When the object is set but not the method, the latter will be deduced if
possible. If the object is of kind
Hoa\Stream, then
according to the type of the arguments given to the callable, the
writeInteger, writeString, writeArray etc. method will be used. If the
argument is of kind Hoa\Event\Bucket, then the method name will be deduced
based on the data contained inside the event bucket. This is very handy. For
instance, the following example will work seamlessly:

Hoa\Event\Event::getEvent('hoa://Event/Exception')
    ->attach(new Hoa\File\Write('Exceptions.log'));

The attach method on Hoa\Event\Event transforms its argument as an
xcallable. In this particular case, the method to call is unknown, we only have
an object (of kind Hoa\File\Write). However, because this is a stream, the
method will be deduced according to the data contained in the event bucket fired
on the hoa://Event/Exception event channel.

Documentation

The
hack book of Hoa\Consistency
contains detailed information about how to use this library and how it works.

To generate the documentation locally, execute the following commands:

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

More documentation can be found on the project’s website:
hoa-project.net.

Getting help

There are mainly two ways to get help:

• On the #hoaproject
  IRC channel,
• On the forum at users.hoa-project.net.

Contribution

Do you want to contribute? Thanks! A detailed contributor
guide explains
everything you need to know.

License

Hoa is under the New BSD License (BSD-3-Clause). Please, see
LICENSE for details.