Magento 2: tipos de cache, clean, flush e cache type próprio

O Magento 2 tem mais de uma dúzia de cache types, e o conselho de sempre quando algo parece errado é dar flush em todos. Funciona, mas também joga fora o trabalho de todos os visitantes desde o último flush e deixa a loja lenta até os caches esquentarem de novo. Saber o que cada cache type guarda permite limpar só o que mudou e entender por que uma alteração não aparece. Este artigo explica os cache types do Magento Open Source e do Adobe Commerce 2.4.8, a diferença entre clean e flush e como adicionar seu próprio cache type.

Listando os cache types

bin/magento cache:status

A saída lista cada cache type pelo código e mostra se ele está habilitado. O admin mostra a mesma lista em System, Tools, Cache Management, com label, descrição e a flag de invalidado. A lista exata depende dos módulos instalados. Uma instalação core 2.4.8 inclui os types abaixo, e extensões podem adicionar os seus.

O que cada cache type guarda

Código	O que guarda	Limpe quando
config	XML de configuração mesclado e valores de system config	O XML de config ou as configurações do admin mudaram
layout	XML de layout mesclado por handle	O XML de layout mudou
block_html	HTML renderizado dos blocks com configuração de cache	A saída do block ou seus dados mudaram
collections	Resultados de collections que usam cache	Os dados de origem mudaram
reflection	Dados de reflection usados pela Web API	As interfaces da API mudaram
db_ddl	Metadados da estrutura das tabelas	O schema do banco mudou
compiled_config	Saída da compilação	Depois da compilação do DI
eav	Tipos de entidade EAV e metadados de atributos	Atributos mudaram
customer_notification	Flags que avisam sessões ativas de clientes para recarregar seus dados	Raramente necessário
config_integration	Configuração de integrações	A config de integração mudou
config_integration_api	Configuração da API de integrações	A config da API de integração mudou
graphql_query_resolver_result	Resultados em cache de alguns resolvers GraphQL	Os dados do resolver mudaram
full_page	Full page cache nativo	O conteúdo da storefront mudou
config_webservice	Configuração da Web API	O webapi.xml mudou
translate	Traduções mescladas	O CSV de tradução ou as traduções inline mudaram

Alguns deles merecem mais detalhe.

config

Este é o mais importante. Ele guarda o resultado mesclado da configuração XML de todos os módulos mais os valores de system configuration do banco. Quase toda request lê dele. Limpar o cache força o Magento a reconstruir a configuração na próxima request, o que é caro. Quando muitos processos tentam reconstruir ao mesmo tempo depois de um clean, aparece um pico curto de carga e de tempo de resposta.

layout e block_html

O cache de layout guarda o XML mesclado para cada combinação de handles, não HTML renderizado. O cache de block HTML guarda a saída de blocks que definem cache keys e lifetimes, como menus e blocks de rodapé. Se você muda um template e não vê mudança na storefront, geralmente é o block_html ou o full_page segurando a saída antiga.

full_page

Este é o full page cache nativo. Quando o Varnish está configurado como aplicação de full page cache, o Magento manda requests de purge ao Varnish quando esse cache type é limpo. Limpar o full_page com Varnish em uso limpa o Varnish, não um storage local. O guia de Varnish explica como funcionam as tags e os purges.

graphql_query_resolver_result

Este type guarda no servidor os resultados de resolvers GraphQL selecionados, separado do cache HTTP de requests GET do GraphQL. Importa para storefronts headless. Veja o guia de cache do GraphQL para entender como as camadas se encaixam.

compiled_config

Guarda a configuração de DI compilada usada em production mode. Depois de rodar setup:di:compile ele é substituído como parte do processo.

Clean versus flush

Esses dois comandos parecem iguais e se comportam de forma bem diferente.

bin/magento cache:clean
bin/magento cache:clean config layout

bin/magento cache:flush

cache:clean remove as entradas do Magento dos cache types informados, ou de todos os types habilitados se você não informar nenhum. Ele trabalha pelas cache tags do Magento, então só toca no que o Magento colocou ali.

cache:flush esvazia por completo o storage de cache por trás dos cache frontends. Com o backend de arquivos isso significa as pastas de cache. Com Redis significa o database configurado. Qualquer outra coisa guardada no mesmo lugar também some. Se outra aplicação ou uma segunda instância do Magento compartilha esse database do Redis, o flush apaga os dados delas.

O admin tem as mesmas duas opções: Flush Magento Cache é um clean, e Flush Cache Storage é um flush. A nomenclatura confunde. No dia a dia, quase sempre o que você quer é o clean. O flush é para quando você suspeita que o próprio storage tem dados velhos que o Magento desconhece.

O status invalidated

Quando você salva certas coisas no admin, como configuração ou atualizações de layout, o Magento marca os cache types afetados como invalidated em vez de limpá-los na hora. O admin mostra uma mensagem dizendo que alguns cache types estão invalidados. Nada é reconstruído até alguém limpar esses types. É uma escolha deliberada para que uma série de mudanças no admin não reconstrua a configuração a cada save. Limpe os types invalidados quando terminar:

bin/magento cache:clean config full_page

Saves de produto, categoria e CMS são diferentes. Eles limpam automaticamente as cache tags específicas das entidades afetadas, então as entradas relacionadas do full page cache são removidas sem ninguém apertar botão.

Habilitando e desabilitando cache types

bin/magento cache:disable block_html full_page
bin/magento cache:enable

O estado habilitado fica guardado em app/etc/env.php, em cache_types. Em produção todo cache type deve estar habilitado. Um cache de config desabilitado, em especial, deixa toda request drasticamente mais lenta.

Em ambiente local, é comum desabilitar block_html, layout e full_page enquanto se trabalha em templates e layout. Funciona, mas esconde bugs de cache, como um block que mostra os dados do cliente errado porque faz cache por página em vez de por cliente. Teste com todos os caches habilitados antes de publicar.

Criando seu próprio cache type

Se o seu módulo guarda dados em cache, por exemplo a resposta de uma API externa ou um cálculo caro, dê a ele um cache type próprio. Assim os admins conseguem vê-lo, desabilitá-lo e limpá-lo de forma independente.

Declare o type em etc/cache.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Cache/etc/cache.xsd">
    <type name="vendor_feed" translate="label,description" instance="Vendor\Feed\Model\Cache\Type\Feed">
        <label>Vendor Feed</label>
        <description>Cached responses from the external feed API</description>
    </type>
</config>

Depois a classe, que agrupa todas as entradas sob uma tag:

<?php
declare(strict_types=1);

namespace Vendor\Feed\Model\Cache\Type;

use Magento\Framework\App\Cache\Type\FrontendPool;
use Magento\Framework\Cache\Frontend\Decorator\TagScope;

class Feed extends TagScope
{
    public const TYPE_IDENTIFIER = 'vendor_feed';
    public const CACHE_TAG = 'VENDOR_FEED';

    public function __construct(FrontendPool $cacheFrontendPool)
    {
        parent::__construct($cacheFrontendPool->get(self::TYPE_IDENTIFIER), self::CACHE_TAG);
    }
}

Para usar, injete a classe do type e verifique se o cache type está habilitado por meio de Magento\Framework\App\Cache\StateInterface:

<?php
declare(strict_types=1);

namespace Vendor\Feed\Model;

use Magento\Framework\App\Cache\StateInterface;
use Magento\Framework\Serialize\SerializerInterface;
use Vendor\Feed\Model\Cache\Type\Feed;

class FeedProvider
{
    public function __construct(
        private readonly Feed $cache,
        private readonly StateInterface $cacheState,
        private readonly SerializerInterface $serializer,
        private readonly FeedClient $client
    ) {
    }

    public function get(string $sku): array
    {
        $key = 'vendor_feed_' . $sku;
        $enabled = $this->cacheState->isEnabled(Feed::TYPE_IDENTIFIER);

        if ($enabled) {
            $cached = $this->cache->load($key);
            if ($cached !== false) {
                return $this->serializer->unserialize($cached);
            }
        }

        $data = $this->client->fetch($sku);

        if ($enabled) {
            $this->cache->save($this->serializer->serialize($data), $key, [Feed::CACHE_TAG], 3600);
        }

        return $data;
    }
}

Depois de habilitar o módulo, rode bin/magento cache:enable vendor_feed para que o novo type fique ativo. Cache types novos nem sempre são habilitados automaticamente em instalações existentes. FeedClient aqui representa a sua própria classe de client da API.

FAQ

Qual a diferença entre cache:clean e cache:flush no Magento 2?

cache:clean remove as entradas do Magento por cache type e tag. cache:flush esvazia o storage de cache inteiro, incluindo qualquer outra coisa guardada no mesmo backend.

Por que o admin diz que alguns cache types estão invalidados?

Alguns saves no admin marcam cache types como invalidated em vez de limpá-los na hora. Limpe esses types quando terminar suas mudanças.

Qual cache type guarda a saída do meu template?

A saída renderizada dos blocks fica no block_html e a página completa fica no full_page, ou no Varnish se você usa. Limpe esses depois de mudar templates.

Algum cache type deve ficar desabilitado em produção?

Não. Todos os cache types devem estar habilitados em produção. Desabilitar o cache de config ou de layout, em especial, deixa toda request mais lenta.

Atendo como freelancer em Magento e Adobe Commerce, incluindo problemas de performance e de cache. Se precisar de ajuda com isso, fale comigo.