PHPackages                             kleijnweb/php-api-descriptions - 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. kleijnweb/php-api-descriptions

AbandonedArchivedLibrary[API Development](/categories/api)

kleijnweb/php-api-descriptions
==============================

A PHP library for creating "contract-first" API applications.

v1.0.0-alpha5(8y ago)57.4k4[18 issues](https://github.com/kleijnweb/php-api-descriptions/issues)[1 PRs](https://github.com/kleijnweb/php-api-descriptions/pulls)3LGPL-3.0PHPPHP ^7.0.0

Since Aug 7Pushed 2y ago1 watchersCompare

[ Source](https://github.com/kleijnweb/php-api-descriptions)[ Packagist](https://packagist.org/packages/kleijnweb/php-api-descriptions)[ RSS](/packages/kleijnweb-php-api-descriptions/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (7)Versions (6)Used By (3)

This project is no longer maintained
====================================

[](#this-project-is-no-longer-maintained)

KleijnWeb\\PhpApi\\Descriptions
===============================

[](#kleijnwebphpapidescriptions)

[![Build Status](https://camo.githubusercontent.com/4e6339f2eaf472427f5c27d582bae6168871bb4d28d6bf6472749d9e42fe23c2/68747470733a2f2f7472617669732d63692e6f72672f6b6c65696a6e7765622f7068702d6170692d6465736372697074696f6e732e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/kleijnweb/php-api-descriptions)[![Coverage Status](https://camo.githubusercontent.com/a524bfa0cbc45cdd7658562d6ce37d169b34d7b6a5917cdfcbe47079465ebf15/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6b6c65696a6e7765622f7068702d6170692d6465736372697074696f6e732f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/kleijnweb/php-api-descriptions?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/cbb5e62a9768dccd1b4822832064277c7e0dae0f26ecc324070e105ae44918a4/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6b6c65696a6e7765622f7068702d6170692d6465736372697074696f6e732f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/kleijnweb/php-api-descriptions/?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/d1268ebc6ec2d2e2620f65d6a3b35a1509fc934fb35c4b1a92d87f88164b10de/68747470733a2f2f706f7365722e707567782e6f72672f6b6c65696a6e7765622f7068702d6170692d6465736372697074696f6e732f762f737461626c65)](https://packagist.org/packages/kleijnweb/php-api-descriptions)

A PHP library for creating "contract-first" API applications.

Supported formats:

- [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (FKA *Swagger*)

Limited:

- [RAML 1.0](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/)\*

\* *RAML is much more feature-rich and generally elaborate standard than OpenAPI, it will take some time to support the full set. Help is appreciated.*

The aim is to provide full support and interchangeability.

Typical Usage
=============

[](#typical-usage)

Validating Requests And Responses
---------------------------------

[](#validating-requests-and-responses)

Namespaces omitted for brevity:

```
$validator = new MessageValidator(
  (new Repository('some/path'))->get('some-service/v1.0.1/swagger.yml')
);
/** @var ServerRequestInterface $request */
$result = $validator->validateRequest($request, $path);

/** @var ResponseInterface $response */
$result = $validator->validateResponse($body, $request, $response, $path);
```

If you're feeling frisky and want to try RAML support:

```
$validator = new MessageValidator(
    (new Repository())
        ->setFactory(new DescriptionFactory(DescriptionFactory::BUILDER_RAML))
        ->get('tests/definitions/raml/mobile-order-api/api.raml')
);
```

(De-)Hydration
==============

[](#de-hydration)

```
// $input is deserialized and validated using $inputSchema

$builder   = new ProcessorBuilder(new ClassNameResolver(['Some\Namespace']));
$processor = $builder->build($schema);
$hydrated  = $processor->hydrate($input, $inputSchema);

// Perform business logic, creating $appOutput

$output = $processor->dehydrate($appOutput, $outputSchema);

// Validate output using $outputSchema
```

### NULLs, Undefined And Defaults

[](#nulls-undefined-and-defaults)

The processor will assume hydration input is pre-validated. This implies that when an input object contains a property with a NULL value, it will leave it as is, and it may be casted to something other than NULL if the input is invalid (otherwise it will be "hydrated" by `NullProcessor`). When dehydrating, the processors will intentionally *not* try to force validity of anything that may have been set to an invalid value by application processing.

The implied flow is thus: `input > deserialization > validation > hydration > business logic > dehydration [> validation] > serialization > output` .

When adhering to this flow, the behavior should be intuitive. There is a separate document detailing the implementation [here](NULLS.md).

### DateTime

[](#datetime)

The expected in- and output format can be tweaked by configuring the DateTimeProcessor factory with a custom instance of `DateTimeSerializer` (via the builder):

```
$builder = new ProcessorBuilder($classNameResolver, new DateTimeSerializer(\DateTime::RFC850));
```

By default output is formatted as 'Y-m-d\\TH:i:s.uP' (RFC3339 with microseconds). When passed, the first constructor argument will be used instead. Input parsing is attempted as follows:

1. Arguments to the constructor
2. RFC3339 with decreasing precision:
1. RFC3339 with microseconds
2. RFC3339 with milliseconds
3. RFC3339

4. ISO8601

**NOTE**: Formats not starting with `Y-m-d` do not work with Schema::FORMAT\_DATE nor `AnyProcessor`.

### Custom Processors

[](#custom-processors)

Class name resolution and DateTime handling can be tweaked by injecting custom instances into the builder, but pretty much all parts of the hydration and dehydration processes are customizable. You can inject custom processors by injecting factories for them into the "processor factory queue". All of the processors and their factories are open for extension. Use cases include:

- Loading objects from a data store
- Maintaining identity of objects that occur more than once in a structure
- Custom typed object hydration (eg. using constructors, setters)
- Custom object creation per type
- Issuing domain events on object creation
- Coercing scalar values (eg. interpreting 'false' as FALSE)
- Pretty much anything else you can think of

Some examples can be found [here](EXAMPLES.md).

### Performance Expectations

[](#performance-expectations)

On my old Xeon W3570, both hydration and deydration of a an array of 1000 realistic objects (nested objects, arrays) takes about 100ms; on average a little short of 1ms per root object.

Integration
===========

[](#integration)

If you want OpenAPI support in combination with Symfony, you should check out [SwaggerBundle](https://github.com/kleijnweb/swagger-bundle).

And there's [PSR-7/PSR-15 Middleware](https://github.com/kleijnweb/php-api-middleware), which behaves pretty much the same but is much more reusable.

Limitations
-----------

[](#limitations)

- Very limited RAML support
- Does not work with form data
- Requires a router to determine the matching path
- If the request has a body, it will have to be deserialized using objects, not as an associative array
- Requires the response body to be passed unserialized
- Response validation does not validate headers and content-types (yet)

Contributing
============

[](#contributing)

Pull requests are *very* welcome, but the code has to be PSR2 compliant, follow used conventions concerning parameter and return type declarations, and the coverage can not go down.

License
-------

[](#license)

KleijnWeb\\PhpApi\\Descriptions is made available under the terms of the [LGPL, version 3.0](https://spdx.org/licenses/LGPL-3.0.html#licenseText).

###  Health Score

25

—

LowBetter than 36% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity27

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 90.2% 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 ~126 days

Total

5

Last Release

3104d ago

### Community

Maintainers

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

---

Top Contributors

[![johnknl](https://avatars.githubusercontent.com/u/8375560?v=4)](https://github.com/johnknl "johnknl (46 commits)")[![RonRademaker](https://avatars.githubusercontent.com/u/2697738?v=4)](https://github.com/RonRademaker "RonRademaker (5 commits)")

---

Tags

swaggeropenapi

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kleijnweb-php-api-descriptions/health.svg)

```
[![Health](https://phpackages.com/badges/kleijnweb-php-api-descriptions/health.svg)](https://phpackages.com/packages/kleijnweb-php-api-descriptions)
```

###  Alternatives

[darkaonline/l5-swagger

OpenApi or Swagger integration to Laravel

2.9k36.4M126](/packages/darkaonline-l5-swagger)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.8M712](/packages/sylius-sylius)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[darkaonline/swagger-lume

OpenApi or Swagger integration to Lumen

3322.4M3](/packages/darkaonline-swagger-lume)[paycore/openfintech-data

Openfintech data

22010.0k](/packages/paycore-openfintech-data)

PHPackages © 2026

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