Close search

The Nucleus release series

Written the .

You know that feeling when you have a prickle in the feet: You can walk but sometimes it hurts. Well, it's been a long time we are thinking about solving an issue in Hoa: The Hoa\Core library. While Hoa stands as a set of libraries, Hoa\Core was kind of a monolithic piece of code required by all libraries. This was not terrible and it was even justified at the origin. Indeed, it was designed to gather several thin layers into a single library for performance reasons. Let me explain it shortly. Parsing time is not very costly compared to I/O: Accessing to a file, opening it and reading it. The core aimed at putting the minimum always needed codes into small and optimized files, in order to reduce this I/O time. However, since recent PHP versions and recent I/O progresses (SSD, kernel, FS…), this is no longer necessary. That's why in October we finally decided that it was time to split the core!

This work could introduce small potential BC breaks so we decided to do this while dropping PHP5.4 support. Since PHP5.4 is dead and no longer support by the PHP group, it is logical that we drop it too. Dropping a PHP version is considered as a BC break and this was expected, as described in the Source page.

Consequences of the split

Splitting a core is well-known to produce a ton of energy. Hoa\Core was not an exception.

So, Hoa\Core is dead and has been split into the following libraries:

You can visit these links and follow their files to learn more but names are self-describing. Shortly, here are small descriptions.

Hoa\Consistency provides a thin layer between PHP VMs and libraries to ensure consistency accross VM versions and library versions. For instance, it frontports functions like trait_exists or interfaces like Throwable. It provides useful methods like isIdentifier or isKeyword to respectivelly check if a datum is a valid PHP identifier or a reserved keyword. It also provides a PSR-4 autoloader and some other useful tools ensuring a better compatibility accross the time. Considering the weak number of BC breaks we have introduced in the whole Hoa's history and our experience in this domain, this library might interest you. It stands in critical places where BC breaks might happen often.

Hoa\Event provides events and listeners in PHP. This is an observer design-pattern implementation but it defines fundamental differences between events and listeners in term of synchronisity, identity and scope. These definitions are most of the time ignored and, while the consequences are not disasters, it can lead to badly designed API.

Hoa\Exception provides powerful exception implementations with errors, generic exceptions, idle exceptions and group of exceptions. This latter is useful when dealing with exceptions from several sources and putting them together to expose a single, clean and easy to understand exception. You can begin, rollback or commit a group of exceptions inside another group (like classical transactions) etc.

Hoa\Protocol is the implementation of the hoa:// protocol which abstracts resource accesses. This protocol is extensible and is often embedded in other softwares. Files, memory resources, network resources… it can represent anything. You will no longer have to deal with runtime current working directory and be afraid of moving a resource from one location to another one. The hoa:// protocol is here to abstract the access and ensure a retro-compatibility.

Benefits of the split

We talked about energy. Here it is.

The immediate benefits is that there is no longer a core! It sounds simple but it was a blocker for several users world-wide. Mostly for projects that would like to embed Hoa inside their code. Having something similar to “a framework” (we should double or triple quotes here) is bad. Actually, it sounded like a framework core but it was not at all; It was just an optimization, nothing more. Well, now it has disappeared.

The core was not easy to test too. Now, since we have several libraries, it's easy to test and we have:

  • 20 new test suites, which represents
  • 223 test cases, be
  • 3054 new assertions.

That was for the quality part. The performance part on the other hand is also very interesting. The Hoa\Core library was always de-facto autoloaded because some API was necessary. Since the split, we only need the Hoa/Consistency/Prelude.php file. Having a prelude is something very common, see in Rust or C for instance. It just checks if Hoa libraries can run, it defines some constants and defines the autoloader. All libraries require Hoa\Consistency, which is pretty logical. You don't have to manage the prelude, it is managed for you, especially if you are using Composer. So here are the performance results between Hoa\Core and Hoa\Consistency for the initialization:

Time (for 1000 runs)Memory (for 1 run)

Such a memory savings was not expected. And this is a good surprise! It's good to see that also time has been saved during the battle. These results were obtained with no PHP optimization, like opcache. This is pure PHP.


So, not only the API is cleaner, not only more projects can re-use our new libraries (but not new code), not only the quality is better, but the performances are also better. These 3.5 months of work have been justified and rewarded.

As usual, this is the result of a team work. We would like to thank all Hoackers, especially (in alphabetic order):

  • Julien Bianchi,
  • Julien Clauzel,
  • Raphaël Emourgeon,
  • Ivan Enderlin,
  • Alexis von Glasow,
  • Matthieu de Laubrie,
  • Pierre Tomasina,

for all the reviews, feedbacks, ideas and motivations. This was 79 PR or issues to review, with more than 96 test suites, 810 test cases and 180,954 assertions to keep green.

Finally, the new minimum required PHP version is 5.5, which is great. Hoa is obviously compatible with PHP 7.

We would like to wish you a happy new year and happy hoacking!