JsonApiBundle

Production-ready JSON:API 1.1 implementation for Symfony with complete filtering, automatic eager loading, and zero N+1 queries.

🚀 Quick Start

Installation

composer require alexfigures/symfony-jsonapi-bundle

Requirements:

PHP 8.3 or higher
Symfony 7.1 or higher
Doctrine ORM 3.0+ (optional, for database integration)

Basic Setup

Register the bundle in config/bundles.php:

return [
    AlexFigures\Symfony\Bridge\Symfony\Bundle\JsonApiBundle::class => ['all' => true],
];

Create configuration in config/packages/jsonapi.yaml:

jsonapi:
    route_prefix: '/api'
    pagination:
        default_size: 25
        max_size: 100

Define your first resource:

use AlexFigures\Symfony\Resource\Attribute\JsonApiResource;
use AlexFigures\Symfony\Resource\Attribute\Id;
use AlexFigures\Symfony\Resource\Attribute\Attribute;
use AlexFigures\Symfony\Resource\Attribute\Relationship;

#[JsonApiResource(type: 'articles')]
final class Article
{
    #[Id]
    #[Attribute]
    public string $id;

    #[Attribute]
    public string $title;

    #[Relationship(toMany: true, targetType: 'comments')]
    public array $comments = [];
}

Implement data layer (see Doctrine Integration Guide)
Start using your API:

# Get all articles
curl http://localhost:8000/api/articles

# Filter, sort, and include relationships (no N+1 queries!)
curl "http://localhost:8000/api/articles?filter[status][eq]=published&sort=-createdAt&include=author,tags"

# Advanced filtering with multiple conditions
curl "http://localhost:8000/api/articles?filter[and][0][status][eq]=published&filter[and][1][viewCount][gte]=100"

# Create new article
curl -X POST \
     -H "Content-Type: application/vnd.api+json" \
     -d '{"data": {"type": "articles", "attributes": {"title": "Hello"}}}' \
     http://localhost:8000/api/articles

# Interactive API documentation
open http://localhost:8000/_jsonapi/docs

📖 Complete Getting Started Guide → 📊 Interactive API Docs →

✅ Compatibility Matrix

JsonApiBundle	PHP	Symfony	Doctrine ORM
`main` branch	8.2 · 8.3 · 8.4	7.1 · 7.2 · 7.3	3.0+
Latest release	8.2+	7.1+	3.0+

CI runs the full test suite across PHP 8.2–8.4 with both stable and lowest-dependency sets to guarantee forwards and backwards compatibility inside each supported Symfony minor.

Tested Databases:

PostgreSQL 16+
MySQL 8.0+
MariaDB 11+
SQLite 3.x

🎯 Key Features

🔍 Advanced Filtering & Querying

Complex Filters - Support for eq, ne, gt, gte, lt, lte, in, nin, like, ilike operators
Logical Operators - Combine filters with and, or, not for complex queries
Relationship Filtering - Filter by nested relationship fields: filter[author.name]=John
Whitelist-based Security - Only explicitly allowed fields can be filtered using #[FilterableFields]

# Complex filtering example
curl "api/articles?filter[and][0][status][eq]=published&filter[and][1][or][0][viewCount][gte]=100&filter[and][1][or][1][featured][eq]=true"

🔗 Smart Relationship Handling

Zero N+1 Queries - Automatic eager loading with optimized JOINs
Deep Includes - Include nested relationships: include=author.company,tags
Relationship Linking Policies - Control how relationships are validated (VERIFY, ALLOW_ORPHANS)
Path Aliases - Expose clean API paths that map to complex Doctrine relationships

#[Relationship(
    toMany: true,
    targetType: 'tags',
    propertyPath: 'articleTags.tag',  // Clean API: specialTags → complex path
    linkingPolicy: RelationshipLinkingPolicy::VERIFY
)]
private Collection $specialTags;

📊 Flexible Sorting & Pagination

Multi-field Sorting - Sort by multiple fields: sort=title,-createdAt,author.name
Relationship Sorting - Sort by nested relationship fields
Cursor & Offset Pagination - Both pagination strategies supported
Configurable Limits - Set default and maximum page sizes

🛡️ Production-Ready Security

Strict Denormalization - Reject unknown fields by default (ALLOW_EXTRA_ATTRIBUTES=false)
Field Whitelisting - Explicit control over filterable/sortable fields
Validation Integration - Full Symfony Validator integration
Error Collection - Collect and return all validation errors at once

🚀 Developer Experience

Attribute-Based Configuration - No YAML/XML, everything in PHP attributes
Auto-Generated OpenAPI - Interactive Swagger UI documentation
Custom Route Support - Define custom endpoints with automatic JSON:API formatting
Response Factory - Fluent API for building JSON:API responses in custom controllers

#[JsonApiResource(type: 'articles')]
#[FilterableFields(['title', new FilterableField('author', inherit: true)])]
#[SortableFields(['title', 'createdAt', new SortableField('author', inherit: true)])]
final class Article
{
    #[Id] #[Attribute] public string $id;
    #[Attribute] public string $title;
    #[Relationship(targetType: 'authors')] public Author $author;
}

⚡ Performance Optimizations

Automatic Query Optimization - Smart JOINs and SELECT field limiting
Batch Operations - Efficient bulk create/update/delete
Caching Support - HTTP caching headers and response caching
Database Agnostic - Works with PostgreSQL, MySQL, MariaDB, SQLite

🔧 Extensibility

Custom Handlers - Build complex business logic with automatic transaction management
Event System - Hook into request/response lifecycle
Custom Serialization - Override default serialization behavior
Middleware Support - Standard Symfony middleware integration

📚 Documentation

For New Users

Getting Started Guide - Build your first API in 5 minutes
Swagger UI & OpenAPI - Interactive API documentation
Configuration Reference - Complete configuration options
Doctrine Integration - Production-ready data layer
Examples & Recipes - Real-world code examples
Custom Routes - Define custom endpoints with attributes
Response Factory - Build JSON:API responses in custom controllers

For Advanced Users

Path Aliases - Expose clean API paths that map to complex Doctrine relationships
Advanced Features - Profiles, hooks, events, caching
Custom Handlers - Handler-based custom routes with automatic transaction management
Public API Reference - Stable API documentation
Troubleshooting Guide - Common issues and solutions

For Contributors

Contributing Guide - How to contribute
Testing Guide - Running tests (unit, functional, integration with Docker)
Architecture Review - Design and extensibility
BC Policy - Backward compatibility guarantees

📖 Complete Documentation Index →

🆕 Recent Updates

New Features

🆕 Path Aliases - Expose clean API paths that map to complex Doctrine relationships using propertyPath parameter

#[Relationship(
    toMany: true,
    targetType: 'tags',
    propertyPath: 'articleTags.tag'  // API: specialTags → Doctrine: articleTags.tag
)]
private Collection $specialTags;

Custom Route Handlers - Build custom endpoints with automatic transaction management and JSON:API response formatting (docs)
Response Factory - Fluent API for building JSON:API responses in custom controllers (docs)
Criteria Builder - Add custom filters and conditions to JSON:API queries in custom route handlers (docs)
Custom Route Attributes - Define custom endpoints using #[JsonApiCustomRoute] attribute (docs)
Media Type Configuration - Configure different media types for different endpoints (e.g., docs, sandbox)
Docker-based Integration Tests - Run integration tests against real databases using Docker (docs)

Testing Improvements

Docker Test Environment - Integration tests now run in Docker with PostgreSQL, MySQL, and MariaDB
Conformance Tests - Snapshot-based tests ensure JSON:API specification compliance
Mutation Testing - Infection configured with 70% MSI threshold
Quality Gates - PHPStan level 8, Deptrac architecture rules, BC checks

Run tests with:

make test              # Unit and functional tests
make docker-test       # Integration tests in Docker
make qa-full          # Full QA suite (tests, static analysis, mutation testing)

See TESTING.md for complete testing documentation.

✨ Features

Production-Ready Features ⭐

✅ Complete Filtering System - All operators (eq, ne, lt, lte, gt, gte, like, in, isnull, between) with SQL injection protection ✅ Automatic Eager Loading - Zero N+1 queries with automatic JOINs for includes ✅ Generic Doctrine Repository - Works out of the box, no custom code needed ✅ Relationship Pagination - Proper pagination for all relationship endpoints ✅ PostgreSQL Optimized - Tested and optimized for PostgreSQL ✅ Custom Route Handlers - Build custom endpoints with automatic transaction management and JSON:API formatting

Core Features

✅ JSON:API 1.1 Compliance - 97.8% specification coverage (132/135 requirements) ✅ Attribute-Driven - No XML/YAML configuration needed ✅ Auto-Generated Endpoints - No controller boilerplate ✅ Configurable Route Naming - Choose between snake_case and kebab-case ✅ Custom Route Attributes - Define custom endpoints with PHP attributes ✅ Query Parameters - include, fields, sort, page, filter ✅ Relationships - To-one and to-many with full CRUD ✅ Write Operations - POST, PATCH, DELETE with validation ✅ Atomic Operations - Batch operations in single transaction ✅ Interactive Docs - Swagger UI / Redoc integration ✅ Response Factory - Build JSON:API responses in custom controllers

Read Operations

GET /api/{type} - Collection with pagination, sorting, filtering
GET /api/{type}/{id} - Single resource with sparse fieldsets
GET /api/{type}/{id}/relationships/{rel} - Relationship linkage
GET /api/{type}/{id}/{rel} - Related resources
Query parsing: include, fields[TYPE], sort, page[number], page[size]
Pagination with self, first, prev, next, last links
Compound documents with included array
Sparse fieldsets for performance optimization

Write Operations

POST /api/{type} → 201 Created with Location header
PATCH /api/{type}/{id} → 200 OK with updated resource
DELETE /api/{type}/{id} → 204 No Content
Transactional execution via TransactionManager
Client-generated ID support (configurable per type)
Strict input validation with detailed error responses
Relationship modification endpoints (optional)

Advanced Features

Profiles (RFC 6906) - Extend JSON:API with custom semantics
Hooks System - Intercept and modify request processing
Event System - React to resource changes
HTTP Caching - ETag, Last-Modified, surrogate keys
Custom Operators - Extend filtering capabilities
Cache Invalidation - CDN/reverse proxy support
Media Type Configuration - Configure different media types for different endpoints
Criteria Builder - Add custom filters and conditions to JSON:API queries in custom handlers

📖 See all features →

🔒 Backward Compatibility

JsonApiBundle follows Semantic Versioning:

MAJOR versions may contain breaking changes
MINOR versions add features in a backward-compatible manner
PATCH versions contain bug fixes only

Public API (Stable)

The following are guaranteed to maintain backward compatibility:

✅ Contract Interfaces (src/Contract/) - Data layer contracts
✅ Resource Attributes (src/Resource/Attribute/) - #[JsonApiResource], #[Attribute], etc.
✅ Configuration Schema - All jsonapi: configuration options

📖 Public API Reference → 📖 BC Policy → 📖 Upgrade Guide →

Pre-1.0 Notice

⚠️ Versions 0.x may introduce breaking changes in MINOR versions. Pin to exact MINOR version:

{
    "require": {
        "jsonapi/symfony-jsonapi-bundle": "~0.1.0"
    }
}

📖 Interactive API Documentation

The bundle provides automatic OpenAPI 3.1 documentation with interactive UI:

Access Documentation

Swagger UI (Interactive):

http://localhost:8000/_jsonapi/docs

OpenAPI Specification (JSON):

http://localhost:8000/_jsonapi/openapi.json

Features

🎨 Two themes: Swagger UI (default) or Redoc
🔍 Try it out: Test endpoints directly from browser
📖 Auto-generated: Reflects all resources and relationships
🔒 Environment-aware: Disable in production

Configuration

# config/packages/jsonapi.yaml
jsonapi:
    docs:
        generator:
            openapi:
                enabled: true
                title: 'My API'
                version: '1.0.0'
        ui:
            enabled: true
            route: '/_jsonapi/docs'
            theme: 'swagger'  # or 'redoc'

Production: Disable in config/packages/prod/jsonapi.yaml:

jsonapi:
    docs:
        ui:
            enabled: false

📖 Swagger UI Documentation →

📊 Example Response

{
  "jsonapi": { "version": "1.1" },
  "links": {
    "self": "http://localhost/api/articles?page[number]=1&page[size]=10",
    "first": "http://localhost/api/articles?page[number]=1&page[size]=10",
    "last": "http://localhost/api/articles?page[number]=3&page[size]=10",
    "next": "http://localhost/api/articles?page[number]=2&page[size]=10"
  },
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "Getting Started with JSON:API",
        "createdAt": "2025-10-07T10:00:00+00:00"
      },
      "relationships": {
        "author": {
          "links": {
            "self": "http://localhost/api/articles/1/relationships/author",
            "related": "http://localhost/api/articles/1/author"
          },
          "data": { "type": "authors", "id": "1" }
        }
      },
      "links": {
        "self": "http://localhost/api/articles/1"
      }
    }
  ],
  "included": [
    {
      "type": "authors",
      "id": "1",
      "attributes": { "name": "Alice" },
      "links": { "self": "http://localhost/api/authors/1" }
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "size": 10
  }
}

🛠️ Development & Testing

Quick Commands

# Install dependencies
composer install
# or
make install

# Run tests
make test              # Unit and functional tests (no Docker required)
make docker-test       # Integration tests with real databases
make test-all          # All test suites

# Code quality
make stan              # PHPStan static analysis (level 8)
make cs-fix            # Fix code style (PSR-12)
make rector            # Automated refactoring
make mutation          # Mutation testing (70% MSI threshold)
make deptrac           # Architecture rules validation
make bc-check          # Backward compatibility check

# Full QA pipeline
make qa-full           # Run all quality checks

See TESTING.md for detailed testing documentation.

🤝 Community & Governance

📮 Need help? Read our Support guide for documentation links, discussion forums, and escalation paths.
📋 Contributions welcome! See the CONTRIBUTING.md for coding standards and workflow.
❤️ Be excellent to each other. Participation is governed by the Code of Conduct.
🛡 Report vulnerabilities privately. Follow the steps in SECURITY.md.
🧭 Stay up to date. Watch Discussions and subscribe to release drafts for roadmap updates.

Symfony Jsonapi Bundle Laravel Package