Json Api Server Bundle Laravel Package

Getting Started

Reality check first: this is a Symfony bundle, not a Laravel package. There is no service provider, no config publish tag, and no Illuminate integration. A Laravel developer cannot composer require this into a Laravel app and get value — the bundle's entire payload is Symfony glue (bundle registration, YAML routing import, DI container tag collection, route-name-prefix-aware exception handling). Treat this package as (a) a reference implementation for how a JSON:API server is wired into a framework, or (b) an install target only if the target service is Symfony.

If you are actually on Symfony (the only path where this runs day-to-day):

1. composer require enm/json-api-server-bundle
2. Register the bundle in config/bundles.php:

   Enm\Bundle\JsonApi\Server\EnmJsonApiServerBundle::class => ['all' => true],
   

3. Import the shipped routes in config/routes.yaml:

   json_api:
     resource: "@EnmJsonApiServerBundle/Resources/config/routing.xml"
   

4. Optionally create config/packages/enm_json_api_server.yaml with debug, url_prefix, and route_name_prefix (all optional).
5. Register at least one request handler as a service tagged json_api_server.request_handler with a type matching the JSON:API resource type it serves.

Where to look first: read the core library docs (enm/json-api-server on GitHub Pages) before the bundle README. The bundle just wires that library in; the request-handler contract, resource model, and error semantics live upstream.

First use case: a single read-only resource type end-to-end — GET /{type} and GET /{type}/{id} for, say, articles — to confirm routing, handler discovery, and error formatting all work before adding relationships or writes.

Implementation Patterns

One handler per resource type, registered via DI tag.

App\RequestHandler\ArticleRequestHandler:
    tags:
      - { name: json_api_server.request_handler, type: 'articles' }

The type attribute is the JSON:API resource type string — it must match exactly what clients send in URLs and what appears in data.type. The bundle collects tagged services into a handler map keyed by that string.

Thin controller, fat handler. All HTTP verbs are dispatched through the single jsonApiAction (introduced in 2.0.0). Your handler is the natural place for query building, authorization checks, and mapping domain objects to JSON:API resources. Avoid putting business logic in controllers — there is exactly one controller and it's the bundle's.

Prefix everything or nothing, atomically. If you front the API with /api, set both url_prefix: '/api' and route_name_prefix: 'enm.json_api' to whatever your route YAML actually uses. These two settings are coupled: url_prefix is about URL matching, route_name_prefix is about the exception handler locating the generated link URLs correctly. They drift out of sync silently and produce wrong links.self values in error responses.

Lean on the automatic error handling. The bundle catches exceptions from request handlers and serializes them as JSON:API error objects. Standardize your domain exceptions (not-found → 404 error object, validation → 422 with source.pointer, etc.) rather than hand-building error responses. This is the single biggest day-to-day time saver and the part most worth studying even in a Laravel context.

Read patterns as a design reference for Laravel. If you land on "build our own JSON:API layer for Laravel," the shape this package encodes is reusable:

• Resource-type → handler lookup map (in Laravel: a tagged/registered service keyed by type).
• Central exception → JSON:API error object converter (Laravel: an exception handler branch or a dedicated middleware).
• Route table covering all ten standard endpoint shapes, generated per type (Laravel: a route macro that expands {type} endpoints).
• Handler contract that receives a parsed request and returns a resource/collection, with serialization (sparse fieldsets, includes, pagination) delegated to a serializer layer.

The parts you don't port are the Symfony-specific ones: bundle class, services YAML, ResourceProviderPass removal remnants, and the symfony/psr-http-message-bridge wiring behind the decorator.

Integration tip — vendor it. If you genuinely adopt this on Symfony, forked as a VCS/path repository, with an internal tag, not pulled fresh from Packagist. Put the JSON:API layer behind an internal interface (e.g. a DocumentBuilder or your own RequestHandlerInterface) so the vendor code is swappable when you migrate.

Gotchas and Tips

• Archived, last release 2018-09-27. No maintainer, no CVE response, no advisories, 10 stars, 0 dependents. Assume you own every bug you hit. Budget for a fork.
• PHP/Symfony version cliff. This is a Symfony 3.4/4.x-era artifact with PHP 7.x constraints. Expect friction on PHP 8.1/8.2 and Symfony 6/7 (deprecations, return types, container API changes). If you can't pin the matrix to a known-good combination, walk away.
• type mismatch is a silent failure. If the tag's type doesn't match the URL segment, the handler isn't found and you'll get an empty/404 rather than a useful message. Check the compiled container (debug:container --tag=json_api_server.request_handler) when a handler "doesn't fire."
• url_prefix / route_name_prefix drift. Both are needed when you prefix routes; forgetting route_name_prefix breaks the exception handler's ability to generate correct URLs in error documents. Verify by triggering an error (e.g. request a nonexistent id) and inspecting links.
• The bundle owns the controller. You cannot inject per-endpoint behavior by adding controller methods — 2.0.0 consolidated everything into jsonApiAction. All behavior goes through the handler or through service decoration.
• Read the core library docs, not just the bundle README. Handler contract, resource model, and pagination semantics (the old pagination.limit config was removed in 3.0.0) are all upstream. Bundle docs are thin on purpose.
• No community knowledge base. 10 stars / 0 dependents means zero Stack Overflow, zero blog posts, zero hiring pool. Your debugging loop is source-reading plus the upstream tests.
• Extension points, ranked by usefulness: (1) the json_api_server.request_handler tag for per-type behavior — cheap and safe; (2) a decorator on the bundle's controller/handler services — viable but private services limit what you can reach (most services were made private in 2.0.0); (3) fork and patch — the realistic long-term path.
• Spec drift. Implements JSON:API ~1.0-era semantics. 1.1 (2022) is not covered. If clients assume 1.1 features, you'll be patching spec-level behavior yourself.
• For Laravel specifically: the productive use is as a specification checklist — enumerate every endpoint, relationship, sparse-fieldset, include, pagination and error-object requirement this package handles, then confirm your chosen Laravel JSON:API package (or your own serializer) covers each. That mapping is more valuable than any attempt to port the bundle's code.