Upgrade Guide

API Platform 2.7/3.0

I Want to Try the New Metadata System

Note that if you want to use the new metadata system, you need to set:

新しいメタデータ システムを使用する場合は、以下を設定する必要があることに注意してください。

# api/config/packages/api_platform.yaml
    metadata_backward_compatibility_layer: false

This will be the default value in 3.0, in 2.7 it's left to true so that nothing breaks by updating. By doing so you won't get access to legacy services and this will probably break things on code using api-platform/core:2.6.

これは 3.0 ではデフォルト値になり、2.7 では更新によって何も壊れないように true のままになっています。そうすると、レガシー サービスにアクセスできなくなり、おそらく api-platform/core:2.6 を使用するコードで問題が発生します。 .

I'm Migrating From 2.6 and Want to Prepare For 3.0

  1. Update the code to 2.7: composer require api-platform/core:^2.7
    コードを 2.7 に更新します: composer require api-platform/core:^2.7
  2. Take care of the deprecations and update your code to the new interfaces, documented on this page
  3. Switch the metadata_backward_compatibility_layer flag to false
    metadata_backward_compatibility_layer フラグを false に切り替えます
  4. Use the api:upgrade-resource command
    api:upgrade-resource コマンドを使用します

Read more about the metadata_backward_compatibility_layer flag here.

metadata_backward_compatibility_layer フラグの詳細については、こちらをご覧ください。


Summary of the Changes Between 2.6 And 2.7/3.0

  • New Resource metadata allowing to declare multiple Resources on a class: ApiPlatform\Metadata\ApiResource
    クラスで複数のリソースを宣言できる新しいリソース メタデータ: ApiPlatform\Metadata\ApiResource
  • Clarification of some properties within the ApiResource declaration
    ApiResource 宣言内のいくつかのプロパティの明確化
  • Removal of item and collection differences on operation declaration
  • ApiPlatform\Core\DataProvider\...DataProviderInterface has a new interface ApiPlatform\State\ProviderInterface
    ApiPlatform\Core\DataProvider\...DataProviderInterface には新しいインターフェイス ApiPlatform\State\ProviderInterface があります
  • ApiPlatform\Core\DataPersister\...DataPersisterInterface has a new interface ApiPlatform\State\ProcessorInterface
    ApiPlatform\Core\DataPersister\...DataPersisterInterface には新しいインターフェイス ApiPlatform\State\ProcessorInterface があります
  • New ApiProperty metadata ApiPlatform\Metadata\ApiProperty
    新しい ApiProperty メタデータ ApiPlatform\Metadata\ApiProperty
  • Configuration flag metadata_backward_compatibility_layer that allows the use of legacy metadata layers
    従来のメタデータ レイヤーの使用を許可する構成フラグ metadata_backward_compatibility_layer
  • ApiPlatform\Core\DataTransformer\DataTransformerInterface is deprecated and will be removed in 3.0
    ApiPlatform\Core\DataTransformer\DataTransformerInterface は非推奨であり、3.0 で削除されます
  • Subresources are now additional resources marked with an #[ApiResource] attribute (see the new subresource documentation)
    サブリソースは、#[ApiResource] 属性でマークされた追加のリソースになりました (新しいサブリソースのドキュメントを参照してください)。

The detailed changes are present in the CHANGELOG.

詳細な変更は CHANGELOG にあります。

ApiResource Metadata

The ApiResource annotation has a new namespace: ApiPlatform\Metadata\ApiResource instead of ApiPlatform\Core\Annotation\ApiResource.

ApiResource アノテーションには、ApiPlatform\Core\Annotation\ApiResource の代わりに、ApiPlatform\Metadata\ApiResource という新しい名前空間があります。

For example, the Book resource in 2.6:

たとえば、2.6 の Book リソースは次のようになります。

// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

    iri: 'https://schema.org/Book',
    itemOperations: [
        'post_publication' => [
            'method' => 'POST',
            'path' => '/books/{id}/publication',
class Book
    // ...

Becomes in 2.7:

2.7 で次のようになります。

// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;
use App\Controller\CreateBookPublication;

#[ApiResource(types: ['https://schema.org/Book'], operations: [
    new Get(),
    new Post(name: 'publication', uriTemplate: '/books/{id}/publication')
class Book
    // ...

You can use the api:upgrade-resource command to upgrade your resources automatically, see instructions here.

api:upgrade-resource コマンドを使用して、リソースを自動的にアップグレードできます。こちらの手順を参照してください。

Removal of Item/Collection Operations

We removed the notion of item and collection. Instead, use HTTP verbs matching the operation you want to declare. There is also a collection flag instructing whether the operation returns an array or an object. The default ApiResource attribute still declares a CRUD:

アイテムとコレクションの概念を削除しました。代わりに、宣言する操作に一致する HTTP 動詞を使用します。操作が配列またはオブジェクトを返すかどうかを指示するコレクション フラグもあります。デフォルトの ApiResource 属性は引き続き CRUD を宣言します。


is the same as:


#[ApiResource(operations: [
    new Get(),
    new Put(),
    new Patch(),
    new Delete(),
    new GetCollection(),
    new Post(),

Metadata Changes


ApiPlatform\Metadata\ApiResource instead of ApiPlatform\Core\Annotation\ApiResource

ApiPlatform\Core\Annotation\ApiResource の代わりに ApiPlatform\Metadata\ApiResource

Before After
iri: 'https://schema.org/Book' types: ['https://schema.org/Book']
path: '/books/{id}/publication' uriTemplate: '/books/{id}/publication'
identifiers: [] uriVariables: []
attributes: [] extraProperties: []
attributes: ['validation_groups' => ['a', 'b']] validationContext: ['groups' => ['a', 'b']]


ApiPlatform\Metadata\ApiProperty instead of ApiPlatform\Core\Annotation\ApiProperty

ApiPlatform\Core\Annotation\ApiProperty の代わりに ApiPlatform\Metadata\ApiProperty

Before After
iri: 'https://schema.org/Book' types: ['https://schema.org/Book']
type: 'string' builtinTypes: ['string']

Note that builtinTypes are computed automatically from PHP types.

builtinTypes は PHP の型から自動的に計算されることに注意してください。

For example:


class Book
    public string|Isbn $isbn;

Will compute: builtinTypes: ['string', Isbn::class]

計算します: builtinTypes: ['string', Isbn::class]

The metadata_backward_compatibility_layer Flag

In 2.7 the metadata_backward_compatibility_layer flag is set to true. This means that all the legacy services will still work just as they used to work in 2.6 (for example PropertyMetadataFactoryInterface or ResourceMetadataFactoryInterface). When updating we advise to first resolve the deprecations then to set this flag to false to use the new metadata system.

2.7 では、metadata_backward_compatibility_layer フラグが true に設定されています。これは、すべてのレガシー サービスが 2.6 で機能していたのと同じように機能することを意味します (たとえば、PropertyMetadataFactoryInterface または ResourceMetadataFactoryInterface)。更新するときは、まず非推奨を解決してから、このフラグを false に設定して、新しいメタデータ システムを使用します。

When metadata_backward_compatibility_layer is set to false: - there's still a bridge with the legacy ApiPlatform\Core\Annotation\ApiResource and old metadata will still work - the deprecated Symfony services will have their interface changed (for example ApiPlatform\Core\Api\IriConverterInterface will be ApiPlatform\Api\IriConverterInterface) and it may break your dependency injection. - the new metadata system is available ApiPlatform\Metadata\ApiResource

metadata_backward_compatibility_layer が false に設定されている場合:- レガシー ApiPlatform\Core\Annotation\ApiResource とのブリッジがまだあり、古いメタデータは引き続き機能します- 非推奨の Symfony サービスのインターフェースが変更されます (たとえば、ApiPlatform\Core\Api\IriConverterInterface は ApiPlatform になります) \Api\IriConverterInterface) を使用すると、依存関係の挿入が中断される可能性があります。- 新しいメタデータ システムが利用可能です ApiPlatform\Metadata\ApiResource


If you want to use the new namespaces for the search filter (ApiPlatform\Doctrine\Orm\Filter\SearchFilter instead ofApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter or ApiPlatform\Doctrine\Odm\Filter\SearchFilter instead ofApiPlatform\Core\Bridge\Doctrine\Odm\Filter\SearchFilter) you need to set the metadata_backward_compatibility_layer to false as this filter relies on the implementation of the new ApiPlatform\Api\IriConverterInterface.

検索フィルターに新しい名前空間を使用する場合 (ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter の代わりに ApiPlatform\Doctrine\Orm\Filter\SearchFilter または ApiPlatform\Core\ の代わりに ApiPlatform\Doctrine\Odm\Filter\SearchFilter Bridge\Doctrine\Odm\Filter\SearchFilter) このフィルターは新しい ApiPlatform\Api\IriConverterInterface の実装に依存しているため、metadata_backward_compatibility_layer を false に設定する必要があります。

In 3.0 this flag will default to false and the legacy code will be removed.

3.0 では、このフラグはデフォルトで false になり、レガシー コードは削除されます。

The Upgrade Command

The upgrade command will automatically upgrade the old ApiPlatform\Core\Annotation\ApiResource to ApiPlatform\Metadata\ApiResource. By default, this does a dry run and shows a diff:

アップグレード コマンドは、古い ApiPlatform\Core\Annotation\ApiResource を ApiPlatform\Metadata\ApiResource に自動的にアップグレードします。既定では、これはドライ ランを実行し、差分を表示します。

php bin/console api:upgrade-resource

To write in-place use the force option:

その場で書き込むには、force オプションを使用します。

php bin/console api:upgrade-resource -f


Providers and Processors are replacing DataProviders and DataPersisters. We reduced their interface to only one method and the class used by your operation can be specified directly within the metadata. Using Doctrine, a default resource would use these:

プロバイダーとプロセッサーは、DataProvider と DataPersisters に取って代わります。それらのインターフェースを 1 つのメソッドのみに削減し、操作で使用されるクラスをメタデータ内で直接指定できます。Doctrine を使用すると、デフォルトのリソースはこれらを使用します:


use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Delete;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;

#[Put(processor: ApiPlatform\Doctrine\Common\State\PersistProcessor::class, provider: ApiPlatform\Doctrine\Orm\State\ItemProvider::class)]
#[Post(processor: ApiPlatform\Doctrine\Common\State\PersistProcessor::class)]
#[Delete(processor: ApiPlatform\Doctrine\Common\State\RemoveProcessor::class)]
#[Get(provider: ApiPlatform\Doctrine\Orm\State\ItemProvider::class)]
#[GetCollection(provider: ApiPlatform\Doctrine\Orm\State\CollectionProvider::class)]
class Book {}

See also the respective documentation:


DataTransformers and DTO Support

Data transformers have been deprecated, instead you can still document the output or the input DTO. Then, just handle the input in a custom State Processor or return another output in a custom State Provider.

データ トランスフォーマーは廃止されました。代わりに、出力または入力 DTO をドキュメント化することができます。次に、カスタム ステート プロセッサで入力を処理するか、カスタム ステート プロバイダーで別の出力を返します。

The dto documentation has been adapted accordingly.

それに応じて dto ドキュメントが変更されました。