This is a list of common pitfalls while using API Platform, and how to avoid them.

これは、API プラットフォームを使用する際の一般的な落とし穴と、それらを回避する方法のリストです。

Using Docker

With Docker Toolbox on Windows

Docker Toolbox is not supported anymore by API Platform. Please upgrade to Docker for Windows.

Docker Toolbox は API Platform でサポートされなくなりました。 Docker for Windows にアップグレードしてください。

Error Starting The Web Server

If the php container cannot start and display this Error starting userland proxy: Bind for, it means that port 80 is already in use. You can check to see which processes are currently listening on certain ports.

PHP コンテナが起動できず、Error starting userland proxy: Bind for が表示されない場合は、ポート 80 が既に使用されていることを意味します。特定のポートで現在リッスンしているプロセスを確認できます。

Find out if any service listens on port 80. You can use this command on UNIX-based OSes like MacOS and Linux:

サービスがポート 80 でリッスンしているかどうかを調べます。MacOS や Linux などの UNIX ベースの OS でこのコマンドを使用できます。

sudo lsof -n -i :80 | grep LISTEN

On Windows, you can use netstat. This will give you all TCP/IP network connections and not just processes listening to port 80.

Windows では、netstat を使用できます。これにより、ポート 80 をリッスンするプロセスだけでなく、すべての TCP/IP ネットワーク接続が提供されます。

netstat -a -b

You can change the port to be used in the docker-compose.yml file (default is port 80).

docker-compose.yml ファイルで使用するポートを変更できます (デフォルトはポート 80 です)。

Using API Platform and JMS Serializer in the same project

For the latest versions of JMSSerializerBundle, there is no conflict so everything should work out of the box.

JMSSerializerBundle の最新バージョンでは、競合がないため、すべてがそのまま使用できるはずです。

If you are still using the old, unmaintained v1 of JMSSerializerBundle, the best way would be to upgrade to v2 of JMSSerializerBundle.

古いメンテナンスされていない JMSSerializerBundle の v1 をまだ使用している場合、最善の方法は JMSSerializerBundle の v2 にアップグレードすることです。

In v1 of JMSSerializerBundle, the serializer alias is registered for the JMS Serializer service by default. However, API Platform requires the Symfony Serializer (and not the JMS one) to work properly. If you cannot upgrade for some reason, this behavior can be deactivated using the following configuration:

JMSSerializerBundle の v1 では、シリアライザー エイリアスはデフォルトで JMS シリアライザー サービスに登録されます。ただし、API プラットフォームが正常に動作するには、Symfony シリアライザー (JMS ではなく) が必要です。何らかの理由でアップグレードできない場合は、次の構成を使用してこの動作を無効にすることができます。

# api/config/packages/jms_serializer.yaml
    enable_short_alias: false

The JMS Serializer service is available as jms_serializer.

JMS シリアライザー サービスは、jms_serializer として利用できます。

Note: if you are using JMSSerializerBundle along with FOSRestBundle and considering migrating to API Platform, you might want to take a look at this guide too.

注: JMSSerializerBundle を FOSRestBundle と一緒に使用していて、API プラットフォームへの移行を検討している場合は、このガイドも参照してください。

"upstream sent too big header while reading response header from upstream" NGINX 502 Error

Some of your API calls fail with a 502 error and the logs for the api container shows the following error message upstream sent too big header while reading response header from upstream.

一部の API 呼び出しは 502 エラーで失敗し、API コンテナーのログには次のエラー メッセージが表示されます。

This can be due to the cache invalidation headers that are too big for NGINX. When you query the API, API Platform adds the ids of all returned entities and their dependencies in the headers like so : Cache-Tags: /entity/1,/dependent_entity/1,/entity/2. This can overflow the default header size (4k) when your API gets larger and more complex.

これは、NGINX には大きすぎるキャッシュ無効化ヘッダーが原因である可能性があります。 API にクエリを実行すると、API プラットフォームは返されたすべてのエンティティの ID とそれらの依存関係を次のようにヘッダーに追加します: Cache-Tags: /entity/1,/dependent_entity/1,/entity/2.これにより、API がより大きく複雑になると、デフォルトのヘッダー サイズ (4k) をオーバーフローする可能性があります。

You can modify the api/docker/nginx/conf.d/default.conf file and set values to fastcgi_buffer_size and fastcgi_buffers that suit your needs, like so:

次のように、api/docker/nginx/conf.d/default.conf ファイルを変更して、必要に応じて値を fastcgi_buffer_size および fastcgi_buffers に設定できます。

server {
    root /srv/api/public;

    location / {
        # try to serve file directly, fallback to index.php
        try_files $uri /index.php$is_args$args;

    location ~ ^/index\.php(/|$) {
        # Comment the next line and uncomment the next to enable dynamic resolution (incompatible with Kubernetes)
        fastcgi_pass php:9000;
        #set $upstream_host php;
        #fastcgi_pass $upstream_host:9000;

        # Bigger buffer size to handle cache invalidation headers expansion
        fastcgi_buffer_size 32k;
        fastcgi_buffers 8 16k;

        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        # When you are using symlinks to link the document root to the
        # current version of your application, you should pass the real
        # application path instead of the path to the symlink to PHP
        # FPM.
        # Otherwise, PHP's OPcache may not properly detect changes to
        # your PHP files (see
        # for more information).
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        # Prevents URIs that include the front controller. This will 404:
        # http://domain.tld/index.php/some-path
        # Remove the internal directive to allow URIs like this

    # return 404 for all other php files not matching the front controller
    # this prevents access to other php files you don't want to be accessible.
    location ~ \.php$ {
      return 404;