PHPackages                             lezhnev74/openapi-psr7-validator - 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. [HTTP & Networking](/categories/http)
4. /
5. lezhnev74/openapi-psr7-validator

Abandoned → [league/openapi-psr7-validator](/?search=league%2Fopenapi-psr7-validator)Library[HTTP & Networking](/categories/http)

lezhnev74/openapi-psr7-validator
================================

Validate PSR-7 messages against OpenAPI (3.0.2) specifications expressed in YAML or JSON

0.16(6y ago)14762.3k10[2 issues](https://github.com/lezhnev74/openapi-psr7-validator/issues)[2 PRs](https://github.com/lezhnev74/openapi-psr7-validator/pulls)MITPHPPHP >=7.1CI failing

Since May 3Pushed 4y ago12 watchersCompare

[ Source](https://github.com/lezhnev74/openapi-psr7-validator)[ Packagist](https://packagist.org/packages/lezhnev74/openapi-psr7-validator)[ Docs](https://github.com/lezhnev74/openapi-psr7-validator)[ RSS](/packages/lezhnev74-openapi-psr7-validator/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (11)Versions (41)Used By (0)

[![Latest Stable Version](https://camo.githubusercontent.com/190213a1b4103915dffa36063ed96b9be3c2de79a400eb56a977a2d294d5ff0f/68747470733a2f2f706f7365722e707567782e6f72672f6c657a686e657637342f6f70656e6170692d707372372d76616c696461746f722f762f737461626c65)](https://packagist.org/packages/lezhnev74/openapi-psr7-validator)[![Build Status](https://camo.githubusercontent.com/771ea8b2129c90f417c3ab1ad553b87f3e0f001292a74c3ab930d37627123a98/68747470733a2f2f7472617669732d63692e6f72672f6c657a686e657637342f6f70656e6170692d707372372d76616c696461746f722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/lezhnev74/openapi-psr7-validator)[![License](https://camo.githubusercontent.com/a2b67248a10301362fa6e6348b9d5c122fd82d5dc30f3511b72c7d7c5d76d060/68747470733a2f2f706f7365722e707567782e6f72672f6c657a686e657637342f6f70656e6170692d707372372d76616c696461746f722f6c6963656e7365)](https://packagist.org/packages/lezhnev74/openapi-psr7-validator)[![contributions welcome](https://camo.githubusercontent.com/382079383bf5ec051cfa878df7b3d9a70a5f5052e573c67033d4d3f7e376a6d4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f6e747269627574696f6e732d77656c636f6d652d627269676874677265656e2e737667)](https://camo.githubusercontent.com/382079383bf5ec051cfa878df7b3d9a70a5f5052e573c67033d4d3f7e376a6d4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f6e747269627574696f6e732d77656c636f6d652d627269676874677265656e2e737667)

NOTICE - THE PACKAGE HAS BEEN CONTRIBUTED TO THE PHP LEAGUE
===========================================================

[](#notice---the-package-has-been-contributed-to-the-php-league)

Go to

This package is here for existing users only.

OpenAPI PSR-7 Message (HTTP Request/Response) Validator
=======================================================

[](#openapi-psr-7-message-http-requestresponse-validator)

This package can validate PSR-7 messages against OpenAPI (3.0.x) specifications expressed in YAML or JSON.

[![](image.jpg)](image.jpg)

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

[](#installation)

```
composer require lezhnev74/openapi-psr7-validator

```

OpenAPI (OAS) Terms
-------------------

[](#openapi-oas-terms)

There are some specific terms that are used in the package. These terms come from OpenAPI:

- `specification` - an OpenAPI document describing an API, expressed in JSON or YAML file
- `data` - actual thing that we validate against a specification, including body and metadata
- `schema` - the part of the specification that describes the body of the request / response
- `keyword` - properties that are used to describe the instance are called key words, or schema keywords
- `path` - a relative path to an individual endpoint
- `operation` - a method that we apply on the path (like `get /password`)
- `response` - described response (includes status code, content types etc)

How To Validate
---------------

[](#how-to-validate)

### ServerRequest Message

[](#serverrequest-message)

You can validate `\Psr\Http\Message\ServerRequestInterface` instance like this:

```
$yamlFile = "api.yaml";
$jsonFile = "api.json";

$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getServerRequestValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYaml(file_get_contents($yamlFile))->getServerRequestValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJson(file_get_contents($jsonFile))->getServerRequestValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJsonFile($jsonFile)->getServerRequestValidator();
#or
$schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getServerRequestValidator();

$match = $validator->validate($request);
```

As a result you would get and `OperationAddress $match` which has matched the given request. If you already know the operation which should match your request (i.e you have routing in your project), you can use `RouterRequestValidator`

```
$address = new \OpenAPIValidation\PSR7\OperationAddress('/some/operation', 'post');

$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getRoutedRequestValidator();

$validator->validate($address, $request);
```

This would simplify validation a lot and give you more performance.

### Request Message

[](#request-message)

You can validate `\Psr\Http\Message\RequestInterface` instance like this:

```
$yamlFile = "api.yaml";
$jsonFile = "api.json";

$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getRequestValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYaml(file_get_contents($yamlFile))->getRequestValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJson(file_get_contents($jsonFile))->getRequestValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJsonFile($jsonFile)->getRequestValidator();
#or
$schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getRequestValidator();

$match = $validator->validate($request);
```

### Response Message

[](#response-message)

Validation of `\Psr\Http\Message\ResponseInterface` is a bit more complicated . Because you need not only YAML file and Response itself, but also you need to know which operation this response belongs to (in terms of OpenAPI).

Example:

```
$yamlFile = "api.yaml";
$jsonFile = "api.json";

$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getResponseValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYaml(file_get_contents($yamlFile))->getResponseValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJson(file_get_contents($jsonFile))->getResponseValidator();
#or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJsonFile($jsonFile)->getResponseValidator();
#or
$schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getResponseValidator();

$operation = new \OpenAPIValidation\PSR7\OperationAddress('/password/gen', 'get') ;

$validator->validate($operation, $request);
```

### Reuse Schema After Validation

[](#reuse-schema-after-validation)

`\OpenAPIValidation\PSR7\ValidatorBuilder` reads and compiles schema in memory as instance of `\cebe\openapi\spec\OpenApi`. Validators use this instance to perform validation logic. You can reuse this instance after the validation like this:

```
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getServerRequestValidator();
# or
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getResponseValidator();

/** @var \cebe\openapi\spec\OpenApi */
$openApi = $validator->getSchema();
```

### Request Message

[](#request-message-1)

`\Psr\Http\Message\RequestInterface` validation is not implemented.

### PSR-15 Middleware

[](#psr-15-middleware)

PSR-15 middleware can be used like this:

```
$yamlFile = 'api.yaml';
$jsonFile = 'api.json';

$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYamlFile($yamlFile)->getValidationMiddleware();
#or
$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYaml(file_get_contents($yamlFile))->getValidationMiddleware();
#or
$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJsonFile($jsonFile)->getValidationMiddleware();
#or
$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJson(file_get_contents($jsonFile))->getValidationMiddleware();
#or
$schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand
$validator = (new \OpenAPIValidation\PSR7\ValidationMiddlewareBuilder)->fromSchema($schema)->getValidationMiddleware();
```

### SlimFramework Middleware

[](#slimframework-middleware)

Slim framework uses slightly different middleware interface, so here is an adapter which you can use like this:

```
$yamlFile = 'api.yaml';
$jsonFile = 'api.json';

$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYamlFile($yamlFile)->getValidationMiddleware();
#or
$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYaml(file_get_contents($yamlFile))->getValidationMiddleware();
#or
$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJsonFile($jsonFile)->getValidationMiddleware();
#or
$psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJson(file_get_contents($jsonFile))->getValidationMiddleware();
#or
$schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand
$validator = (new \OpenAPIValidation\PSR7\ValidationMiddlewareBuilder)->fromSchema($schema)->getValidationMiddleware();

$slimMiddleware = new \OpenAPIValidation\PSR15\SlimAdapter($psr15Middleware);

/** @var \Slim\App $app */
$app->add($slimMiddleware);
```

### Caching Layer / PSR-6 Support

[](#caching-layer--psr-6-support)

PSR-7 Validator has a built-in caching layer (based on [PSR-6](https://www.php-fig.org/psr/psr-6/) interfaces) which saves time on parsing OpenAPI specs. It is optional. You enable caching if you pass a configured Cache Pool Object to the static constructor like this:

```
// Configure a PSR-6 Cache Pool
$cachePool = new ArrayCachePool();

// Pass it as a 2nd argument
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)
    ->fromYamlFile($yamlFile)
    ->setCache($cachePool)
    ->getResponseValidator();
# or
\OpenAPIValidation\PSR15\ValidationMiddleware::fromYamlFile($yamlFile, $cachePool);
```

You can use `->setCache($pool, $ttl)` call for both PSR-7 and PSR-15 builder in order to set [proper expiration ttl in seconds (or explicit `null`)](https://www.php-fig.org/psr/psr-6/#definitions)

If you want take control over the cache key for schema item, or your cache does not support cache key generation by itself you can `->overrideCacheKey('my_custom_key')` to ensure cache uses key you want.

### Standalone OpenAPI Validator

[](#standalone-openapi-validator)

The package contains a standalone validator which can validate any data against an OpenAPI schema like this:

```
$spec = resolveReferences(new ReferenceContext($spec, "/"));
$schema = new cebe\openapi\spec\Schema($spec->schema);

try {
    (new \OpenAPIValidation\Schema\SchemaValidator())->validate($data, $schema);
} catch(\OpenAPIValidation\Schema\Exception\KeywordMismatch $e) {
    // you can evaluate failure details
    // $e->keyword() == "enum"
    // $e->data() == "c"
    // $e->dataBreadCrumb()->buildChain() -- only for nested data
}
```

Custom Type Formats
-------------------

[](#custom-type-formats)

As you know, OpenAPI allows you to add formats to types:

```
schema:
  type: string
  format: binary
```

This package contains a bunch of built-in format validators:

- `string` type:
    - `byte`
    - `date`
    - `date-time`
    - `email`
    - `hostname`
    - `ipv4`
    - `ipv6`
    - `uri`
    - `uuid` (uuid4)
- `number` type
    - `float`
    - `double`

You can also add your own formats. Like this:

```
# A format validator must be a callable
# It must return bool value (true if format matched the data, false otherwise)

# A callable class:
$customFormat = new class()
{
    function __invoke($value): bool
    {
        return $value === "good value";
    }
};

# Or just a closure:
$customFormat = function ($value): bool {
    return $value === "good value";
};

# Register your callable like this before validating your data
\OpenAPIValidation\Schema\TypeFormats\FormatsContainer::registerFormat('string', 'custom', $customFormat);
```

Exceptions
----------

[](#exceptions)

The package throws a list of various exceptions which you can catch and handle. There are some of them:

- Schema related:
    - `\OpenAPIValidation\Schema\Exception\KeywordMismatch` - Indicates that data was not matched against a schema's keyword
        - `\OpenAPIValidation\Schema\Exception\TypeMismatch` - Validation for `type` keyword failed against a given data. For example `type:string` and value is `12`
        - `\OpenAPIValidation\Schema\Exception\FormatMismatch` - data mismatched a given type format. For example `type: string, format: email` won't match `not-email`.
- PSR7 Messages related:
    - `\OpenAPIValidation\PSR7\Exception\NoContentType` - HTTP message(request/response) contains no Content-Type header. General HTTP errors.
    - `\OpenAPIValidation\PSR7\Exception\NoPath` - path is not found in the spec
    - `\OpenAPIValidation\PSR7\Exception\NoOperation` - operation os not found in the path
    - `\OpenAPIValidation\PSR7\Exception\NoResponseCode` - response code not found under the operation in the spec
    - Validation exceptions (check parent exception for possible root causes):
        - `\OpenAPIValidation\PSR7\Exception\ValidationFailed` - generic exception for failed PSR-7 message
        - `\OpenAPIValidation\PSR7\Exception\Validation\InvalidBody` - body does not match schema
        - `\OpenAPIValidation\PSR7\Exception\Validation\InvalidCookies` - cookies does not match schema or missing required cookie
        - `\OpenAPIValidation\PSR7\Exception\Validation\InvalidHeaders` - header does not match schema or missing required header
        - `\OpenAPIValidation\PSR7\Exception\Validation\InvalidPath` - path does not match pattern or pattern values does not match schema
        - `\OpenAPIValidation\PSR7\Exception\Validation\InvalidQueryArgs` - query args does not match schema or missing required argument
        - `\OpenAPIValidation\PSR7\Exception\Validation\InvalidSecurity` - request does not match security schema or invalid security headers
    - Request related:
        - `\OpenAPIValidation\PSR7\Exception\MultipleOperationsMismatchForRequest` - request matched multiple operations in the spec, but validation failed for all of them.

Testing
-------

[](#testing)

You can run the tests with:

```
vendor/bin/phpunit

```

Contribution Guide
------------------

[](#contribution-guide)

Feel free to open an Issue or add a Pull request. There is a certain code style that this package follows: [doctrine/coding-standard](https://www.doctrine-project.org/projects/doctrine-coding-standard/en/latest/reference/index.html#introduction).

To conform to this style please use a git hook, shipped with this package at `.githooks/pre-commit`.

How to use it:

1. Clone the package locally and navigate to the folder
2. Create a symlink to the hook like this: `ln -s -f ../../.githooks/pre-commit .git/hooks/pre-commit`
3. Add execution rights: `chmod +x .git/hooks/pre-commit`
4. Now commit any new changes and the code will be checked and formatted accordingly.
5. If there are any issues with your code, check the log here: `.phpcs-report.txt`

Credits
-------

[](#credits)

People:

- [Dmitry Lezhnev](https://github.com/lezhnev74)
- [Carsten Brandt](https://github.com/cebe)
- [Samuel Nela](https://github.com/samnela)
- [Pavel Batanov](https://github.com/scaytrase)
- [Christopher L Bray](https://github.com/brayniverse)
- [David Pauli](https://github.com/dpauli)
- [Jason Judge](https://github.com/judgej)
- [Yannick Chenot](https://github.com/osteel)
- [TarasBK](https://github.com/TarasBK)
- [Jason B. Standing](https://github.com/jasonbstanding)
- [Dmytro Demchyna](https://github.com/dmytro-demchyna)
- [Will Chambers](https://github.com/willchambers99)
- [Ignacio](https://github.com/imefisto)
- A big thank you to [Henrik Karlström](https://github.com/hkarlstrom) who kind of inspired me to work on this package.

Resources:

- Icons made by Freepik, licensed by CC 3.0 BY
- [cebe/php-openapi](https://github.com/cebe/php-openapi) package for Reading OpenAPI files
- [slim3-psr15](https://github.com/bnf/slim3-psr15) package for Slim middleware adapter

License
-------

[](#license)

The MIT License (MIT). Please see `License.md` file for more information.

TODO
----

[](#todo)

- Support Discriminator Object (note: apparently, this is not so straightforward, as discriminator can point to any external scheme)

###  Health Score

37

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity39

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 88% 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 ~3 days

Total

38

Last Release

2451d ago

### Community

Maintainers

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

---

Top Contributors

[![lezhnev74](https://avatars.githubusercontent.com/u/10206110?v=4)](https://github.com/lezhnev74 "lezhnev74 (206 commits)")[![scaytrase](https://avatars.githubusercontent.com/u/6578413?v=4)](https://github.com/scaytrase "scaytrase (18 commits)")[![imefisto](https://avatars.githubusercontent.com/u/3299088?v=4)](https://github.com/imefisto "imefisto (2 commits)")[![brayniverse](https://avatars.githubusercontent.com/u/945367?v=4)](https://github.com/brayniverse "brayniverse (2 commits)")[![dmytro-demchyna](https://avatars.githubusercontent.com/u/1595810?v=4)](https://github.com/dmytro-demchyna "dmytro-demchyna (1 commits)")[![chtombleson](https://avatars.githubusercontent.com/u/276237?v=4)](https://github.com/chtombleson "chtombleson (1 commits)")[![cleptric](https://avatars.githubusercontent.com/u/6617432?v=4)](https://github.com/cleptric "cleptric (1 commits)")[![panvid](https://avatars.githubusercontent.com/u/10072693?v=4)](https://github.com/panvid "panvid (1 commits)")[![samnela](https://avatars.githubusercontent.com/u/1852108?v=4)](https://github.com/samnela "samnela (1 commits)")[![digilist](https://avatars.githubusercontent.com/u/833667?v=4)](https://github.com/digilist "digilist (1 commits)")

---

Tags

openapiopenapi3phppsr-7validationhttpvalidationopenapipsr7

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/lezhnev74-openapi-psr7-validator/health.svg)

```
[![Health](https://phpackages.com/badges/lezhnev74-openapi-psr7-validator/health.svg)](https://phpackages.com/packages/lezhnev74-openapi-psr7-validator)
```

###  Alternatives

[league/openapi-psr7-validator

Validate PSR-7 messages against OpenAPI (3.0.2) specifications expressed in YAML or JSON

55615.9M69](/packages/league-openapi-psr7-validator)[kevinrob/guzzle-cache-middleware

A HTTP/1.1 Cache for Guzzle 6. It's a simple Middleware to be added in the HandlerStack. (RFC 7234)

43117.4M104](/packages/kevinrob-guzzle-cache-middleware)[mezzio/mezzio-authentication-oauth2

OAuth2 (server) authentication middleware for Mezzio and PSR-7 applications.

28483.0k2](/packages/mezzio-mezzio-authentication-oauth2)[mezzio/mezzio-authentication

Authentication middleware for Mezzio and PSR-7 applications

121.6M26](/packages/mezzio-mezzio-authentication)[hkarlstrom/openapi-validation-middleware

PSR-7 and PSR-15 OpenAPI Validation Middleware

95198.8k1](/packages/hkarlstrom-openapi-validation-middleware)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)

PHPackages © 2026

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