haddowg/json-api-symfony

Symfony bundle for haddowg/json-api: idiomatic routing, content negotiation, validation, and a Doctrine data layer for spec-compliant JSON:API 1.1 endpoints.

v1.0.0 2026-07-13 09:18 UTC

Requires

• php: ^8.3
• haddowg/json-api: ^1.0
• nyholm/psr7: ^1.8
• psr/http-factory: ^1.0
• psr/http-message: ^2.0
• symfony/config: ^6.4 || ^7.0 || ^8.0
• symfony/console: ^6.4 || ^7.0 || ^8.0
• symfony/dependency-injection: ^6.4 || ^7.0 || ^8.0
• symfony/event-dispatcher: ^6.4 || ^7.0 || ^8.0
• symfony/http-foundation: ^6.4 || ^7.0 || ^8.0
• symfony/http-kernel: ^6.4 || ^7.0 || ^8.0
• symfony/psr-http-message-bridge: ^6.4 || ^7.0 || ^8.0
• symfony/routing: ^6.4 || ^7.0 || ^8.0
• symfony/string: ^6.4 || ^7.0 || ^8.0

Requires (Dev)

• doctrine/doctrine-bundle: ^2.12
• doctrine/orm: ^3.0
• egulias/email-validator: ^4.0
• friendsofphp/php-cs-fixer: ^3.64
• opis/json-schema: ^2.6
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0
• symfony/browser-kit: ^6.4 || ^7.0 || ^8.0
• symfony/clock: ^6.4 || ^7.0 || ^8.0
• symfony/doctrine-bridge: ^6.4 || ^7.0 || ^8.0
• symfony/expression-language: ^6.4 || ^7.0 || ^8.0
• symfony/framework-bundle: ^6.4 || ^7.0 || ^8.0
• symfony/intl: ^6.4 || ^7.0 || ^8.0
• symfony/security-bundle: ^6.4 || ^7.0 || ^8.0
• symfony/security-core: ^6.4 || ^7.0 || ^8.0
• symfony/translation: ^6.4 || ^7.0 || ^8.0
• symfony/validator: ^6.4 || ^7.0 || ^8.0
• symfony/var-exporter: ^6.4 || ^7.0 || ^8.0
• symfony/yaml: ^6.4 || ^7.0 || ^8.0
• zenstruck/foundry: ^2.10

Suggests

• doctrine/orm: Enables the reference Doctrine data provider/persister for zero-handler CRUD endpoints (^3.0).
• egulias/email-validator: Enables strict (RFC 5322) translation of the email.strict constraint; without it the Email rule falls back to Symfony's HTML5 mode (^4.0).
• opis/json-schema: Enables the optional dev/CI structural document linter (json_api.schema_validation) that validates write bodies against the JSON:API JSON Schema, and the SchemaConformanceTrait that validates real responses against the generated OpenAPI component schemas in your test suite (^2.6).
• symfony/browser-kit: Enables the JsonApiBrowser test utility (KernelBrowser's BrowserKit base); only needed in test/dev (^6.4 || ^7.0 || ^8.0).
• symfony/doctrine-bridge: Enables the UniqueEntity entity-level constraint (it ships Symfony's UniqueEntity constraint + validator); without it UniqueEntity cannot be translated (^6.4 || ^7.0 || ^8.0).
• symfony/expression-language: Enables the ECMA expression syntax used by the resource security expressions (it ships with symfony/security-core's ExpressionVoter) (^6.4 || ^7.0 || ^8.0).
• symfony/framework-bundle: Enables the JsonApiBrowser test utility (it extends Symfony's KernelBrowser); only needed in test/dev (^6.4 || ^7.0 || ^8.0).
• symfony/intl: Enables sourcing a reference-data resource (e.g. a countries list) from the ICU dataset; used by the music-catalog example app (^6.4 || ^7.0 || ^8.0).
• symfony/security-core: Enables declarative resource authorization: security expressions on #[AsJsonApiResource] are evaluated at the lifecycle hooks via the AuthorizationChecker, and an AccessDenied/Authentication exception maps to a 403/401 JSON:API error (^6.4 || ^7.0 || ^8.0).
• symfony/translation: Enables localizing/overriding the error catalogue: title/detail are looked up per error code in the jsonapi_errors translation domain, rendered in the request's negotiated locale (^6.4 || ^7.0 || ^8.0).
• symfony/validator: Enables translating JSON:API resource constraints into Symfony Validator rules for create/update validation (^6.4 || ^7.0 || ^8.0).
• symfony/yaml: Enables YAML output for the OpenAPI export command (json-api:openapi:export --format=yaml) and the optional static .yaml artifact the OpenAPI cache warmer writes to public_path; without it only JSON is emitted (^6.4 || ^7.0 || ^8.0).

MIT

• Gregory Haddow

• symfony
• rest
• api
• bundle
• doctrine
• jsonapi
• JSON-API
• psr-15

Published on Packagist.org on 2026-07-13 09:20 UTC

README

Part of the jsonapi.rest suite — a complete, spec-compliant JSON:API 1.1 stack for PHP: a framework-agnostic core, this Symfony bundle, a Laravel package, and a typed TypeScript client, bound together by one conformance-tested OpenAPI 3.1 contract.

A Symfony bundle that makes haddowg/json-api idiomatic in a Symfony application: register a JSON:API type as a service and get the standard JSON:API 1.1 endpoint set — idiomatic routing, content negotiation, spec-compliant error documents, constraint validation, and a reference Doctrine data layer — with no controller, no operation handler, and no serializer wired by hand.

It is the Symfony twin of the Laravel package: both build on the same framework-agnostic core and project a byte-identical OpenAPI document for an identical domain, so a client generator consumes either backend unchanged.

Requirements

• PHP 8.3, 8.4, or 8.5
• Symfony 6.4, 7.x, or 8.x

Doctrine, the validator, the opis linter, and strict email are opt-in (suggest dependencies) — install one to enable that capability, leave it out and the path is simply absent. See the optional-dependency matrix.

Installation

composer require haddowg/json-api-symfony

Composer pulls the core library and the PSR-7 bridge it needs. Registering the bundle and importing its routes — the one step that surprises everyone, since the bundle mounts no routes until you ask it to — is covered in install.

Documentation

Full documentation is published at haddowg.github.io/json-api-symfony. Start with install and getting started, or browse the documentation index.

Core concepts (fields, relations, constraints, response value objects) live in the core documentation.

Demo

docker compose up from examples/music-catalog-symfony boots the full music-catalog service — curl http://localhost:8080/albums, with interactive OpenAPI docs (Swagger UI) at http://localhost:8080/docs. The getting-started guide walks the same example.

Licence

Released under the MIT Licence.