Exceptions

The aim of this package is to provide a base exception class from which to extend for internal application exceptions.

This package contains one base exception - ServiceException which provides several helper methods for standardising exception outputs.

Installation

composer require philcross/exceptions:"^1.0"

Support

Package Version	PHP Versions Supported
1.x	8.1, 8.2, 8.3, 8.4, 8.5

Usage

Extending the ServiceException

The ServiceEXception class in this package is designed to be extended to provide additional data for application exceptions. It will return sensible default values, preventing sensitive data leaking to client side users.

use PhilCross\Exceptions\ServiceException;

class ServiceUnavailableException extends ServiceException
{
    //
}

Some properties can be overridden to provide exception specific defaults:

use PhilCross\Exceptions\ServiceException;

class UserNotFoundException extends ServiceException
{
    protected int $status = 404;
    protected string $title = 'User not found';
    protected string $safeMessage = 'The requested user could not be found.';
}

By default, all exceptions are classed as reportable. You can set whether you want this exception reportable by changing the $reportable property:

use PhilCross\Exceptions\ServiceException;

class DataValidationException extends ServiceException
{
    protected int $status = 422;
    protected bool $reportable = false;
}

If you require more advanced logic to determine if it should be reported, you can use the shouldReport() method:

use PhilCross\Exceptions\ServiceException;

class ServiceUnavailableException extends ServiceException
{
    public function shouldReport() : bool
    {
        return rand(0, 1) === 1;
    }
}

Hooks can be used to decorate exceptions with additional behaviour. Hooks are ran during instantiation. This is useful if you want to automatically report exceptions to Sentry, or add additional context:

use PhilCross\Exceptions\ServiceException;

class SomeServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        ServiceException::addHook(function (ServiceException $exception) {
            $exception->addMeta('authenticated_user_id', Auth::user()->id);
        });
        
        ServiceException::addHook(function (ServiceException $exception) {
            \sentry\captureException($exception);
        });
    }
}

/**
 * This will:
 *  - add authenticated_user_id to the exceptions metadata
 *  - automatically report the exception to sentry during construction
 */
throw new ServiceException('test');

If you want to instantiate an exception without running any hooks already set:

use PhilCross\Exceptions\ServiceException;

class SomeServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        ServiceException::addHook(function (ServiceException $exception) {
            \sentry\captureException($exception);
        });
    }
}

/**
 * This will:
 *  - add authenticated_user_id to the exceptions metadata
 *  - automatically report the exception to sentry during construction
 */
throw ServiceException::withoutHooks('test');

Out of box exceptions

This package comes with several exceptions out of the box:

Exception	Usage
ConflictException	Useful for extending when there is a conflict in application state. Will use the HTTP status 409
NotAuthenticatedException	Useful for extending or throwing when a request requiring authentication is made be an unauthenticated user. Will use the HTTP status 401
NotAuthorisedException	Useful for extending or throwing when an authenticated user makes a request, but lacks the expected permissions. Will use the HTTP status 403
ValidationException	Useful in combination with Laravels validation exception. Will return the HTTP status 422

Testing

This package comes with a full phpunit testsuite, as well as a phpcs checker and beautifier.

Command	Alias	Description
./vendor/bin/phpunit --configuration=phpunit.xml	composer test	Runs all phpunit tests
./vendor/bin/phpcs	composer phpcs	Runs code standards checks
./vendor/bin/phpcbf	composer clean	Runs code linting based on code standards
composer check	runs the code beautifier, tests and phpcs in that order