Adds infrastructure for creating an API with documentation, response handling, and more.

Installs: 3 471

Dependents: 1

Suggesters: 0

Security: 0

Stars: 3

Watchers: 4

Forks: 1

Open Issues: 0


4.3.2 2022-08-08 19:59 UTC


GitHub Actions Build Status Issues License PHP Version Current Version

Provides several helpers and support objects for better handling League Fractal with Symfony. The integration with Fractal is based on Dingo API for Laravel:


  • PHP 8.0+
  • somnambulist/fractal-bundle
  • symfony/twig-bundle (for documentation output)


Install using composer, or checkout / pull the files from

  • composer require somnambulist/api-bundle


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:

         Assert\InvalidArgumentException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\AssertionExceptionConverter
         Assert\LazyAssertionException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\LazyAssertionExceptionConverter
         Symfony\Component\Messenger\Exception\HandlerFailedException: Somnambulist\Bundles\ApiBundle\Response\ExceptionConverters\HandlerFailedExceptionConverter
      exception_to_json: true
      json_to_post: true
      request_id: true
      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
          tag_name: "Description for the tag"

Extend the bundled ApiController and build your API.

Optionally you can:

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 from Response\AbstractType, use key, meta, and include 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 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.


PHPUnit 9+ is used for testing. Run tests via vendor/bin/phpunit.