Performance and Cache

Enabling the Built-in HTTP Cache Invalidation System #

Exposing a hypermedia API has many advantages. One of them is the ability to know exactly which resources are included in HTTP responses created by the API. We used this specificity to make API Platform apps blazing fast.

When the cache mechanism is enabled, API Platform collects identifiers of every resource included in a given HTTP response (including lists, embedded documents and subresources) and returns them in a special HTTP header called Cache-Tags.

A caching reverse proxy supporting cache tags (e.g. Varnish, Cloudflare, Fastly) must be put in front of the web server and store all responses returned by the API with a high TTL. This means that after the first request, all subsequent requests will not hit the web server, and will be served instantly from the cache.

When a resource is modified, API Platform takes care of purging all responses containing it in the proxy’s cache. This ensures that the content served will always be fresh, because the cache is purged in real time. Support for most specific cases such as the invalidation of collections when a document is added or removed or for relationships and inverse relations is built-in.

Integration with Varnish and Doctrine ORM is shipped with the core library, and Varnish is included in the Docker setup provided with the API Platform distribution. If you use the distribution, this feature works out of the box.

If you don’t use the distribution, add the following configuration to enable the cache invalidation system:

api_platform:
    http_cache:
        invalidation:
            enabled: true
            varnish_urls: ['%env(VARNISH_URL)%']
        public: true
    defaults:
        cache_headers:
            max_age: 0
            shared_max_age: 3600
            vary: ['Content-Type', 'Authorization', 'Origin']

api_platform:
    http_cache:
        invalidation:
            enabled: true
            varnish_urls: ['%env(VARNISH_URL)%']
        public: true
    defaults:
        cache_headers:
            max_age: 0
            shared_max_age: 3600
            vary: ['Content-Type', 'Authorization', 'Origin']

Support for reverse proxies other than Varnish can easily be added by implementing the ApiPlatform\HttpCache\PurgerInterface. Two purgers are available, the http tags (api_platform.http_cache.purger.varnish.ban) or the surrogate key implementation (api_platform.http_cache.purger.varnish.xkey). You can specify the implementation using the purger configuration node, for example to use the xkey implementation:

api_platform:
    http_cache:
        invalidation:
            enabled: true
            varnish_urls: ['%env(VARNISH_URL)%']
            purger: 'api_platform.http_cache.purger.varnish.xkey'
        public: true
    defaults:
        cache_headers:
            max_age: 0
            shared_max_age: 3600
            vary: ['Content-Type', 'Authorization', 'Origin']
            invalidation:
                xkey:
                    glue: ', '

api_platform:
    http_cache:
        invalidation:
            enabled: true
            varnish_urls: ['%env(VARNISH_URL)%']
            purger: 'api_platform.http_cache.purger.varnish.xkey'
        public: true
    defaults:
        cache_headers:
            max_age: 0
            shared_max_age: 3600
            vary: ['Content-Type', 'Authorization', 'Origin']
            invalidation:
                xkey:
                    glue: ', '

In addition to the cache invalidation mechanism, you may want to use HTTP/2 Server Push to pre-emptively send relations to the client.

Extending Cache-Tags for Invalidation #

Sometimes you need individual resources like /me. To work properly with Varnish, the Cache-Tags header needs to be augmented with these resources. Here is an example of how this can be done:

<?php
// api/src/EventSubscriber/UserResourcesSubscriber.php
namespace App\EventSubscriber;

use ApiPlatform\Symfony\EventListener\EventPriorities;
use App\Entity\User;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

final class UserResourcesSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            KernelEvents::REQUEST => ['extendResources', EventPriorities::POST_READ]
        ];
    }

    public function extendResources(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $class = $request->attributes->get('_api_resource_class');

        if ($class === User::class) {
            $resources = [
                '/me'
            ];

            $request->attributes->set('_resources', $request->attributes->get('_resources', []) + (array)$resources);
        }
    }
}

<?php
// api/src/EventSubscriber/UserResourcesSubscriber.php
namespace App\EventSubscriber;

use ApiPlatform\Symfony\EventListener\EventPriorities;
use App\Entity\User;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

final class UserResourcesSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            KernelEvents::REQUEST => ['extendResources', EventPriorities::POST_READ]
        ];
    }

    public function extendResources(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $class = $request->attributes->get('_api_resource_class');

        if ($class === User::class) {
            $resources = [
                '/me'
            ];

            $request->attributes->set('_resources', $request->attributes->get('_resources', []) + (array)$resources);
        }
    }
}

Setting Custom HTTP Cache Headers #

The cacheHeaders attribute can be used to set custom HTTP cache headers:

use ApiPlatform\Metadata\ApiResource;

#[ApiResource(
    cacheHeaders: [
        'max_age' => 60, 
        'shared_max_age' => 120, 
        'vary' => ['Authorization', 'Accept-Language']
    ]
)]
class Book
{
    // ...
}

use ApiPlatform\Metadata\ApiResource;

#[ApiResource(
    cacheHeaders: [
        'max_age' => 60, 
        'shared_max_age' => 120, 
        'vary' => ['Authorization', 'Accept-Language']
    ]
)]
class Book
{
    // ...
}

For all endpoints related to this resource class, the following HTTP headers will be set:

Cache-Control: max-age=60, public, s-maxage=120
Vary: Authorization, Accept-Language

Cache-Control: max-age=60, public, s-maxage=120
Vary: Authorization, Accept-Language

It’s also possible to set different cache headers per operation:

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

#[ApiResource]
#[Get(
    cacheHeaders: [
        'max_age' => 60, 
        'shared_max_age' => 120
    ]
)]
class Book
{
    // ...
}

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

#[ApiResource]
#[Get(
    cacheHeaders: [
        'max_age' => 60, 
        'shared_max_age' => 120
    ]
)]
class Book
{
    // ...
}

Enabling the Metadata Cache #

Computing metadata used by the bundle is a costly operation. Fortunately, metadata can be computed once and then cached. API Platform internally uses a PSR-6 cache. If the Symfony Cache component is available (the default in the API Platform distribution), it automatically enables support for the best cache adapter available.

Best performance is achieved using APCu. Be sure to have the APCu extension installed on your production server. API Platform will automatically use it.

Using PPM (PHP-PM) #

Response time of the API can be improved up to 15x by using PHP Process Manager. If you want to use it on your project, follow the documentation dedicated to Symfony on the PPM website.

Keep in mind that PPM is still in an early stage of development and can cause issues in production.

Doctrine Queries and Indexes #

Search Filter #

When using the SearchFilter and case insensitivity, Doctrine will use the LOWER SQL function. Depending on your driver, you may want to carefully index it by using a function-based index or it will impact performance with a huge collection. Here are some examples to index LIKE filters depending on your database driver.

Eager Loading #

By default Doctrine comes with lazy loading - usually a killer time-saving feature but also a performance killer with large applications.

Fortunately, Doctrine offers another approach to solve this problem: eager loading. This can easily be enabled for a relation: #[ORM\ManyToOne(fetch: "EAGER")].

By default in API Platform, we made the choice to force eager loading for all relations, with or without the Doctrine fetch attribute. Thanks to the eager loading extension. The EagerLoadingExtension will join every readable association according to the serialization context. If you want to fetch an association that is not serializable, you have to bypass readable and readableLink by using the fetchEager attribute on the property declaration, for example:

...

#[ApiProperty(fetchEager: true)]
public $foo;

...

...

#[ApiProperty(fetchEager: true)]
public $foo;

...

Max Joins #

There is a default restriction with this feature. We allow up to 30 joins per query. Beyond that, an ApiPlatform\Exception\RuntimeException exception will be thrown but this value can easily be increased with a bit of configuration:

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        max_joins: 100

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        max_joins: 100

Be careful when you exceed this limit, it’s often caused by the result of a circular reference. Serializer groups can be a good solution to fix this issue.

Fetch Partial #

If you want to fetch only partial data according to serialization groups, you can enable fetch_partial parameter:

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        fetch_partial: true

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        fetch_partial: true

It is disabled by default. If enabled, Doctrine ORM entities will not work as expected if any of the other fields are used.

Force Eager #

As mentioned above, by default we force eager loading for all relations. This behaviour can be modified in the configuration in order to apply it only on join relations having the EAGER fetch mode:

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        force_eager: false

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        force_eager: false

Override at Resource and Operation Level #

When eager loading is enabled, whatever the status of the force_eager parameter, you can easily override it directly from the configuration of each resource. You can do this at the resource level, at the operation level, or both:

<?php
// api/src/Entity/Address.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource]
class Address
{
    // ...
}

<?php
// api/src/Entity/Address.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource]
class Address
{
    // ...
}

<?php
// api/src/Entity/User.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource(forceEager: false)]
class User
{
    #[ORM\ManyToOne(fetch: 'EAGER')]
    public Address $address;

    /**
     * @var Group[]
     */
    #[ORM\ManyToMany(targetEntity: 'Group', inversedBy: 'users')]
    #[ORM\JoinTable(name: 'users_groups')]
    public $groups;

    // ...
}

<?php
// api/src/Entity/User.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource(forceEager: false)]
class User
{
    #[ORM\ManyToOne(fetch: 'EAGER')]
    public Address $address;

    /**
     * @var Group[]
     */
    #[ORM\ManyToMany(targetEntity: 'Group', inversedBy: 'users')]
    #[ORM\JoinTable(name: 'users_groups')]
    public $groups;

    // ...
}

<?php
// api/src/Entity/Group.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\GetCollection;
use Doctrine\ORM\Mapping as ORM;

#[ApiResource(forceEager: false)]
#[Get(forceEager: true)]
#[Post]
#[GetCollection(forceEager: true)]
#[ORM\Entity]
class Group
{
    /**
     * @var User[]
     */
    #[ORM\ManyToMany(targetEntity: 'User', mappedBy: 'groups')] 
    public $users;

    // ...
}

<?php
// api/src/Entity/Group.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\GetCollection;
use Doctrine\ORM\Mapping as ORM;

#[ApiResource(forceEager: false)]
#[Get(forceEager: true)]
#[Post]
#[GetCollection(forceEager: true)]
#[ORM\Entity]
class Group
{
    /**
     * @var User[]
     */
    #[ORM\ManyToMany(targetEntity: 'User', mappedBy: 'groups')] 
    public $users;

    // ...
}

Be careful, the operation level is higher priority than the resource level but both are higher priority than the global configuration.

Disable Eager Loading #

If for any reason you don’t want the eager loading feature, you can turn it off in the configuration:

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        enabled: false

# api/config/packages/api_platform.yaml
api_platform:
    eager_loading:
        enabled: false

The whole configuration described before will no longer work and Doctrine will recover its default behavior.

Partial Pagination #

When using the default pagination, the Doctrine paginator will execute a COUNT query on the collection. The result of the COUNT query is used to compute the last page available. With big collections this can lead to quite long response times. If you don’t mind not having the last page available, you can enable partial pagination and avoid the COUNT query:

# api/config/packages/api_platform.yaml
api_platform:
    defaults:
        pagination_partial: true # Disabled by default

# api/config/packages/api_platform.yaml
api_platform:
    defaults:
        pagination_partial: true # Disabled by default

More details are available on the pagination documentation.

Profiling with Blackfire.io #

Blackfire.io allows you to monitor the performance of your applications. For more information, visit the Blackfire.io website.

To configure Blackfire.io follow these simple steps:

Add the following to your docker-compose.override.yml file:


```yaml
        blackfire:
            image: blackfire/blackfire:2
            environment:
                # Exposes the host BLACKFIRE_SERVER_ID and TOKEN environment variables.
                - BLACKFIRE_SERVER_ID
                - BLACKFIRE_SERVER_TOKEN
                - BLACKFIRE_DISABLE_LEGACY_PORT=1
    ```


```yaml
        blackfire:
            image: blackfire/blackfire:2
            environment:
                # Exposes the host BLACKFIRE_SERVER_ID and TOKEN environment variables.
                - BLACKFIRE_SERVER_ID
                - BLACKFIRE_SERVER_TOKEN
                - BLACKFIRE_DISABLE_LEGACY_PORT=1
    ```

Add your Blackfire.io ID and server token to your .env file at the root of your project (be sure not to commit this to a public repository):


```shell
    BLACKFIRE_SERVER_ID=xxxxxxxxxx
    BLACKFIRE_SERVER_TOKEN=xxxxxxxxxx
    ```

Or set it in the console before running Docker commands:

```shell
    export BLACKFIRE_SERVER_ID=xxxxxxxxxx
    export BLACKFIRE_SERVER_TOKEN=xxxxxxxxxx
    ```


```shell
    BLACKFIRE_SERVER_ID=xxxxxxxxxx
    BLACKFIRE_SERVER_TOKEN=xxxxxxxxxx
    ```

Or set it in the console before running Docker commands:

```shell
    export BLACKFIRE_SERVER_ID=xxxxxxxxxx
    export BLACKFIRE_SERVER_TOKEN=xxxxxxxxxx
    ```

Install and configure the Blackfire probe in the app container, by adding the following to your ./Dockerfile:


```dockerfile
            RUN version=$(php -r "echo PHP_MAJOR_VERSION.PHP_MINOR_VERSION;") \
                && curl -A "Docker" -o /tmp/blackfire-probe.tar.gz -D - -L -s https://blackfire.io/api/v1/releases/probe/php/alpine/amd64/$version \
                && mkdir -p /tmp/blackfire \
                && tar zxpf /tmp/blackfire-probe.tar.gz -C /tmp/blackfire \                        
                && mv /tmp/blackfire/blackfire-*.so $(php -r "echo ini_get('extension_dir');")/blackfire.so \
                && printf "extension=blackfire.so\nblackfire.agent_socket=tcp://blackfire:8307\n" > $PHP_INI_DIR/conf.d/blackfire.ini
    ```


```dockerfile
            RUN version=$(php -r "echo PHP_MAJOR_VERSION.PHP_MINOR_VERSION;") \
                && curl -A "Docker" -o /tmp/blackfire-probe.tar.gz -D - -L -s https://blackfire.io/api/v1/releases/probe/php/alpine/amd64/$version \
                && mkdir -p /tmp/blackfire \
                && tar zxpf /tmp/blackfire-probe.tar.gz -C /tmp/blackfire \                        
                && mv /tmp/blackfire/blackfire-*.so $(php -r "echo ini_get('extension_dir');")/blackfire.so \
                && printf "extension=blackfire.so\nblackfire.agent_socket=tcp://blackfire:8307\n" > $PHP_INI_DIR/conf.d/blackfire.ini
    ```

Rebuild and restart all your containers


```console
    docker compose build
    docker compose up --wait
    ```


```console
    docker compose build
    docker compose up --wait
    ```

For details on how to perform profiling, see the Blackfire.io documentation.

You can also help us improve the documentation of this page.