Exception handling

There are several things that can go wrong while Apitizer handles a request. By default, exceptions are raised. This can be tweaked in several ways. Generally, there are 3 ways to change the exception handling:

  • Globally
  • For one or multiple schemas.
  • For one specific schema instance.

All of these cases are accomplished in the same way: by changing the ExceptionStrategy. There are two strategies available out of the box:

  • Apitizer\ExceptionStrategy\Raise raise the exception. This is the default behaviour.
  • Apitizer\ExceptionStrategy\Ignore ignore the exception.

Global exception handler

To change the default exception strategy for all schemas, you can bind your preferred strategy in Laravel's container. This can be done in a provider.

<?php

use Apitizer\ExceptionStrategy\Ignore;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        // Set the default to ignore.
        $this->app->bind(Strategy::class, Ignore::class);
    }
}

One or multiple schemas

Every Apitizer\Schema has the getExceptionStrategy method that returns an instance of the Strategy class. You can override this method with your own implementation that returns the exception strategy for that specific schema (or any of it's children, if you declare it on an abstract base class).

<?php

use Apitizer\ExceptionStrategy\Strategy;

class PostSchema extends Schema
{
    public function getExceptionStrategy(): Strategy
    {
        return MyStrategyImplementation();
    }
}

Per instance

Besides the getExceptionStrategy method, there's also the setExceptionStrategy that can be used on a per-instance basis to set the appropriate strategy. This method accepts either null (to reset the current exception strategy back to its default), or a Strategy implementation.

Custom strategies

A custom strategy can be useful to tweak the behaviour of Apitizer. Furthermore, certain exceptions only occur when a programmer error has caused it (for example, by writing an invalid schema) and you will likely want to log these messages to some service or file.

<?php

use Apitizer\ExceptionStrategy\Strategy;
use Apitizer\Schema;
use Apitizer\Exceptions\ApitizerException;
use Apitizer\Exceptions\InvalidOutputException;

class MyStrategy implements Strategy
{
    public function handle(Schema $schema, ApitizerException $exception): void
    {
        if ($exception instanceof InvalidOutputException) {
            // log to sentry, bugsnag, or w/e
        }

        throw $exception;
    }
}

The Apitizer\Exceptions\InvalidOutputException is an important exception to handle in your strategy, as this exception only occurs when there is a mismatch between the schema definition and the data that was actually fetched from the data source. When this exception reaches your strategy, it should ideally alert one of the developers that there is a mistake in the schema definition that should be fixed ASAP. The exception itself contains a wealth of information on where this error occurred and how it might be fixed.

With the combination of the ./artisan apitizer:validate-schema command, and the possibility of running the schema validator in a test, you should strife to never see Apitizer\Exceptions\DefinitionException in production. If it does occur, then same as the InvalidOutputException it should alert a developer and it should be fixed ASAP.