JSON streamer for large collections

The default Symfony serializer builds the full response in memory before writing it to the output. For a collection of 10,000 items, this means allocating a PHP array, serializing it to a string, and keeping both in memory until the response is flushed. At scale, this is the source of the OOM errors that force people to add pagination everywhere.

4.2 adds a streaming JSON encoder that writes the response incrementally:

api_platform:
    serializer:
        enable_json_streamer: true

With streaming enabled, the response is written directly to the output buffer as each item is serialized. Memory usage stays roughly constant regardless of collection size. The trade-off: you cannot set response headers after streaming starts, and the HTTP status code must be committed before the first byte is written.

ObjectMapper replaces manual DTO wiring

3.1 introduced stateOptions with DoctrineOrmOptions for separating the API resource from the Doctrine entity. The provider received entity objects and the serializer mapped them to the DTO. This worked, but the mapping was implicit — the serializer used property names to match fields, and anything that did not match was either ignored or caused a normalization error.

4.2 introduces ObjectMapper, a declarative mapping layer between entities and DTOs:

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    public string $title;
    public string $authorName;
}

The #[Map] attribute tells ObjectMapper that BookDto can be populated from BookEntity. Field names are matched by convention; mismatches are declared explicitly at the property level:

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    #[Map(source: 'author.fullName')]
    public string $authorName;
}

The dot notation traverses nested objects. The mapping runs before serialization and replaces the implicit property-matching behavior of the serializer. Unmapped fields raise an error at configuration time, not at runtime.

ObjectMapper works with stateOptions:

use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use Symfony\Component\ObjectMapper\Attribute\Map;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
#[Map(source: BookEntity::class)]
class BookDto {}

The provider fetches BookEntity objects from Doctrine. ObjectMapper converts them to BookDto instances. The serializer writes the DTO. Three distinct steps, each with a clear contract.

TypeInfo integration throughout the stack

Symfony 7.1 introduced the TypeInfo component , a unified type introspection layer that understands union types, intersection types, generic collections, and nullable types across reflection, PHPDoc, and PHP 8.x syntax.

4.2 replaces API Platform’s internal type resolution with TypeInfo. This affects filter schema generation, OpenAPI schema inference, and the serializer’s type coercion. The visible benefit is that types that previously generated incorrect or missing OpenAPI schemas — Collection<int, Book>, list<string>, intersection types — now produce accurate schemas without manual @ApiProperty annotations.

Autoconfigure #[ApiResource]

Before 4.2, adding #[ApiResource] to a class was sufficient for Hugo to discover it only if the class was in a path scanned by API Platform’s resource loader. Outside that path, you needed explicit service configuration.

4.2 hooks into Symfony’s autoconfigure system. Any class tagged with #[ApiResource] is automatically registered as a resource regardless of its location, as long as it is in a directory covered by Symfony’s component scan. No config/services.yaml entry needed.

For Laravel, the equivalent uses Laravel’s service provider autoloading — Eloquent models with #[ApiResource] are picked up automatically without manual registration.

Doctrine ExistsFilter

The ExistsFilter constrains a collection by whether a nullable relation or field is set:

#[ApiFilter(ExistsFilter::class, properties: ['publishedAt'])]
class Book {}

GET /books?exists[publishedAt]=true returns books where publishedAt is not null. exists[publishedAt]=false returns books where it is null.

Strict query parameter validation

3.3 introduced query parameter validation as opt-in. 3.4 deprecated the loose behavior. 4.1 formalizes it with a native strictQueryParameterValidation property on resources and operations: when set to true, unknown query parameters return 400.

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    strictQueryParameterValidation: true,
    parameters: [
        new QueryParameter(key: 'utm_source', required: false, schema: ['type' => 'string']),
        new QueryParameter(key: 'feature_flag', required: false, schema: ['type' => 'string']),
    ]
)]
class Book {}

Declared parameters pass through; undeclared parameters are rejected. To disable strict validation on a specific operation when it is enabled at the resource level, set strictQueryParameterValidation: false on that operation.

x-apiplatform-tag for multi-spec OpenAPI

Large APIs often need multiple OpenAPI specs: one per team, one per API version, one internal and one public. Before 4.1, the generated spec was one document, and splitting it required post-processing or separate API Platform instances.

4.1 adds an x-apiplatform-tag vendor extension (no trailing s). You tag operations with logical group names via the extensionProperties of an OpenAPI Operation object, then request the spec filtered to one or more groups:

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\OpenApi\Factory\OpenApiFactory;
use ApiPlatform\OpenApi\Model\Operation;

#[GetCollection(
    openapi: new Operation(
        extensionProperties: [OpenApiFactory::API_PLATFORM_TAG => ['public', 'v2']]
    )
)]
class Book {}

Requesting /api/docs.json?filter_tags[]=public returns only the operations tagged public. The full spec is still available without a filter. Groups do not affect the actual API behavior — they are a documentation-layer concern only.

This makes it feasible to maintain one API Platform configuration while serving different spec views to different consumers: a public Swagger UI, a partner portal, and an internal tool that exposes admin endpoints.

HTTP authentication in Swagger UI

Before 4.1, the Swagger UI bundled with API Platform supported Bearer token authentication via its “Authorize” dialog. API Key and HTTP Basic authentication were not wired in.

4.1 adds support for multiple security schemes in the generated OpenAPI document. Security schemes are added by decorating the OpenApiFactory and modifying the components.securitySchemes object of the spec. Each declared scheme then appears in Swagger UI’s “Authorize” dialog and is applied to requests made from the UI. This is a documentation and developer experience improvement — the actual authentication logic in your application is not affected.

GraphQL query depth and complexity limits

GraphQL’s recursive query structure makes it trivial to craft a query that is small in bytes but enormous in execution cost. Without limits, a nested query four levels deep across a many-to-many relation can hit the database hundreds of times.

4.1 adds configurable depth and complexity limits:

api_platform:
    graphql:
        max_query_depth: 10
        max_query_complexity: 100

max_query_depth is the maximum nesting level. max_query_complexity assigns a cost to each field and rejects queries whose total cost exceeds the threshold. Queries that exceed either limit are rejected before execution with a 400 response.

There is no universally correct value for these limits — they depend on your schema shape and expected query patterns. The defaults are intentionally permissive to avoid breaking existing APIs on upgrade. Tightening them is a deliberate configuration choice.

Operation-level output formats

4.0 and earlier configured accepted and returned content types at the API level. 4.1 lets you narrow this per operation:

use ApiPlatform\Metadata\GetCollection;

#[GetCollection(
    outputFormats: ['jsonld' => ['application/ld+json']],
    inputFormats: ['json' => ['application/json']],
)]
class Book {}

Operations that do not specify formats inherit the API-level configuration. This is useful for endpoints that need to return a specific format (a CSV export, a binary stream) without changing the defaults for the rest of the API.

Laravel as a first-class target

Since its first release, API Platform was built on Symfony. The HTTP layer, metadata, serializer, and Doctrine bridge all assumed Symfony’s container, event dispatcher, and request lifecycle. Laravel users could run API Platform through a thin adapter, but filters, security, and Doctrine integration did not work on Eloquent.

4.0 ships a dedicated Laravel bridge. It maps API Platform’s state layer onto Laravel’s request lifecycle, integrates with Eloquent models directly, and wires into Laravel’s authorization system:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Illuminate\Database\Eloquent\Model;

#[ApiResource(
    operations: [new GetCollection(), new Get()]
)]
class Book extends Model
{
    protected $fillable = ['title', 'author'];
}

Authorization uses Laravel policies and gates rather than Symfony’s security voters. Operations expose a dedicated policy parameter that maps to a policy method name:

#[Get(policy: 'view')]
class Book extends Model {}

API Platform maps the policy value to Laravel’s Gate::allows() with the model instance. Policies can also be auto-detected: if a model has a registered policy class, API Platform infers the correct method (view, viewAny, create, update, delete) based on the operation type. Filters for Eloquent collections cover the same ground as their Doctrine counterparts: PartialSearchFilter, EqualsFilter, RangeFilter, OrderFilter, DateFilter, and search variants (StartSearchFilter, EndSearchFilter). Pagination, sorting, and validation work through Laravel’s native mechanisms.

This is not a compatibility shim. The Laravel bridge is maintained alongside the Symfony bridge and is covered by the same test suite. Projects using either framework get the same resource definition API.

PUT removed from default operations

Since API Platform 1.0, #[ApiResource] without an explicit operations array generated CRUD operations including PUT. The PUT handler updated existing resources and, after 3.1, could also create them via allowCreate: true.

4.0 removes PUT from the default set. #[ApiResource] now generates GET, POST, PATCH, and DELETE. To use PUT, you must declare it explicitly:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Put;

#[ApiResource(
    operations: [
        // ... other operations
        new Put(),
    ]
)]
class Book {}

The motivation is semantic clarity. PATCH replaces PUT for most partial-update use cases. PUT’s semantics — replace the entire resource representation — are rarely what an API actually implements, but the default made it appear in every API unless actively removed. Making PUT opt-in aligns the defaults with how HTTP semantics are actually used in practice.

PHP 8.2 minimum

4.0 drops PHP 8.0 and 8.1. PHP 8.2 is the new minimum. The readonly class syntax, AllowDynamicProperties, and DNF¹ types introduced in 8.2 are available throughout the codebase. No specific 8.2 feature is load-bearing for 4.0 — the version bump is primarily about dropping the older maintenance burden.

Symfony 6.4+ and Doctrine ORM 2.17+ minimum

On the Symfony side, 4.0 requires Symfony 6.4 or 7.x and Doctrine ORM 2.17 or 3.x. Both were already supported in 3.4. The migration from 3.4 to 4.0 on the Symfony track is: resolve 3.4 deprecations, verify you are on Symfony 6.4+ and ORM 2.17+, then upgrade. No new migration work is required if those are already in place.

What 4.0 is not

4.0 is not a new architecture. The state providers, processors, and resource metadata model from 3.0 are unchanged. The Laravel bridge adds a new execution context but does not change how resources or operations are declared. The split is intentional: if 3.0 was the “what”, 4.0 is the “where”.

BackedEnum as API resources

Since PHP 8.1, BackedEnum classes have a fixed set of cases with string or integer backing values. API Platform 3.4 lets you put #[ApiResource] directly on a BackedEnum:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [new GetCollection()]
)]
enum BookStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

A GET /book_statuses endpoint returns the list of cases. Each case is serialized with its name and value. The endpoint is read-only — enums are immutable by nature.

This is mostly useful for frontend consumers that want a machine-readable list of valid values without hardcoding them. The alternative was a custom controller or a dedicated DTO resource listing the enum values manually.

BackedEnumFilter

The companion to enum resources is BackedEnumFilter, a new filter for Doctrine collections that constrains a query by a BackedEnum property:

use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
#[ApiFilter(BackedEnumFilter::class, properties: ['status'])]
class Book
{
    public BookStatus $status;
}

GET /books?status=published filters the collection to books where status equals BookStatus::Published. Invalid enum values return a 400 response. Before this filter, you had to either write a custom filter or use SearchFilter and validate the value manually.

Security expressions on parameters

3.3 added security to links and properties. 3.4 extends this to query parameters. A parameter can declare a security expression that controls whether it is accepted at all:

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    parameters: [
        new QueryParameter(
            key: 'includeDeleted',
            security: "is_granted('ROLE_ADMIN')"
        ),
    ]
)]
class Book {}

When the security expression is false, the parameter is rejected with a 403, not silently ignored. This is more explicit than checking the user’s role inside the provider after receiving the parameter.

DBAL 4 support added

3.4 adds support for Doctrine DBAL 4, which ships with type system changes that affect how custom types and platform-specific SQL work. The Doctrine Orm filters and query extensions in API Platform were updated to work with the new DBAL 4 type API.

Both DBAL 3 (^3.4.0) and DBAL 4 are supported simultaneously in 3.4. This is the release to upgrade to if you want to adopt DBAL 4 while staying on a stable API Platform 3.x branch.

Query parameter validator deprecated

3.3 added the strict query parameter validator as an opt-in. 3.4 deprecates the old behavior (unknown parameters silently ignored) in preparation for making strict validation the default in 4.0. Projects that relied on pass-through query parameters have one more release to declare them explicitly.

Last stop before 4.0

3.4 is the last 3.x release with new features. Anything 3.x that was deprecated by 3.4 is gone in 4.0. The migration path from 3.4 to 4.0 is intentionally short: resolve the deprecations, then upgrade.

Declarative header configuration

Before 3.3, setting custom response headers required either a custom processor that modified the response object or a Symfony event listener on kernel.response. Both approaches worked but lived outside the resource definition.

3.3 adds a parameters parameter to operation metadata:

use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\HeaderParameter;

#[Get(
    parameters: [
        'X-Custom-Header' => new HeaderParameter(description: 'A custom header'),
    ]
)]

For headers that vary per response (like Cache-Control with a computed max-age), the processor can still set them directly on the response. The headers parameter is primarily for documenting expected headers in the OpenAPI spec and for static header values.

Link security on sub-resources

When a resource exposes links to related resources, those links appear in the serialized output regardless of whether the current user can access the linked resource. This creates a disclosure problem: a user who can read a book but not its author profile still sees the author’s URI in the response.

3.3 adds security expressions to the Link descriptor:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Link;

#[ApiResource]
#[Get]
class Book
{
    #[Link(
        toClass: Author::class,
        security: "is_granted('ROLE_ADMIN')"
    )]
    public Author $author;
}

The link is omitted from the response when the security expression evaluates to false. The linked resource itself is not affected — only whether the current response includes the reference to it.

ApiProperty::security

The same security expression mechanism is available at the property level via ApiProperty::security. This lets you hide individual fields based on the current user without writing a custom normalizer:

use ApiPlatform\Metadata\ApiProperty;

class Book
{
    #[ApiProperty(security: "is_granted('ROLE_ADMIN')")]
    public string $internalNote;
}

The property is excluded from serialization when the expression is false. This is cleaner than a normalizer for the common case of role-gated fields.

OpenAPI webhooks

OpenAPI 3.1 supports webhooks — outbound HTTP calls that your API makes to registered listeners — in the spec document itself. Before 3.3, there was no way to document these in API Platform’s generated spec.

3.3 adds a Webhook class you pass to the openapi parameter of an operation. Declare a dedicated PHP class with #[ApiResource] and use Webhook on each operation to describe the outbound call shape:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Attributes\Webhook;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\PathItem;

#[ApiResource(
    operations: [
        new Post(
            openapi: new Webhook(
                name: 'bookCreated',
                pathItem: new PathItem(
                    post: new Operation(summary: 'A book was created'),
                ),
            )
        ),
    ]
)]
class BookWebhook {}

The webhook definitions appear in the generated spec under the webhooks key alongside regular paths. Swagger UI renders them in a separate section.

Swagger UI deep linking

Swagger UI supports deep linking — bookmarkable URLs that open directly to a specific operation in the interface. Before 3.3, the API Platform integration did not enable this. 3.3 turns on the Swagger UI deepLinking option, configurable via swagger_ui_extra_configuration:

api_platform:
    openapi:
        swagger_ui_extra_configuration:
            deepLinking: true

With this enabled, the URL fragment updates as you navigate the UI, and pasting or sharing the URL opens the same operation. Useful when writing docs that link directly to a specific endpoint.

Strict query parameter validation

3.3 tightens the query parameter validator: parameters not declared on the operation now return a 400 response instead of being silently ignored. This behavior is opt-in:

api_platform:
    validator:
        query_parameter_validation: true

The intent is to catch typos and API misuse early. If you rely on pass-through query parameters for custom logic (logging, feature flags), you need to declare them explicitly on the operation before enabling this.

Errors as resources

Before 3.2, error handling was outside the resource model. Exceptions were caught by a Symfony event listener and converted to a response, with limited control over the shape of the output.

3.2 makes errors first-class ApiResource classes compliant with RFC 9457 (Problem Details for HTTP APIs). The built-in error class is ApiPlatform\ApiResource\Error, and you can create your own:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ApiResource]
#[ErrorResource]
class BookNotFoundError extends \RuntimeException implements ProblemExceptionInterface
{
    public function __construct(private readonly string $bookId)
    {
        parent::__construct("Book $bookId not found");
    }

    public function getType(): string
    {
        return '/errors/book-not-found';
    }
}

When this exception is thrown anywhere in the state layer, API Platform catches it, serializes it as a Problem Detail response, and generates a proper OpenAPI schema for it. The error type, title, detail, and status are all part of the resource contract — not hardcoded strings in a listener.

Sub-resources without the workarounds

Sub-resources existed in 2.x but were removed in 3.0 because they were tightly coupled to the old data provider model and couldn’t be cleanly mapped to the new operation-first architecture. 3.2 reintroduces them in a way that fits.

A sub-resource is a resource accessible through a parent resource’s URI. In 3.2, it is declared directly on the child resource using uriTemplate:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: [
                'bookId' => new Link(fromClass: Book::class),
            ],
        ),
    ]
)]
class Review
{
    // ...
}

The Link descriptor makes the relationship explicit. The provider receives bookId in $uriVariables and can use it to scope the query. No magic inference, no implicit joins — the URI structure and the data access are both declared.

canonical_uri_template for multiple access paths

When a resource is accessible through multiple URIs (a direct endpoint and a sub-resource endpoint), OpenAPI needs to know which URI is canonical for $ref links. 3.2 uses the top-level uriTemplate on ApiResource as the default canonical URI. For finer control, the canonical_uri_template option can be passed via extraProperties on any operation to override it explicitly.

#[ApiResource(
    uriTemplate: '/reviews/{id}',
    operations: [
        new Get(),
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: ['bookId' => new Link(fromClass: Book::class)],
        ),
    ]
)]
class Review {}

The generated OpenAPI spec uses the canonical URI for schema references, keeping the document consistent when a resource appears under several paths.

Union and intersection types

3.2 adds support for PHP union and intersection types in the metadata layer. A property declared as Book|Magazine generates a proper oneOf schema in OpenAPI. This was previously unsupported — you had to fall back to an untyped mixed or annotate the property manually.

Event listeners made optional

The last compatibility shim from 2.x was the ability to use Symfony event listeners on the kernel.request and kernel.view events to intercept API Platform’s data flow. 3.2 does not remove them, but introduces an opt-out: setting event_listeners_backward_compatibility_layer: false in the API Platform configuration disables the event-based hooks entirely. The replacement is a provider or processor decorated with another provider or processor. The event-based hook was stateful, order-dependent, and bypassed the operation context entirely. Decorated providers get the operation object and can call the inner provider when ready.

The state model is now complete

3.0 introduced the architecture. 3.1 added resource/entity separation. 3.2 closes the remaining gaps: errors have a resource contract, sub-resources have a clean declaration model, and the state layer now covers every extension point that event listeners once handled. The 2.x shims still exist, but opting out of them is now a single config flag.

The resource/entity split

In 2.x, API Platform worked best when your API resource and your persistence model were the same class. Using a DTO as the API surface was possible through the Input/Output DTO system, but that system was removed in 3.0 — it complicated the state model without enough benefit.

3.1 replaces it with something cleaner. The stateOptions parameter on an operation accepts a DoctrineOrmOptions object that points to a different entity:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Orm\State\Options;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
class BookDto
{
    public string $title;
    public string $author;
}

The provider receives the BookEntity objects from Doctrine and the serialization layer maps them to BookDto. The Doctrine filters, pagination, and ordering all work on BookEntity. The API surface exposes BookDto. The two can evolve independently.

This matters more than it looks. Your persistence model accumulates internal fields, relations, and columns that have no business being in your API. Before 3.1, you either exposed them anyway or built an elaborate normalizer to hide them. Now you declare what the API looks like as a separate class and let the framework handle the mapping.

PUT that follows the spec

Since version 1.0, API Platform’s PUT handler updated existing resources. Creating a resource via PUT — which the HTTP spec explicitly allows — was not supported. 3.1 adds uriTemplate-based creation:

#[Put(
    uriTemplate: '/books/{id}',
    allowCreate: true,
)]

With allowCreate: true, a PUT to a URI that does not exist creates the resource instead of returning 404. The identifier comes from the URI, not from the request body. This is what RFC 9110 describes for PUT: “If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response.”

It is a small flag, but it opens API Platform to use cases — idempotent resource creation, client-assigned identifiers — that previously required a custom controller.

Denormalization errors collected, not thrown

Before 3.1, deserialization errors stopped at the first problem. Send a request body with five invalid fields and get an error about the first one. Fix it, send again, find the second. Repeat five times.

3.1 adds a collect_denormalization_errors option on the operation that changes this behavior:

#[Post(collectDenormalizationErrors: true)]

With this enabled, API Platform catches all type errors and constraint violations during deserialization and returns them as a structured list in the response, formatted the same way as validation errors. One round-trip, full picture.

ApiResource::openapi replaces openapiContext

The old openapiContext parameter accepted a raw array that was merged into the generated OpenAPI schema — convenient but untyped. 3.1 introduces a first-class openapi parameter that accepts an OpenApiOperation object:

use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\RequestBody;

#[Post(
    openapi: new Operation(
        requestBody: new RequestBody(
            description: 'Create a book',
            required: true,
        ),
        summary: 'Create a new book entry',
    )
)]

The old openapiContext array still works but is deprecated. The new approach is typed, IDE-friendly, and validates at construction time rather than at schema generation time. PHP 8.1 backed enums also get proper OpenAPI schema generation in 3.1 — a field typed as a backed enum produces a schema with enum values and the correct type, without any annotation.

The pattern is clear

3.0 established the architecture. 3.1 shows what that architecture enables: clean resource/entity separation without a parallel DTO system, RFC-correct HTTP semantics, better error reporting. None of these would have been as clean to implement on the 2.x data provider model. The features in 3.1 are the first proof that the rewrite was the right call.

The old model had a conceptual leak. DataProviderInterface and DataPersisterInterface were called for every HTTP request, but the provider received the operation context as a hint — not as a contract. A collection provider and an item provider were separate interfaces, but both lived in the same mental bucket: “things that return data.” The HTTP layer knew what was being requested; the provider had to reconstruct that knowledge from context clues passed in the $context array.

3.0 inverts the model. Operations are declared first. Data access is wired to operations.

State providers replaced data providers

The old DataProviderInterface is gone. The replacement is ProviderInterface:

use ApiPlatform\State\ProviderInterface;
use ApiPlatform\Metadata\Operation;

class BookProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            return $this->repository->findAll();
        }

        return $this->repository->find($uriVariables['id']);
    }
}

The difference is not syntactic. In 2.x, you registered a provider and API Platform called it for any matching resource. In 3.0, you bind a provider to a specific operation. The provider no longer guesses what triggered it — the operation object it receives is the contract.

State processors replaced data persisters

DataPersisterInterface had the same problem on the write side: one class handling create, update, and delete, distinguishing them by inspecting the HTTP method or the object state. ProcessorInterface receives the operation as a typed argument:

use ApiPlatform\State\ProcessorInterface;
use ApiPlatform\Metadata\Operation;

class BookProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        $this->entityManager->persist($data);
        $this->entityManager->flush();

        return $data;
    }
}

More usefully: you can bind a different processor per operation. The delete operation gets one that removes. The post operation gets one that validates and stores. No switch statement, no method inspection, no shared class trying to be three things at once.

Operations declared explicitly in PHP 8.1 attributes

The other half of 3.0 is the metadata layer. Doctrine annotations are replaced by PHP 8.1 native attributes, and each operation is declared explicitly on the resource class:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new GetCollection(provider: BookProvider::class),
        new Get(provider: BookProvider::class),
        new Post(processor: BookProcessor::class),
    ]
)]
class Book
{
    // ...
}

This is more verbose than @ApiResource with magic defaults. It is also explicit. You know exactly what HTTP operations exist for this resource, what retrieves data, what writes it, and where the logic lives. The defaults of 2.x were convenient until the day you needed to override one and couldn’t figure out which service to decorate without reading the source.

PHP 8.1 was not a coincidence

The hard requirement for PHP 8.1 is load-bearing. First-class callables make filter registration cleaner. The immutability of operation metadata is enforced through cloning patterns (withX() methods) that rely on named arguments and promoted constructor properties — PHP 8.0 foundations the architecture builds on heavily.

More practically: the full expression of 3.0’s architecture — typed operations, operation-scoped providers, explicit metadata — needed 8.1 to not feel like workarounds. Dropping PHP 7.x and 8.0 was not a housekeeping decision.

The migration is real work

The jump from 2.x to 3.0 is not a version bump. Every DataProvider becomes a ProviderInterface. Every DataPersister becomes a ProcessorInterface. Annotations become attributes. Custom normalizers and filters may need restructuring. The upgrade guide documents all of it, but “documented” does not mean “fast.”

What you get on the other side is an architecture that scales without the ambient complexity of 2.x: no more guessing which interface to implement, no more $this->supports() chains, no more invisible defaults quietly overriding explicit config.

3.0 is the API Platform you’d design from scratch knowing what you know after years of 2.x. The price is the migration. The version number is honest about that.