Download the PHP package hoa/exception without Composer

Hoa is a modular, extensible and structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds.

Hoa\Exception

This library allows to use advanced exceptions. It provides generic exceptions (that are sent over the hoa://Event/Exception event channel), idle exceptions (that are not sent over an event channel), uncaught exception handlers, errors to exceptions handler and group of exceptions (with transactions).

Learn more.

Installation

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

For more installation procedures, please read the Source page.

Testing

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

Then, to run all the test suites:

For more information, please read the contributor guide.

Quick usage

We propose a quick overview of how to use generic exceptions, how to listen all thrown exceptions through events and how to use group of exceptions.

Generic exceptions

An exception is constitued of:

• A message,
• A code (optional),
• A list of arguments for the message (à la printf, optional),
• A previous exception (optional).

Thus, the following example builds an exception:

The exception message will be: Hello world!. The “raise” message (with all information, not only the message) is:

Previous exceptions are shown too, for instance:

Listen exceptions through events

Most exceptions in Hoa extend Hoa\Exception\Exception, which fire themselves on the hoa://Event/Exception event channel (please, see the Hoa\Event library). Consequently, we can listen for all exceptions that are thrown in the application by writing:

Only the Hoa\Exception\Idle exceptions are not fired on the channel event.

Group and transactions

Groups of exceptions are represented by the Hoa\Exception\Group. A group is an exception that contains one or many exceptions. A transactional API is provided to add more exceptions in the group with the following methods:

• beginTransaction to start a transaction,
• rollbackTransaction to remove all newly added exceptions since beginTransaction call,
• commitTransaction to merge all newly added exceptions in the previous transaction,
• hasUncommittedExceptions to check whether they are pending exceptions or not.

For instance, if an exceptional behavior is due to several reasons, a group of exceptions can be thrown instead of one exception. Group can be nested too, which is useful to represent a tree of exceptions. Thus:

The following example uses a transaction to add new exceptions in the group:

Documentation

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

To generate the documentation locally, execute the following commands:

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.