phpro/api-problem-bundle

RFC7807 Problem details integration for Symfony

1.9.0 2024-12-02 08:43 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• phpro/api-problem: ^1.0
• symfony/dependency-injection: ^5.4 || ^6.0 || ^7.0
• symfony/event-dispatcher: ^5.4 || ^6.0 || ^7.0
• symfony/http-kernel: ^6.4 || ^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.39
• matthiasnoback/symfony-dependency-injection-test: ^4.3
• phpro/grumphp-shim: ^2.3
• phpspec/prophecy: ^1.17
• phpspec/prophecy-phpunit: ^2.0
• phpunit/phpunit: ^9.5
• symfony/security-core: ^5.4 || ^6.0 || ^7.0

MIT

• Toon Verwerft

README

Api Problem Bundle

This package provides a RFC7807 Problem details exception listener for Symfony. Internal, this package uses the models provided by phpro/api-problem. When an ApiProblemException is triggered, this bundle will return the correct response.

Installation

composer require phpro/api-problem-bundle

If you are not using symfony/flex, you'll have to manually add the bundle to your bundles file:

// config/bundles.php

return [
    // ...
    Phpro\ApiProblemBundle\ApiProblemBundle::class => ['all' => true],
];

Supported response formats

• application/problem+json

How it works

use Phpro\ApiProblem\Exception\ApiProblemException;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;

class SomeController
{
    /**
     * @Route('/some-route', defaults={"_format" = "json"})
     */
    public function someAction() {
        throw new ApiProblemException(
            new HttpApiProblem('400', 'It aint all bad ...')
        );
    }
}

When the controller is marked as a "json" format, the request Content-Type is */json or the request Accept header first value contains json (i.e. application/json, text/html), this bundle kicks in. It will transform the exception to following response:

Headers:

Content-Type: application/problem+json

Body:

{
    "status": 400,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Bad Request",
    "detail": "It ain't all bad ..."
}

As an alternative, use ApiProblemHttpException instead of ApiProblemException, to make it possible to exclude the specific status code from the log

Adding custom exception transformations

Currently, we automatically transform exceptions from following packages to an ApiProblem instance:

• phpro/api-problem
• symfony/http-kernel
• symfony/security

Besides that, all other errors are transformed to a basic ExceptionApiProblem instance.

If you want to add custom transformations, you can implement the ExceptionTransformerInterface and register it in the symfony container with the phpro.api_problem.exception_transformer tag.

use Phpro\ApiProblemBundle\Transformer\ExceptionTransformerInterface;

class MyTransformer implements ExceptionTransformerInterface
{
    public function transform(\Throwable $exception): ApiProblemInterface
    {
        return new MyApiProblem($exception);
    }

    public function accepts(\Throwable $exception): bool
    {
        return $exception instanceof MyException;
    }
}

About

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub. Please take a look at our rules before contributing your code.

License

api-problem-bundle is licensed under the MIT License.