API Bundle.

Add simple API request/response handling for a Symfony API, recommended for micro-services / internal services.

Article image for: API Bundle

Introduction.

Introduction
Controller, Transformer and Request Helper
Event Subscribers
Controller Argument Resolvers

Github Print

Somnambulist API Bundle

GitHub Actions Build Status

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.0+
  • samj/fractal-bundle

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
    request_handler:
        per_page: 20
        max_per_page: 100
        limit: 100
        request_id_header: 'X-Request-Id'
    subscribers:
        exception_to_json: true
        json_to_post: true
        request_id: true

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 and ExternalIdentityValueResolver 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 to ExceptionConverters
  • Transformers and ExceptionConverters are now part of the Response namespace
  • TransformerBinding has been removed in favour of Types with specific interfaces
  • ApiController methods paginate, collection, item are now strictly typed
  • withIncludes 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() with new ObjectType()
  • TransformerBinding::collection() with new CollectionType() or new IterableType()
  • TransformerBinding::paginate() with new 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.

Links