Json Api Bundle Laravel Package

Getting Started

• This is a Symfony bundle, not a Laravel package. There is no service provider, facade, or vendor:publish. Day-to-day leverage assumes a Symfony 2.8/3.x app (the era of the last release, Feb 2017) with JMS Serializer installed. In a Laravel codebase you are looking at a port or a standalone JMS Serializer setup, not a drop-in.
• Minimal install:
  • composer require steffenbrem/json-api-bundle
  • Register in app/AppKernel.php: new SteffenBrem\JsonApiBundle\JsonApiBundle()
  • Ensure JMS\SerializerBundle\JMSSerializerBundle is registered and configured.
  • Add bundle config under its root key in config.yml (check DependencyInjection/Configuration.php for the exact key and options — the tree is small).
• Look first at, in order:
  1. src/DependencyInjection/Configuration.php — the real documented surface area.
  2. src/Resources/config/services.yml — service ids you will inject or override.
  3. src/Serializer/ (or equivalent) — the JMS visitor/handler that turns objects into JSON API documents.
  4. tests/ — the README is thin-to-nonexistent; tests are the de facto docs.
• First use case: return a JSON API document from a controller. Annotate an entity/POPO with JMS @Serializer\Type/@Groups, inject the bundle's serializer service (or JMS configured with the JSON API format), and return a response with Content-Type: application/vnd.api+json. Verify the shape (data, type, id, attributes) before wiring relationships.
• Sanity check the install with bin/console debug:container | grep -i json and bin/console debug:config <root_key> (Symfony 3.2+).

Implementation Patterns

• Controller-per-resource: keep document construction thin. Inject the serializer, pass the entity or collection, and let the bundle build the envelope. Wrap responses in a base JsonResponse subclass that sets application/vnd.api+json.
• JMS groups as your API contract: define @Groups({"api"}) on exposed fields and serialize with the api group. This separates persistence from representation and avoids leaking Doctrine internals.
• Relationships vs. compound documents: JSON API requires relationships, and optionally included plus links. JMS serializes nested objects, but the bundle is unlikely to automatically build the included array or links.related. Start with relationships-only for CRUD; add compound documents later via post-processing or a custom handler.
• Collections and pagination: serialize arrays as data: []. If the bundle exposes pagination config, use it; otherwise add links/meta in a response factory so pagination stays consistent across controllers.
• Request parsing: JSON API payloads are nested (data.attributes, data.relationships). Do not bind directly to form requests/entities. Write a small request-to-DTO mapper — most of your app-specific code lives here.
• Error documents: JSON API requires {"errors": [...]}. Add an exception listener or controller wrapper that maps validation/HTTP errors into that shape; Symfony's default exception output will violate the spec.
• Content negotiation: check Accept for application/vnd.api+json and return 406 for unsupported media types. A kernel event listener is a reasonable home for this.
• In a Laravel context: register JMS Serializer and the bundle's serializer service inside a small standalone container, or extract the serialization logic. Realistically, a Laravel dev would choose a JSON API package with a Laravel adapter rather than this bundle.

Gotchas and Tips

• Age and compatibility: last release 2017-02-08, targeting Symfony 2/3 and PHP 5.6/7.0. Symfony 4+ (Flex, autowiring defaults, removed bundle conventions) and PHP 8 will likely need forks. Pin symfony/*, jms/serializer-bundle, and php constraints, and test the exact versions before committing.
• Content-Type is not automatic: JSON API mandates application/vnd.api+json; Symfony's JsonResponse sends application/json. Set it in one base response class — scattered new JsonResponse() calls are the most common compliance bug.
• JMS serialization is not JSON API: JMS produces attribute-shaped JSON, not data/type/id/attributes. The bundle bridges simple cases, but included, links, meta, sparse fieldsets (fields[type]), sorting, and pagination params are usually not covered. Budget for a response layer.
• Sparse fieldsets and includes: if the bundle does not implement ?include=/?fields=, clients get more than requested. Filter the serialized array against query params before returning.
• Circular references and lazy loading: bidirectional Doctrine relations plus JMS groups can cause recursion or N+1 queries when relationships serialize. Use @MaxDepth, explicit groups, and query joins/eager fetching where relationships are exposed.
• Config quirks: bundle config lives under a root key. In Symfony 3, config is cached — run bin/console cache:clear after YAML edits; silent staleness in dev is common.
• Debugging: debug:container <service> to find the serializer service id; debug:config for the config tree; a small fixture serialization test to see output without HTTP. Because docs are sparse, the repo's tests are the best reference.
• Overriding: services are defined in Resources/config/services.yml. Prefer compiler passes or service decoration over editing vendor files; the bundle is small enough that copying its serializer/handler into your app is a pragmatic escape hatch when the 2017 code does not fit.
• Abandonment risk: 53 stars, 0 dependents, no release in years. Treat it as a reference implementation or a starting point you own, not a maintained dependency. For new work, evaluate actively maintained JSON API implementations (or hand-rolled serializers).