Índice de Hooks do WordPress

Um índice pesquisável das actions e filters do WordPress que os desenvolvedores realmente usam — com a assinatura exata de add_action/add_filter, quando dispara, um exemplo funcional e aquilo que costuma pegar as pessoas de surpresa.

39 hooks, com a assinatura exata de add_action / add_filter, quando ele é disparado, um exemplo que funciona e aquele detalhe que pega todo mundo. 1 estão marcados como não verificados — não conferimos a quantidade de argumentos deles no código-fonte do WordPress, e preferimos sinalizar isso a apresentar um palpite como fato.

Isto não é exaustivo e nem pretende ser — o WordPress tem milhares de hooks. Cobrimos aqueles que as pessoas realmente usam.

39 de 39

Roda depois que o WordPress terminou de carregar, mas antes de qualquer cabeçalho ser enviado. O lugar padrão para registrar tipos de post personalizados, taxonomias e regras de reescrita.

Quando dispara

Em toda requisição, no front-end e no admin, depois que o core, os plugins e o tema são carregados.

Assinatura

add_action( 'init', 'my_callback' );

Exemplo

add_action( 'init', function () {
    register_post_type( 'book', array(
        'public'       => true,
        'label'        => 'Books',
        'show_in_rest' => true, // required for the block editor
    ) );
} );

A pegadinha

init roda em TODA requisição, incluindo AJAX, REST e cron. Fazer qualquer coisa lenta aqui (uma requisição HTTP, uma consulta pesada) sobrecarrega cada carregamento de página. Além disso: o usuário atual já está disponível aqui, mas você não pode gerar nenhuma saída — os cabeçalhos ainda não foram enviados, mas estão prestes a ser.

Roda assim que o tema é carregado. O lugar correto para add_theme_support(), add_image_size() e para registrar menus de navegação.

Quando dispara

Depois que o functions.php do tema é carregado, ANTES do init.

Assinatura

add_action( 'after_setup_theme', 'my_callback' );

Exemplo

add_action( 'after_setup_theme', function () {
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'title-tag' );
    add_image_size( 'card', 600, 400, true ); // true = hard crop
} );

A pegadinha

Registrar tamanhos de imagem no init em vez de aqui funciona por acaso na maioria dos casos e depois falha misteriosamente em alguns. Use after_setup_theme — é para isso que ele serve.

Roda quando todos os plugins ativos estão carregados. O ponto seguro mais cedo para interagir com outro plugin.

Quando dispara

Depois que cada arquivo de plugin é incluído, antes de o tema ser carregado.

Assinatura

add_action( 'plugins_loaded', 'my_callback' );

A pegadinha

O usuário atual ainda NÃO está disponível aqui — wp_get_current_user() não vai funcionar de forma confiável. Se você precisa do usuário, use init.

Roda depois que o WordPress está totalmente carregado — plugins, tema, init e o usuário estão todos prontos.

Quando dispara

Depois do init e depois que o usuário atual é configurado.

Assinatura

add_action( 'wp_loaded', 'my_callback' );

Roda no início de toda requisição do admin. Usado para register_setting(), verificações de permissão e redirecionamentos do admin.

Quando dispara

Em toda requisição do lado do admin.

Assinatura

add_action( 'admin_init', 'my_callback' );

A pegadinha

Ele também dispara em requisições do admin-ajax.php, que não são realmente "telas do admin". Se seu callback pressupõe que existe uma tela, proteja-o com wp_doing_ajax().

O único lugar correto para enfileirar CSS e JavaScript do front-end.

Quando dispara

Nos carregamentos de página do front-end, antes de o head ser renderizado.

Assinatura

add_action( 'wp_enqueue_scripts', 'my_callback' );

Exemplo

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'child-style',
        get_stylesheet_uri(),
        array( 'parent-style' ),          // load AFTER the parent
        wp_get_theme()->get( 'Version' )  // cache-bust on version change
    );
} );

A pegadinha

Apesar do nome, ele cuida tanto de ESTILOS quanto de scripts — não existe um hook wp_enqueue_styles, e as pessoas perdem tempo de verdade procurando por um. Além disso: ele não dispara no admin (use admin_enqueue_scripts) nem no editor de blocos (use enqueue_block_editor_assets).

Enfileira CSS/JS no admin. Recebe o sufixo de hook da tela atual, para que você possa carregar recursos em uma única tela.

Quando dispara

Nos carregamentos de páginas do admin.

Assinatura

add_action( 'admin_enqueue_scripts', 'my_callback' ); // receives $hook_suffix

Exemplo

add_action( 'admin_enqueue_scripts', function ( $hook ) {
    if ( 'settings_page_my-plugin' !== $hook ) {
        return; // do not load our JS on every admin screen
    }
    wp_enqueue_script( 'my-admin', plugins_url( 'admin.js', __FILE__ ), array(), '1.0', true );
} );

A pegadinha

Não proteger com base no $hook é a causa isolada mais comum de um plugin quebrar telas do admin sem relação com ele. Carregue seus recursos onde são necessários e em nenhum outro lugar.

Enfileira recursos apenas no editor de blocos (Gutenberg) — não no front-end, não no resto do admin.

Quando dispara

Quando o editor de blocos carrega.

Assinatura

add_action( 'enqueue_block_editor_assets', 'my_callback' );

Imprime saída dentro do <head>. Usado para meta tags e CSS crítico inline.

Quando dispara

Dentro do <head>, no front-end.

Assinatura

add_action( 'wp_head', 'my_callback' );

A pegadinha

NÃO enfileire scripts ou estilos aqui — use wp_enqueue_scripts, que deixa o WordPress cuidar de dependências e deduplicação. Ecoar uma tag <script> dentro do wp_head ignora tudo isso e é por isso que tantos sites carregam o jQuery três vezes.

Imprime saída logo antes do </body>. O lugar certo para trechos de analytics e marcação adiada.

Quando dispara

No final da página do front-end.

Assinatura

add_action( 'wp_footer', 'my_callback' );

A pegadinha

Um tema que esquece de chamar wp_footer() quebra a barra de administração, quebra qualquer plugin que enfileira um script no rodapé e é rejeição automática na revisão de temas do wordpress.org.

Filtra o conteúdo do post imediatamente antes de ele ser exibido. O lugar habitual para acrescentar ou preceder marcação a um post.

Quando dispara

Toda vez que the_content() é chamado.

Assinatura

add_filter( 'the_content', 'my_callback' ); // receives $content

Exemplo

add_filter( 'the_content', function ( $content ) {
    if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
        return $content; // <- the guard everyone forgets
    }
    return $content . '<p class="cta">Enjoyed this? Read more.</p>';
} );

A pegadinha

Isso roda muito mais vezes do que você imagina — em widgets, em respostas REST, na geração de resumo de alguns plugins e uma vez por post em um loop numa página de arquivo. Sem a proteção com is_singular / in_the_loop / is_main_query, seu CTA aparece quinze vezes na página inicial do blog e dentro do feed RSS. Este é o filtro mais mal utilizado do WordPress.

Filtra o título do post antes da exibição.

Quando dispara

Toda vez que the_title() ou get_the_title() é chamado.

Assinatura

add_filter( 'the_title', 'my_callback', 10, 2 ); // receives $title, $post_id

A pegadinha

Ele também dispara para títulos no menu do admin, em menus de navegação e no <title> do documento. Filtrá-lo sem condição vai renomear coisas em lugares que você não pretendia.

Define quantas PALAVRAS um resumo gerado automaticamente contém. O padrão é 55.

Quando dispara

Quando o WordPress gera um resumo para um post que não tem resumo manual.

Assinatura

add_filter( 'excerpt_length', 'my_callback' ); // receives $length (words)

Exemplo

add_filter( 'excerpt_length', function ( $length ) {
    return 25;
}, 999 ); // high priority: many themes set this too, and last one wins

A pegadinha

Ele não tem efeito em posts que têm um resumo MANUAL — esses são usados literalmente. E muitos temas definem esse filtro por conta própria, então você muitas vezes precisa de um número de prioridade alto para vencer.

Muda a string acrescentada a um resumo truncado. O padrão é " […]".

Quando dispara

Quando um resumo gerado automaticamente é truncado.

Assinatura

add_filter( 'excerpt_more', 'my_callback' ); // receives $more

Modifica uma consulta ANTES de ela rodar. A forma correta de mudar o que aparece em uma página de arquivo — muito melhor do que um segundo WP_Query.

Quando dispara

Depois que as variáveis da consulta são analisadas, antes de o SQL ser construído.

Assinatura

add_action( 'pre_get_posts', 'my_callback' ); // receives WP_Query $query (by reference)

Exemplo

add_action( 'pre_get_posts', function ( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return; // <- both guards are mandatory
    }
    if ( $query->is_category() ) {
        $query->set( 'posts_per_page', 12 );
    }
} );

A pegadinha

Ele roda no ADMIN também, e roda para TODA consulta, incluindo menus, widgets e a biblioteca de mídia. Omita as proteções is_admin() e is_main_query() e você vai mudar silenciosamente o que a lista de posts do admin exibe — um bug genuinamente difícil de rastrear até a origem. Note também: modifique $query, não retorne nada.

Filtra a cláusula SQL WHERE bruta de uma consulta.

Quando dispara

Enquanto o SQL da consulta está sendo montado.

Assinatura

add_filter( 'posts_where', 'my_callback', 10, 2 ); // receives $where, WP_Query $query

A pegadinha

Você está escrevendo SQL bruto. Proteja sempre com $query->is_main_query() e use sempre $wpdb->prepare() para qualquer entrada do usuário. Esta é a forma mais rápida de introduzir injeção de SQL em um site WordPress.

Filtra o número total de posts que uma consulta encontrou — que é a partir do qual a paginação é calculada.

Quando dispara

Depois que a consulta roda, antes de a paginação ser calculada.

Assinatura

add_filter( 'found_posts', 'my_callback', 10, 2 ); // receives $found_posts, WP_Query $query

Define o tamanho em pixels acima do qual o WordPress reduz um upload e serve uma cópia "-scaled" em vez do seu original. O padrão é 2560.

Quando dispara

No upload, quando o WordPress decide se uma imagem é "grande".

Assinatura

add_filter( 'big_image_size_threshold', 'my_callback' ); // receives int $threshold

Exemplo

// Serve originals at full resolution — no -scaled copy.
add_filter( 'big_image_size_threshold', '__return_false' );

// Or just raise the ceiling:
add_filter( 'big_image_size_threshold', function () {
    return 3840;
} );

A pegadinha

Esta é a causa isolada mais comum de "minha imagem fica borrada depois de enviar para o WordPress", e quase ninguém sabe que ela existe. Seu original continua no disco — ele simplesmente nunca é servido. Note que se aplica à MAIOR aresta e só afeta imagens enviadas depois que o filtro está ativo.

Filtra o array de tamanhos de imagem que o WordPress está prestes a gerar para um upload. Remova um tamanho para deixar de gerá-lo.

Quando dispara

No upload, antes de os arquivos derivados serem criados.

Assinatura

add_filter( 'intermediate_image_sizes_advanced', 'my_callback', 10, 2 ); // receives $sizes, $metadata

Exemplo

add_filter( 'intermediate_image_sizes_advanced', function ( $sizes ) {
    unset( $sizes['1536x1536'] );
    unset( $sizes['2048x2048'] );
    return $sizes;
} );

A pegadinha

Remover um tamanho que seu tema realmente USA faz o WordPress recorrer ao original em tamanho completo — o que é pior do que o espaço em disco que você economizou. E isso só impede que NOVOS arquivos sejam criados; os existentes permanecem até você regenerá-los.

Define a qualidade JPEG com que o WordPress recodifica as imagens enviadas. O padrão é 82.

Quando dispara

Sempre que o WordPress grava um JPEG.

Assinatura

add_filter( 'jpeg_quality', 'my_callback', 10, 2 ); // receives $quality, $context

A pegadinha

Qualidade 82 é adequada para fotografias e visivelmente ruim para capturas de tela, logos e gráficos planos — esses têm arestas nítidas e nenhum ruído fotográfico para esconder os artefatos. Além disso: wp_editor_set_quality é o filtro mais moderno e cobre diretamente as classes do editor de imagens; definir os dois é comum.

Define a qualidade de saída usada pelas classes WP_Image_Editor (GD e Imagick).

Quando dispara

Quando uma instância do editor de imagens define sua qualidade.

Assinatura

add_filter( 'wp_editor_set_quality', 'my_callback', 10, 2 ); // receives $quality, $mime_type

Adiciona seus tamanhos de imagem personalizados ao menu suspenso de tamanhos na janela de mídia e no editor de blocos.

Quando dispara

Quando a interface de mídia constrói seu seletor de tamanhos.

Assinatura

add_filter( 'image_size_names_choose', 'my_callback' ); // receives $sizes

Exemplo

add_filter( 'image_size_names_choose', function ( $sizes ) {
    return array_merge( $sizes, array( 'card' => __( 'Card', 'textdomain' ) ) );
} );

A pegadinha

add_image_size() registra o tamanho, mas NÃO o torna selecionável no editor. Toda pergunta do tipo "meu tamanho de imagem personalizado não aparece no menu suspenso" é este filtro estar faltando.

Inspeciona ou rejeita um arquivo ANTES de ele ser movido para a pasta de uploads.

Quando dispara

Durante o upload, antes de o arquivo ser gravado.

Assinatura

add_filter( 'wp_handle_upload_prefilter', 'my_callback' ); // receives $file

A pegadinha

Para rejeitar um arquivo, defina $file['error'] com uma string de mensagem e retorne $file. Retornar false ou lançar uma exceção não fará o que você quer.

Filtra o array de metadados (incluindo os tamanhos gerados) depois que um anexo é processado.

Quando dispara

Depois que as imagens derivadas são criadas no upload.

Assinatura

add_filter( 'wp_generate_attachment_metadata', 'my_callback', 10, 2 ); // receives $metadata, $attachment_id

A pegadinha

Este é o hook que os plugins de otimização de imagem usam. Ele pode ser lento — roda depois que cada tamanho de imagem é gravado, e fazer uma requisição HTTP aqui faz todo upload esperar por ela.

Filtra os candidatos de srcset que o WordPress gera para uma imagem responsiva.

Quando dispara

Quando uma imagem responsiva é renderizada.

Assinatura

add_filter( 'wp_calculate_image_srcset', 'my_callback', 10, 5 );

A pegadinha

Remover o tamanho medium_large (768w) em outro lugar degrada silenciosamente o srcset — esse tamanho existe quase inteiramente para servi-lo.

Não verificamos a quantidade exata de argumentos deste hook no código-fonte do WordPress. Consulte developer.wordpress.org antes de confiar nele. Preferimos sinalizar a incerteza a apresentar silenciosamente um palpite como fato.

Registra páginas de menu e submenu do admin.

Quando dispara

Quando o menu do admin está sendo construído.

Assinatura

add_action( 'admin_menu', 'my_callback' );

Exemplo

add_action( 'admin_menu', function () {
    add_options_page(
        'My Plugin',
        'My Plugin',
        'manage_options',   // capability — NOT a role
        'my-plugin',
        'my_render_settings_page'
    );
} );

A pegadinha

O argumento de capability é uma CAPABILITY, não um papel. Passar "administrator" parece funcionar (porque os administradores têm uma capability com esse nome em algumas configurações) e depois concede acesso silenciosamente às pessoas erradas. Use manage_options.

Imprime um aviso no topo de uma tela do admin.

Quando dispara

Na renderização da página do admin.

Assinatura

add_action( 'admin_notices', 'my_callback' );

A pegadinha

Ele dispara em TODA tela do admin. Um plugin que mostra um aviso incondicional de "obrigado por instalar!" em todas elas é o padrão mais odiado do admin do WordPress. Proteja-o e torne-o dispensável.

Roda sempre que um post é criado ou atualizado. O lugar habitual para salvar dados de meta box.

Quando dispara

Depois que um post é gravado no banco de dados.

Assinatura

add_action( 'save_post', 'my_callback', 10, 3 ); // receives $post_id, $post, $update

Exemplo

add_action( 'save_post', function ( $post_id ) {
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
    if ( wp_is_post_revision( $post_id ) ) return;
    if ( ! current_user_can( 'edit_post', $post_id ) ) return;
    // ... now it is safe to save
}, 10, 1 );

A pegadinha

Ele dispara em SALVAMENTOS AUTOMÁTICOS e em REVISÕES, além dos salvamentos reais. Sem as três proteções acima, seus metadados são sobrescritos com valores vazios toda vez que o editor faz um salvamento automático — um bug que parece dados sumindo aleatoriamente.

Registra meta boxes na tela de edição de post.

Quando dispara

Quando a tela de edição é construída.

Assinatura

add_action( 'add_meta_boxes', 'my_callback', 10, 2 ); // receives $post_type, $post

A pegadinha

Meta boxes clássicos não aparecem no editor de blocos, a menos que o editor de blocos recorra ao modo de compatibilidade. Para um site nativo do editor de blocos, registre o post meta com show_in_rest e construa um painel na barra lateral em vez disso.

Roda depois que um usuário faz login com sucesso.

Quando dispara

Na autenticação bem-sucedida.

Assinatura

add_action( 'wp_login', 'my_callback', 10, 2 ); // receives $user_login, WP_User $user

Roda imediatamente depois que um novo usuário é criado.

Quando dispara

No cadastro.

Assinatura

add_action( 'user_register', 'my_callback', 10, 2 ); // receives $user_id, $userdata

Filtra o resultado da autenticação. Retorne um WP_Error para bloquear um login.

Quando dispara

Durante a tentativa de login.

Assinatura

add_filter( 'authenticate', 'my_callback', 30, 3 ); // receives $user, $username, $password

A pegadinha

A prioridade importa muito aqui. O core do WordPress registra suas próprias verificações nas prioridades 20 e 30 — registre cedo demais e você roda antes de a senha sequer ter sido verificada.

Registra rotas e campos REST.

Quando dispara

Quando a API REST inicializa.

Assinatura

add_action( 'rest_api_init', 'my_callback' );

Exemplo

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/items', array(
        'methods'             => 'GET',
        'callback'            => 'my_get_items',
        'permission_callback' => '__return_true', // BE DELIBERATE ABOUT THIS
    ) );
} );

A pegadinha

permission_callback é OBRIGATÓRIO — desde o WP 5.5, omiti-lo gera um aviso, e defini-lo como __return_true torna o endpoint totalmente público. Isso é aceitável para dados genuinamente públicos e uma falha grave para qualquer outra coisa. Decida, não deixe no padrão.

Adiciona um intervalo de recorrência personalizado para wp_schedule_event().

Quando dispara

Quando o WordPress monta sua lista de agendamentos disponíveis.

Assinatura

add_filter( 'cron_schedules', 'my_callback' ); // receives $schedules

Exemplo

add_filter( 'cron_schedules', function ( $schedules ) {
    $schedules['every_five_minutes'] = array(
        'interval' => 300,             // seconds
        'display'  => __( 'Every 5 minutes', 'textdomain' ),
    );
    return $schedules;
} );

A pegadinha

O WP-Cron não é um cron de verdade. Ele só dispara quando alguém visita o site, então um site de pouco tráfego não vai rodar um agendamento de cinco minutos a cada cinco minutos. Se o horário realmente importa, desative o WP-Cron (DISABLE_WP_CRON) e chame o wp-cron.php a partir de um cron de sistema real.

Roda imediatamente depois que um comentário é salvo.

Quando dispara

No envio do comentário.

Assinatura

add_action( 'comment_post', 'my_callback', 10, 3 ); // receives $comment_id, $approved, $commentdata

Filtra os dados do comentário antes de ele ser salvo. Usado para verificações de spam e validação.

Quando dispara

Antes de o comentário ser gravado.

Assinatura

add_filter( 'preprocess_comment', 'my_callback' ); // receives $commentdata

A pegadinha

Para rejeitar um comentário aqui, chame wp_die() com uma mensagem — retornar false não o impede.

Roda na página de pedido recebido depois de um checkout bem-sucedido.

Quando dispara

Quando o cliente chega à página de agradecimento.

Assinatura

add_action( 'woocommerce_thankyou', 'my_callback' ); // receives $order_id

A pegadinha

Este NÃO é um lugar confiável para disparar a preparação do pedido. Ele só dispara se o cliente realmente chegar à página de agradecimento — se ele fechar a aba depois de pagar, nunca roda. Use woocommerce_payment_complete ou um hook de transição de status do pedido para qualquer coisa que precise acontecer.

Gera marcação imediatamente antes do botão de adicionar ao carrinho em uma página de produto.

Quando dispara

Enquanto a página de produto é renderizada.

Assinatura

add_action( 'woocommerce_before_add_to_cart_button', 'my_callback' );

Adiciona, remove ou reordena campos no checkout clássico.

Quando dispara

Quando o formulário de checkout é construído.

Assinatura

add_filter( 'woocommerce_checkout_fields', 'my_callback' ); // receives $fields

A pegadinha

Isso afeta apenas o checkout CLÁSSICO (por shortcode). O checkout mais novo, baseado em blocos, o ignora por completo e é personalizado por Slot & Fill em JavaScript. Isso confunde quase todo mundo na primeira vez.