README

how exceptable!

A lot of php code treats exceptions in an ad-hoc way: throwing a plain Exception instance with a message written inline. Then, when (...if?) you look at your error log, you have to start working backwards to figure out the state of the application at that time. This can be frustrating and painful.

Exceptables make exceptions exceptional. Exceptables:

✓ are easy to create and pass details to
✓ are readable by both humans and your application code
✓ can provide a wealth of runtime information about the state of things that led to the problem
✓ make it easy to add, adapt, and maintain error handling code as your application grows

More importantly, when throwing an Exceptable, you can include any additional information that might be helpful - values of arguments or local variables, details about state, whole objects, anything! This context is good for adding details to the error message, but can also be sent to log aggregation tools, and even be used at runtime to inspect the error and recover or fail gracefully.

dependencies

Requires php 8.3 or later.

ICU support requires the intl extension.

installation

Recommended installation method is via Composer:

simply composer require "php-enspired/exceptable:^6"

a quick taste

<?php
use at\exceptable\ {
  Fault,
  EnumeratesFaults
};

// A simple Fault, just for you
enum ProcessFault : string implements Fault {
  use EnumeratesFaults;

  case NotReady = "{type} is not ready (status is '{status}')";
}

class Example {
  public function __construct( public ExampleStatus $status ) {}
}
enum ExampleStatus {
  case Preparing;
  case Ready;
}

$example = new Example(ExampleStatus::Preparing);
if ($example->status !== ExampleStatus::Ready) {
  throw (ProcessFault::NotReady)([
    "type" => $example::class,
    "status" => $example->status
  ]);
}

// results in:
//  Fatal error: Uncaught at\exceptable\Spl\RuntimeException: ProcessError.NotReady: Example is not ready (status is 'preparing')

Having faults available to your application also means you don't have to throw exceptions: your methods can return first-class error values. This approach encourages handling error cases more carefully and closer to their source and is also a benefit to static analysis. See Larry Garfield's excellent article "A Naked Result" for more about this idea and its benefits.

Version 6.0

6.0 requires PHP 8.3 or greater.

It also changes the api fairly substantially in two ways:

The focus is changing from excpetions to more of a Fault (formerly, "Error")-first approach.
Many of the old error "handling" utilities are removed in favor of more practical tools that help you use faults and exceptables in your own code, while also smoothing out usage of other code that doesn't.

Additionally, exceptable is now released under the Mozilla Public License, version 2.

Previously, the software was released under the GPLv3. That license's strong copyleft protections were a major factor in the decision to use it, but it has become apparent that their interpretations of what constitutes "combined works" was much broader than I'd understood it to be. Specifically, merely declaring this package as a dependency (e.g., via composer), without actually modifying and/or including/distributing the code with your software, was never intended to trigger these protections.

If you are using a previous version of this software licensed under the GPLv3, and would prefer to use it under the MPL instead, please contact me. I will grant the relicensing and waive enforcement action against you arising from any noncompliance with the GPLv3, if it would be permissible under the MPL.

Read the release notes.

docs

Usage

Api

tests

You can run unit tests with composer test:unit and static analysis with composer test:analyze.

Note, the first time you run a test: command, dev dependencies will be installed automatically. This requires an internet connection and may take some time.

contributing or getting help

I'm on IRC at libera#php-enspired, or open an issue on github. Feedback is welcomed as well.

php-enspired / exceptable

Maintainers

Details