PHPackages                             phpro/api-problem - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. phpro/api-problem

ActiveLibrary[API Development](/categories/api)

phpro/api-problem
=================

RFC7807 Problem details implementation

1.9.0(7mo ago)67791.4k↓16.4%8[2 issues](https://github.com/phpro/api-problem/issues)6MITPHPPHP ~8.3.0 || ~8.4.0 || ~8.5.0CI passing

Since Aug 31Pushed 7mo ago6 watchersCompare

[ Source](https://github.com/phpro/api-problem)[ Packagist](https://packagist.org/packages/phpro/api-problem)[ RSS](/packages/phpro-api-problem/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (13)Used By (6)

[![Travis](https://camo.githubusercontent.com/f62cb8ed6fa8df25be6c02264b5672374fd8a9f3c0158d0d6ccc9bf8f8e52b8c/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f706870726f2f6170692d70726f626c656d2f6d61737465722e737667)](http://travis-ci.org/phpro/api-problem)[![Installs](https://camo.githubusercontent.com/607f3b58ea04b110260f6bf665b9f1a3ae1a5c45663bf7135d5a87a39a441906/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f706870726f2f6170692d70726f626c656d2e737667)](https://packagist.org/packages/phpro/api-problem/stats)[![Packagist](https://camo.githubusercontent.com/1201bfd89ac989dfd995709038af059a6f00e562aa731e29890326faedb20e74/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f706870726f2f6170692d70726f626c656d2e737667)](https://packagist.org/packages/phpro/api-problem)

Api Problem
===========

[](#api-problem)

This package provides a [RFC7807](https://tools.ietf.org/html/rfc7807) Problem details implementation. It can be integrated everywhere in your code and should result in a general error response format for HTTP APis.

This package only provides a generic interface, an exception class and some built-in api problem messages. Since handling the exceptions is up to the framework, here is a list of known framework integrations:

- **Symfony** `^4.1`: [ApiProblemBundle](https://www.github.com/phpro/api-problem-bundle)

Installation
------------

[](#installation)

```
composer require phpro/api-problem
```

Usage
-----

[](#usage)

This package provides a general interface for creating ApiProblem value objects.

```
use Phpro\ApiProblem\Exception;

throw new ApiProblemException(
    new HttpApiProblem(418, ['detail' => 'Did you know 4,000 people are injured by teapots every year?!'])
);
```

### Built-in problems

[](#built-in-problems)

- General problems

    - [ExceptionApiProblem](#exceptionapiproblem)
    - [HttpApiProblem](#httpapiproblem)
- Symfony integration problems

    - [ValidationApiProblem](#validationapiproblem)
- Http problems

    - 400 [BadRequestProblem](#badrequestproblem)
    - 401 [UnauthorizedProblem](#unauthorizedproblem)
    - 403 [ForbiddenProblem](#forbiddenproblem)
    - 404 [NotFoundProblem](#notfoundproblem)
    - 405 [MethodNotAllowedProblem](#methodnotallowedproblem)
    - 409 [ConflictProblem](#conflictproblem)
    - 412 [PreconditionFailedProblem](#preconditionfailedproblem)
    - 415 [UnsupportedMediaTypeProblem](#unsupportedmediatypeproblem)
    - 418 [IAmATeapotProblem](#iamateapotproblem)
    - 422 [UnprocessableEntityProblem](#unprocessableentityproblem)
    - 423 [LockedProblem](#lockedproblem)
    - 428 [PreconditionRequiredProblem](#preconditionrequiredproblem)

#### ExceptionApiProblem

[](#exceptionapiproblem)

*Debuggable*: The `exception` part will only be added in debug context!

```
use Phpro\ApiProblem\Http\ExceptionApiProblem;

new ExceptionApiProblem(new \Exception('message', 500));
```

```
{
  "status": 500,
  "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
  "title": "Internal Server Error",
  "detail": "message",
  "exception": {
    "message": "message",
    "type": "RuntimeException",
    "code": 500,
    "line": 23,
    "file": "exception.php",
    "trace": [
         "#0 [internal function]: ...",
         "#1 [internal function]: ...",
         "#3 [internal function]: ...",
         "..."
    ],
    "previous": [
      {
        "message": "previous",
        "type": "InvalidArgumentException",
        "code": 0,
        "line": 20,
        "file": "exception.php",
        "trace": [
            "#0 [internal function]: ...",
            "#1 [internal function]: ...",
            "#3 [internal function]: ...",
            "..."
        ]
      }
    ]
  }
}
```

#### HttpApiProblem

[](#httpapiproblem)

```
use Phpro\ApiProblem\Http\HttpApiProblem;

new HttpApiProblem(404, ['detail' => 'The book could not be found.']);
```

```
{
    "status": 404,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Not found",
    "detail": "The book could not be found."
}
```

#### ValidationApiProblem

[](#validationapiproblem)

```
composer require symfony/validator:^4.1
```

```
use Phpro\ApiProblem\Http\ValidationApiProblem;
use Symfony\Component\Validator\ConstraintViolation;
use Symfony\Component\Validator\ConstraintViolationList;

new ValidationApiProblem(new ConstraintViolationList([
    new ConstraintViolation('Invalid email', '', [], '', 'email', '', null, '8615ecd9-afcb-479a-9c78-8bcfe260cf2a'),
]));
```

```
{
    "status": 400,
    "type": "https:\/\/symfony.com\/errors\/validation",
    "title": "Validation Failed",
    "detail": "email: Invalid Email",
    "violations": [
        {
            "propertyPath": "email",
            "title": "Invalid email",
            "type": "urn:uuid:8615ecd9-afcb-479a-9c78-8bcfe260cf2a"
        }
    ]
}
```

#### BadRequestProblem

[](#badrequestproblem)

```
use Phpro\ApiProblem\Http\BadRequestProblem;

new BadRequestProblem('Bad request. Bad!.');
```

```
{
    "status": 400,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Bad Request",
    "detail": "Bad request. Bad!"
}
```

#### UnauthorizedProblem

[](#unauthorizedproblem)

```
use Phpro\ApiProblem\Http\UnauthorizedProblem;

new UnauthorizedProblem('You are not authorized to access X.');
```

```
{
    "status": 401,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Unauthorized",
    "detail": "You are not authenticated. Please login."
}
```

#### ForbiddenProblem

[](#forbiddenproblem)

```
use Phpro\ApiProblem\Http\ForbiddenProblem;

new ForbiddenProblem('Not authorized to access gold.');
```

```
{
  "status": 403,
  "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
  "title": "Forbidden",
  "detail": "Not authorized to access gold."
}
```

#### NotFoundProblem

[](#notfoundproblem)

```
use Phpro\ApiProblem\Http\NotFoundProblem;

new NotFoundProblem('The book with ID 20 could not be found.');
```

```
{
    "status": 404,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Not found",
    "detail": "The book with ID 20 could not be found."
}
```

#### MethodNotAllowedProblem

[](#methodnotallowedproblem)

```
use Phpro\ApiProblem\Http\MethodNotAllowedProblem;

new MethodNotAllowedProblem('Only POST and GET allowed.');
```

```
{
    "status": 405,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Method Not Allowed",
    "detail": "Only POST and GET allowed."
}
```

#### ConflictProblem

[](#conflictproblem)

```
use Phpro\ApiProblem\Http\ConflictProblem;
new ConflictProblem('Duplicated key for book with ID 20.');
```

```
{
    "status": 409,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Conflict",
    "detail": "Duplicated key for book with ID 20."
}
```

#### PreconditionFailedProblem

[](#preconditionfailedproblem)

```
use Phpro\ApiProblem\Http\PreconditionFailedProblem;

new PreconditionFailedProblem('Incorrect entity tag provided.');
```

```
{
    "status": 412,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Precondition Failed",
    "detail": "Incorrect entity tag provided."
}
```

#### UnsupportedMediaTypeProblem

[](#unsupportedmediatypeproblem)

```
use Phpro\ApiProblem\Http\UnsupportedMediaTypeProblem;

new UnsupportedMediaTypeProblem('Please provide valid JSON.');
```

```
{
    "status": 415,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Unsupported Media Type",
    "detail": "Please provide valid JSON."
}
```

#### IAmATeapotProblem

[](#iamateapotproblem)

```
use Phpro\ApiProblem\Http\IAmATeapotProblem;

new IAmATeapotProblem('More tea please.');
```

```
{
    "status": 418,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "I'm a teapot",
    "detail": "More tea please."
}
```

#### UnprocessableEntityProblem

[](#unprocessableentityproblem)

```
use Phpro\ApiProblem\Http\UnprocessableEntityProblem;

new UnprocessableEntityProblem('Unable to process the contained instructions.');
```

```
{
    "status": 422,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Unprocessable Entity",
    "detail": "Unable to process the contained instructions."
}
```

#### LockedProblem

[](#lockedproblem)

```
use Phpro\ApiProblem\Http\LockedProblem;

new LockedProblem('This door is locked.');
```

```
{
    "status": 423,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Locked",
    "detail": "This door is locked."
}
```

#### PreconditionRequiredProblem

[](#preconditionrequiredproblem)

```
use Phpro\ApiProblem\Http\PreconditionRequiredProblem;

new PreconditionRequiredProblem('If-match header is required.');
```

```
{
    "status": 428,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Precondition Required",
    "detail": "If-match header is required."
}
```

### Creating your own problem

[](#creating-your-own-problem)

Creating problem sounds scary right!? Since the RFC is very loose, we made the interface as easy as possible:

```
use Phpro\ApiProblem\ApiProblemInterface;

class MyProblem implements ApiProblemInterface
{
    public function toArray(): array
    {
        return [
            'type' => 'about:blank',
            'status' => '99',
            'title' => 'Got 99 problems but a glitch aint one!',
        ];
    }
}
```

A lot of problems will be detected in an HTTP context. Therefore, we also provided a base `HttpApiProblem` class. This one will automatically fill in the type and title section based on the HTTP code. The only thing you'll need to do, is add some additional data to it:

```
use Phpro\ApiProblem\Http\HttpApiProblem;

class MyProblem extends HttpApiProblem
{
    public function __construct(string $details)
    {
        parent::__construct(500, ['details' => $details]);
    }
}
```

If you want to log additional information in a debug context, it is possible to implement an additional `DebuggableApiProblemInterface`:

```
use Phpro\ApiProblem\DebuggableApiProblemInterface;

class MyProblem implements DebuggableApiProblemInterface
{
    public function toArray(): array
    {
        return [
            'type' => 'about:blank',
            'status' => '99',
            'title' => 'Got 99 problems but a glitch ain\'t one!',
        ];
    }

    public function toDebuggableArray(): array
    {
        return array_merge(
            $this->toArray(),
            [
                'situation' => 'If you are having code problems, I feel bad for you son',
            ]
        );
    }
}
```

About
-----

[](#about)

### Submitting bugs and feature requests

[](#submitting-bugs-and-feature-requests)

Bugs and feature request are tracked on [GitHub](https://github.com/phpro/api-problem/issues). Please take a look at our rules before [contributing your code](CONTRIBUTING).

### License

[](#license)

api-problem is licensed under the [MIT License](LICENSE).

###  Health Score

62

—

FairBetter than 99% of packages

Maintenance64

Regular maintenance activity

Popularity52

Moderate usage in the ecosystem

Community26

Small or concentrated contributor base

Maturity87

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 76.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~237 days

Recently: every ~356 days

Total

12

Last Release

210d ago

PHP version history (6 changes)v1.0.0PHP ^7.2

v1.4.0PHP ^7.3 || ^8.0

v1.5.0PHP ^8.0

1.7.0PHP ~8.1.0 || ~8.2.0 || ~8.3.0

1.8.0PHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0

1.9.0PHP ~8.3.0 || ~8.4.0 || ~8.5.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/cab1b0de06c75fec5317beded0c2978f3e9e560e6830c1d9048f3e37b3287342?d=identicon)[phpro](/maintainers/phpro)

---

Top Contributors

[![veewee](https://avatars.githubusercontent.com/u/1618158?v=4)](https://github.com/veewee "veewee (26 commits)")[![pottink](https://avatars.githubusercontent.com/u/2572887?v=4)](https://github.com/pottink "pottink (4 commits)")[![avandenbogaert](https://avatars.githubusercontent.com/u/2714711?v=4)](https://github.com/avandenbogaert "avandenbogaert (1 commits)")[![Landerstraeten](https://avatars.githubusercontent.com/u/5587595?v=4)](https://github.com/Landerstraeten "Landerstraeten (1 commits)")[![lucassabreu](https://avatars.githubusercontent.com/u/3457213?v=4)](https://github.com/lucassabreu "lucassabreu (1 commits)")[![neeckeloo](https://avatars.githubusercontent.com/u/1768645?v=4)](https://github.com/neeckeloo "neeckeloo (1 commits)")

### Embed Badge

![Health badge](/badges/phpro-api-problem/health.svg)

```
[![Health](https://phpackages.com/badges/phpro-api-problem/health.svg)](https://phpackages.com/packages/phpro-api-problem)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk

PHP SDK for Facebook Business

90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

265103.1M454](/packages/google-gax)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)