Download the PHP package kleijnweb/php-api-descriptions without Composer

This project is no longer maintained

KleijnWeb\PhpApi\Descriptions

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

Supported formats:

• OpenAPI 2.0 (FKA Swagger)

Limited:

• RAML 1.0^*

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

Validating Requests And Responses

Namespaces omitted for brevity:

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

(De-)Hydration

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.

DateTime

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

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
3. ISO8601

NOTE: Formats not starting with Y-m-d do not work with Schema::FORMAT_DATE nor AnyProcessor.

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.

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

If you want OpenAPI support in combination with Symfony, you should check out SwaggerBundle.

And there's PSR-7/PSR-15 Middleware, which behaves pretty much the same but is much more reusable.

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

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

KleijnWeb\PhpApi\Descriptions is made available under the terms of the LGPL, version 3.0.