This project is no longer maintained
KleijnWeb\PhpApi\Descriptions
, (*1)
A PHP library for creating "contract-first" API applications., (*2)
Supported formats:, (*3)
Limited:, (*4)
*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., (*5)
The aim is to provide full support and interchangeability., (*6)
Typical Usage
Validating Requests And Responses
Namespaces omitted for brevity:, (*7)
$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:, (*8)
$validator = new MessageValidator(
(new Repository())
->setFactory(new DescriptionFactory(DescriptionFactory::BUILDER_RAML))
->get('tests/definitions/raml/mobile-order-api/api.raml')
);
(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
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., (*9)
The implied flow is thus: input > deserialization > validation > hydration > business logic > dehydration [> validation] > serialization > output ., (*10)
When adhering to this flow, the behavior should be intuitive. There is a separate document detailing the implementation here., (*11)
DateTime
The expected in- and output format can be tweaked by configuring the DateTimeProcessor factory with a custom instance of DateTimeSerializer (via the builder):, (*12)
php
$builder = new ProcessorBuilder($classNameResolver, new DateTimeSerializer(\DateTime::RFC850));, (*13)
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:, (*14)
- Arguments to the constructor
- RFC3339 with decreasing precision:
- RFC3339 with microseconds
- RFC3339 with milliseconds
- RFC3339
- ISO8601
NOTE: Formats not starting with Y-m-d do not work with Schema::FORMAT_DATE nor AnyProcessor., (*15)
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:, (*16)
- 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., (*17)
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., (*18)
Integration
If you want OpenAPI support in combination with Symfony, you should check out SwaggerBundle., (*19)
And there's PSR-7/PSR-15 Middleware, which behaves pretty much the same but is much more reusable., (*20)
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., (*21)
License
KleijnWeb\PhpApi\Descriptions is made available under the terms of the LGPL, version 3.0., (*22)
Wallogit.com
