PHPackages                             somnambulist/api-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. somnambulist/api-bundle

ActiveSymfony-bundle[API Development](/categories/api)

somnambulist/api-bundle
=======================

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

6.1.2(1y ago)34.9k11MITPHPPHP ^8.1CI passing

Since Oct 21Pushed 2w ago3 watchersCompare

[ Source](https://github.com/somnambulist-tech/api-bundle)[ Packagist](https://packagist.org/packages/somnambulist/api-bundle)[ RSS](/packages/somnambulist-api-bundle/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (21)Versions (65)Used By (1)

Somnambulist API Bundle
=======================

[](#somnambulist-api-bundle)

[![GitHub Actions Build Status](https://camo.githubusercontent.com/0388d74d9f528a8528af02675d694d95f5779400d163839c25be08f82cb5d42f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f736f6d6e616d62756c6973742d746563682f6170692d62756e646c652f74657374732e796d6c3f6c6f676f3d676974687562266272616e63683d6d6173746572)](https://github.com/somnambulist-tech/api-bundle/actions?query=workflow%3Atests)[![Issues](https://camo.githubusercontent.com/4854b4799a6af105240086b196b356054a77d71fa86ebd71998d37846ce1d6c5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f736f6d6e616d62756c6973742d746563682f6170692d62756e646c653f6c6f676f3d676974687562)](https://github.com/somnambulist-tech/api-bundle/issues)[![License](https://camo.githubusercontent.com/e5a5f2e17f8541783ddb63fda73fe81f7e853c194d26d8691e0438a26f44235f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f736f6d6e616d62756c6973742d746563682f6170692d62756e646c653f6c6f676f3d676974687562)](https://github.com/somnambulist-tech/api-bundle/blob/master/LICENSE)[![PHP Version](https://camo.githubusercontent.com/8f573e0c5af978cdd463580fa1b532e0354fce35712da09e8914beca29c924e5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f736f6d6e616d62756c6973742f6170692d62756e646c653f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://packagist.org/packages/somnambulist/api-bundle)[![Current Version](https://camo.githubusercontent.com/b7bffc7f0507bcf3fa13c2e9c0b2abdff61d85fe8b3059c61680b5f66f1b40dd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736f6d6e616d62756c6973742f6170692d62756e646c653f6c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465)](https://packagist.org/packages/somnambulist/api-bundle)

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

Requirements
------------

[](#requirements)

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

Installation
------------

[](#installation)

Install using composer, or checkout / pull the files from github.com.

- composer require somnambulist/api-bundle

Usage
-----

[](#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](docs/api_controller.md) and build your API.

Optionally you can:

- [learn more about the API Controller](docs/api_controller.md)
- [learn how to transform responses to JSON](docs/transforming_responses.md)
- [learn how to document your API](docs/api_documentor.md)
- [configure controller argument resolvers](docs/argument_resolvers.md)
- [configure event subscribers](docs/event_subscribers.md)

### BC Breaks in V5

[](#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

[](#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

[](#package-change-in-v350)

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

[](#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

[](#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

[](#tests)

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

Links
-----

[](#links)

- [Fractal Bundle](https://github.com/somnambulist-tech/fractal-bundle)
- [Form Request Bundle](https://github.com/somnambulist-tech/form-request-bundle)
- [The PHP League Fractal Docs](https://fractal.thephpleague.com/)
- [Dingo API](https://github.com/dingo/api)

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance70

Regular maintenance activity

Popularity21

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity81

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 97.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~29 days

Recently: every ~68 days

Total

64

Last Release

579d ago

Major Versions

1.7.5 → 2.0.02020-08-27

2.0.0 → 3.0.02021-01-21

3.8.0 → 4.0.02022-03-21

4.3.2 → 5.0.02023-01-22

5.x-dev → 6.0.02024-03-02

PHP version history (4 changes)1.0.0PHP >=7.2

2.0.0PHP >=7.4

3.3.0PHP ^8.0

5.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/c0e439bf91b68c2e81e0250c752d3a552e78752c91acdf00c72a1f93aeb1ceca?d=identicon)[dredfern](/maintainers/dredfern)

---

Top Contributors

[![dave-redfern](https://avatars.githubusercontent.com/u/1477147?v=4)](https://github.com/dave-redfern "dave-redfern (100 commits)")[![jasonhofer](https://avatars.githubusercontent.com/u/974242?v=4)](https://github.com/jasonhofer "jasonhofer (3 commits)")

---

Tags

api-servicejson-responsephpsymfony-bundlejsonapisymfonybundlefractal

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/somnambulist-api-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/somnambulist-api-bundle/health.svg)](https://phpackages.com/packages/somnambulist-api-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M737](/packages/sylius-sylius)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M574](/packages/shopware-core)[web-auth/webauthn-framework

FIDO2/Webauthn library for PHP and Symfony Bundle.

515100.5k3](/packages/web-auth-webauthn-framework)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1189.8k](/packages/rcsofttech-audit-trail-bundle)[stfalcon-studio/api-bundle

Base classes and helper services to build API application via Symfony.

1035.6k](/packages/stfalcon-studio-api-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)