Download the PHP package dbstudios/php-api-common without Composer

This package contains components that tend to be useful across different REST API projects.

This package is broken up into several parts:

• Common code, files that are always useful.
• Validation code, files that are useful in tandem with the symfony/validator component.
• Doctrine Query Document code, files that are useful in tandem with the dbstudios/doctrine-query-document library.
• Lexik JWT code, files that are useful in tandem with the lexik/jwt-authentication-bundle bundle.
• Payload code, files that are useful in tandem with the symfony/serializer component's deserialize functionality.

Common

Common files include the ResponderInterface and it's implementations, as well as the classes in the top level of the src/Error/Errors directory.

Working with responders is pretty straightforward.

The above code returns a Response object containing the following JSON.

Responders can also be used to simplify error handling, and to normalize error response formats.

The above code returns a Response object containing the following JSON.

For Symfony projects, you can use DaybreakStudios\RestApiCommon\ResponderService instead, which takes a responder and the request stack, allowing you to omit the format argument in calls to ::createResponse() and createErrorResponse().

Validation

The validation component adds an extra API error class, which will normalize constraint violation errors from the symfony/validator component, allowing them to nicely returned as an API error.

The above code returns a Response object containing approximately the following JSON.

Doctrine Query Document

The Doctrine query document component adds 4 new API error classes. Since they're relatively simple, please refer to the individual class documentation.

Lexik JWT

The Lexik JWT component adds a special event subscriber that will transform the very generic error messages emitted by the lexik/jwt-authentication-bundle into messages that can be displayed directly to the end-user.

To register the subscriber in a Symfony application, be sure to add the kernel.event_subscriber tag to the service!

Payload

The payload component adds a simple framework for parsing API payloads into Data Transfer Object (DTO) classes. While useful by itself, giving you a more concrete set of fields on the objects your API consumes, it is most useful when also paired with the symfony/validator package, giving you a clean way to validate input to your API. By default, assertions tagged with the "create" group will only be run when DecoderIntent::CREATE is passed to the parse() method, while assertions tagged with the "update" method will be run when DecoderIntent::UPDATE is passed. Assertions in the "Default" group will always run. For example:

In the above example, the final line's call to SymfonyDeserializeDecoder::parse() would result in an ApiErrorException, whose error field would be a ValidationFailedError, since the input payload did not pass validation (the email address was not a valid email address).

If you're using PHP 8, you can use the PayloadTrait in your DTO class to gain access to the exists() and unset() utility methods. Since PHP 8 introduces the mixed psuedo-type, you can use it as the actual type for the properties on your DTO class. By doing so, you can use the exists() method, which uses \ReflectionProperty::isInitialized() to determine if a property was actually part of the input payload, and not just defaulting to null because the key was not included. This is useful when you have a property that might be part of the payload, but whose value could be null (since isset() would still return false when used on such a property). Since exists() uses reflection, results are cached to mitigate performance hits due to repeated calls for the same property. Do not call unset() directly on any property of a DTO class that you might need to call exists() on; instead, use PayloadTrait::unset() to unset the property and clear it from the exists() cache.