somnambulist / api-bundle
Adds infrastructure for creating an API with documentation, response handling, and more.
Installs: 4 734
Dependents: 1
Suggesters: 0
Security: 0
Stars: 3
Watchers: 4
Forks: 1
Open Issues: 0
Type:symfony-bundle
Requires
- php: ^8.1
- ext-json: *
- psr/log: ^1|^2|^3
- ramsey/uuid: ^4.0
- somnambulist/form-request-bundle: ^2.0
- somnambulist/fractal-bundle: ^2.0
- symfony/framework-bundle: ^6.4|^7.0
Requires (Dev)
- doctrine/collections: ~1.8
- monolog/monolog: ^3.4
- pagerfanta/pagerfanta: ^3.8
- phpunit/phpunit: ^10.5
- somnambulist/api-client: ^4.0.0
- somnambulist/domain: ^6.0.0
- somnambulist/read-models: ^4.0
- symfony/browser-kit: ^6.4|^7.0
- symfony/messenger: ^6.4|^7.0
- symfony/monolog-bundle: ~3.5
- symfony/phpunit-bridge: ^6.4|^7.0
- symfony/serializer: ^6.4|^7.0
- symfony/stopwatch: ^6.4|^7.0
- symfony/twig-bundle: ^6.4|^7.0
- symfony/var-dumper: ^6.4|^7.0
- symfony/yaml: ^6.4|^7.0
Suggests
- pagerfanta/pagerfanta: Pagination support expects Pagerfanta collections
- symfony/stopwatch: Add profiling data from using fractal
- symfony/twig-bundle: Required to use OpenAPI documentation generator
- dev-master
- 6.1.2
- 6.1.1
- 6.1.0
- 6.0.1
- 6.0.0
- 5.x-dev
- 5.2.3
- 5.2.2
- 5.2.1
- 5.2.0
- 5.1.0
- 5.0.1
- 5.0.0
- 4.3.2
- 4.3.1
- 4.3.0
- 4.2.0
- 4.1.1
- 4.1.0
- 4.0.1
- 4.0.0
- 3.8.0
- 3.7.2
- 3.7.1
- 3.7.0
- 3.6.0
- 3.5.0
- 3.4.4
- 3.4.3
- 3.4.2
- 3.4.1
- 3.4.0
- 3.3.7
- 3.3.6
- 3.3.5
- 3.3.4
- 3.3.3
- 3.3.2
- 3.3.1
- 3.3.0
- 3.2.0
- 3.1.0
- 3.0.2
- 3.0.1
- 3.0.0
- 2.0.0
- 1.7.5
- 1.7.4
- 1.7.3
- 1.7.2
- 1.7.1
- 1.7.0
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.0
- 1.4.0
- 1.3.0
- 1.2.0
- 1.1.0
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
This package is auto-updated.
Last update: 2024-12-01 16:23:13 UTC
README
Provides several helpers and support objects for better handling League Fractal with Symfony. The integration with Fractal is based on Dingo API for Laravel: https://github.com/dingo/api
Requirements
- PHP 8.1+
- somnambulist/fractal-bundle
- symfony/twig-bundle (for documentation output)
Installation
Install using composer, or checkout / pull the files from github.com.
- composer require somnambulist/api-bundle
Usage
Add the SomnambulistApiBundle
to your bundles.php
list and add a config file in packages
if you wish to configure the bundle. The following options can be set:
somnambulist_api: exception_handler: converters: Assert\InvalidArgumentException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\AssertionExceptionConverter Assert\LazyAssertionException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\LazyAssertionExceptionConverter Doctrine\ORM\EntityNotFoundException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\EntityNotFoundConverter Doctrine\ORM\NoResultException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\EntityNotFoundConverter Somnambulist\Components\Models\Exceptions\EntityNotFoundException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\EntityNotFoundConverter Somnambulist\Components\ReadModels\Exceptions\EntityNotFoundException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\EntityNotFoundConverter Somnambulist\Components\ReadModels\Exceptions\NoResultsException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\EntityNotFoundConverter Symfony\Component\Messenger\Exception\HandlerFailedException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\HandlerFailedExceptionConverter api_root: '/api' doc_root: '/api/docs' subscribers: exception_to_json: true json_to_post: true request_id: true openapi: path: '%kernel.project_dir%/config/openapi' title: 'API Docs' version: '1.0.0' description: 'The documentation for the API' cache_time: 1400 # cache time in seconds for the generated docs tags: tag_name: "Description for the tag"
Extend the bundled ApiController and build your API.
Optionally you can:
- learn more about the API Controller
- learn how to transform responses to JSON
- learn how to document your API
- configure controller argument resolvers
- configure event subscribers
BC Breaks in V5
V5 drops all previously deprecated methods and makes changes to the signatures of the transformer types. Transformer types are now readonly and cannot be modified once instantiated. This means that the constructor args have changed to include all options and the order has been revised.
All response types default to a data
key name, including ObjectType
that previously was null. Now, you
must specify a null key to remove it. Using a data
key allows for applying metadata more easily to the
response object.
BC Breaks in V4
V4 updates to league/fractal 0.20.0. This adds many type hints to properties and methods. Specifically
in TransformerAbstract
, the various overridable arrays now require the array
type hint.
In addition:
- removed
RequestArgumentHelper
use FormRequests instead as they provide a cleaner, self-documenting API - removed the configuration for the arg helper from the bundle config
- removed
withXXX
fromResponse\AbstractType
, usekey
,meta
, andinclude
instead - the
AbstractType::include()
method now only accepts multiple string arguments - the request id header string is now set via a parameter (see docs)
Package change in V3.5.0
From 3.5.0 samj/fractal-bundle
has been replaced with somnambulist/fractal-bundle
as samj has been
abandoned and archived. The replacement provides the same service resolution and allows transformers to
be tagged as well as auto-configured.
The only code change necessary is to replace SamjFractalBundle
in bundles.php with SomnambulistFractalBundle
.
BC Breaks in V3
From v3.0.0 the library has been re-namespaced to Somanmbulist\Bundles\ApiBundle
. Be sure to update
any references.
In addition:
ReadModelTransformer
now requires somnambulist/read-models 2.0+UuidValueResolver
andExternalIdentityValueResolver
now require somnambulist/domain 4.0+
BC Breaks in v2
From v2.0.0 the following changes have been made:
- use PHP 7.4 features through-out the library
- removed
Services
namespace component Converters
namespace was changed toExceptionConverters
Transformers
andExceptionConverters
are now part of theResponse
namespaceTransformerBinding
has been removed in favour ofTypes
with specific interfacesApiController
methodspaginate
,collection
,item
are now strictly typedwithIncludes
method accepts multiple string arguments instead of an array- all transformers should be registered as container services (transformer is now a string explicitly)
To switch from TransformerBinding
replace each call to:
TransformerBinding::item()
withnew ObjectType()
TransformerBinding::collection()
withnew CollectionType()
ornew IterableType()
TransformerBinding::paginate()
withnew PagerfantaType()
for Pagerfanta.
The constructor signatures are largely the same; except collection and pagerfanta have an
additional key
as the last argument, defaulted to data
.
When updating, remember to update the exception converters in your somnambulist.yaml config file if using the included defaults.
Tests
PHPUnit 9+ is used for testing. Run tests via vendor/bin/phpunit
.