Close search
Hoa

Hack book of Hoa\Consistency

Unfortunately, the documentation of this library has not been written yet. However, the README.md file may contain enough information to help you. This document is an extract of the README.md file.
Sorry for this inconvenience. Be ensured we are working hard to fix this.

Help on IRC Help on Gitter Documentation Board

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

Learn more.

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:

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:

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.

An error or a suggestion about the documentation? Contributions are welcome!

Comments

menu