Os Hooks do WordPress são uma das ferramentas mais importantes a ter no arsenal de um desenvolvedor de WordPress. Eles são a base do plugin WordPress e do desenvolvimento de temas. Você pode usar os muitos hooks embutidos do WordPress para “enganchar” o WordPress Core com seu código personalizado e fazer ou modificar algo.
Existem dois tipos de hooks para WordPress: Ações e Filtros. Os hooks são tão comuns que até mesmo o WordPress Core os utiliza extensivamente. O WordPress também inclui uma forma de você definir seus próprios hooks personalizados para que outros desenvolvedores possam se conectar ao seu código.
Aprender como funcionam as ações, filtros e hooks personalizados é essencial para dominar o desenvolvimento do WordPress.
A primeira metade deste artigo cobre os princípios básicos dos hooks do WordPress e explica como eles funcionam com vários exemplos. Na segunda metade, você aprenderá como usar os hooks para personalizar o WordPress, criar seus próprios hooks personalizados e usá-los para construir seus próprios plugins extensíveis.
Parece excitante? Vamos mergulhar!
O que são hooks WordPress?
Uma página WordPress é montada por toneladas de funções e consultas a banco de dados. O WordPress Core, plugins e tema trabalham em conjunto para produzir os elementos da página como texto, imagens, scripts e estilos. Uma vez totalmente montado, o navegador então os coloca todos juntos e renderiza a página.
Os hooks do WordPress permitem que você ‘entre’ neste processo de compilação em certos pontos e execute seu código personalizado. A principal função dos hooks é permitir que você modifique ou adicione recursos ao WordPress sem tocar nos arquivos principais.
A Plugin API do WordPress potencializa a funcionalidade dos hooks do WordPress. Você usa hooks chamando certas funções do WordPress chamadas Hook Functions em instâncias específicas durante o tempo de execução do WordPress.
Usando funções hooks, você pode agrupar seu código personalizado dentro de uma função de Callback e tê-lo registrado com qualquer hooks. Uma vez registrado, este callback será executado onde quer que os hooks estejam, permitindo que você aumente ou substitua os recursos padrão do WordPress.
A posição dos hooks no processo de execução do código é um fator importante. Você aprenderá mais sobre sua importância nas próximas seções.
Dois tipos de hooks para WordPress: Ações e Filtros
O WordPress inclui dois tipos de hooks chamados Actions e Filters. As Actions permitem que você faça algo em certos pontos pré-definidos no tempo de execução do WordPress, enquanto os Filters permitem que você modifique qualquer dado processado pelo WordPress e o return.
As ações são definidas no código do WordPress como:
do_action( 'action_name', [optional_arguments] );A string action_name é o nome da action. Você pode especificar a variável [optional_arguments] para passar argumentos adicionais para a função callback. Se este campo não for especificado, então seu valor padrão estará vazio.
Exemplo: A ação do_action( 'wp_head' ) pode ser ligada para executar código personalizado toda vez que o WordPress processa o cabeçalho do site. Esta ação não tem nenhum outro argumento.
Os filtros são definidos no código do WordPress como:
apply_filters( 'filter_name', 'value_to_be_filtered', [optional_arguments] );A string filter_name é o nome do filtro, a variável value_to_be_filtered é o valor que precisa ser filtrado e retornado, e a variável [optional_arguments] pode passar argumentos adicionais, assim como com ações.
Exemplo: O filtro apply_filters( 'admin_footer_text' , string $text ) pode ser ligado para modificar o texto exibido no rodapé do administrador. A partir do WordPress 5.4, seu valor padrão exibirá a frase Thank you for creating with WordPress. no rodapé da área admin.
Você aprenderá como se conectar em ações e filtros mais tarde com muitos exemplos do WordPress Core.
Uma vez viciado, você pode direcionar seu código para fazer ou customizar algo em seu site. Por exemplo, você pode usar hooks para enviar um e-mail automático após a publicação de um post, ou carrega rfolhas de estilo personalizadas para mudar a aparência do seu site.
A maneira mais simples de entender os hooks é imaginar o seu site WordPress como a construção de uma casa.
Os hooks são semelhantes ao uso de uma grua para mover itens de construção para frente e para trás. Os itens que estão sendo transferidos são as funções de Callback que incluem seu código personalizado. Estes itens (ou funções) podem ajudar você a construir ou modificar a casa.
As funções de retorno podem ser funções regulares do PHP, funções padrão do WordPress, ou funções personalizadas definidas por você.
Só podemos transportar certos itens em suportes específicos presos a hooks específicos. Assim, as ações só podem ser ganchadas com funções de ação. Da mesma forma, os filtros só podem ser enganchados com Funções de Filtro.
Embora seja tedioso trocar os hooks e suportes em um guindaste, o WordPress torna isso super fácil ao incluir mais de 2.200 tipos de hooks padrão.
Você pode encontrar hooks espalhados pelo WordPress Core, permitindo que você toque na posição exata onde você quer se conectar e executar seu código personalizado.
Hooks vs Ações vs Filtros
Conforme o WordPress Plugin Handbook:
“Hooks são uma forma de um pedaço de código interagir/modificar outro pedaço de código… Existem dois tipos de hooks: Ações e Filtros. ”
Há uma inconsistência generalizada com a forma como os termos Hooks, Ação e Filtro são usados. Alguns tutoriais e guias os misturam com as funções associadas a eles. Uma das principais razões para essa confusão é a natureza complexa de como os hooks funcionam.
Mesmo quando você olha cuidadosamente dentro do WordPress Core, você vai descobrir que não há muita diferença entre adicionar ações e filtros. Aqui está o código fonte para a função add_action() do arquivo wp-includes/plugin.php:
function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
return add_filter( $tag, $function_to_add, $priority, $accepted_args );
}A função add_action() apenas chama a função add_filter() e retorna seu valor. Por que? Porque ambas funcionam fundamentalmente da mesma forma, exceto por uma diferença.
A função apply_filters() retorna um valor que pode alterar os tipos de dados existentes, enquanto a função do_action() não retorna nada (valor NULL no PHP).
Se você ainda estiver confuso, não se preocupe! Assim que você passar da primeira metade deste artigo, tudo ficará claro. Vamos nos ater à terminologia oficial do WordPress Codex, pois ela é clara, precisa e universal.
Por enquanto, familiarize-se com a rotina de Hooks mostrada abaixo.
Vamos quebrar as diferenças entre Ações e Hooks.
| Hooks WordPress | |
| Ações | Filtros |
| As ações são utilizadas para executar funções personalizadas em um ponto específico durante a execução do WordPress Core.. | Os filtros são utilizados para modificar ou personalizar os dados utilizados por outras funções. |
As ações são definidas/criadas pela função do_action( 'action_name' ) no código do WordPress. |
Os filtros são definidos/criados pela função apply_filters( 'filter_name', 'value_to_be_filtered' ) no código do WordPress. |
| As ações também são chamadas de hooks de ação. | Os filtros também são chamados de hooks de filtro. |
As ações só podem ser ligadas com as funções Action. Por exemplo, add_action(), remove_action(). |
Os filtros só podem ser conectados com as funções de Filtro. Por exemplo, add_filter(), remove_filter(). |
| Funções de ação não precisam passar nenhum argumento para suas funções de chamada de retorno. | Funções de filtro precisam passar pelo menos um argumento para suas funções de callback. |
| Funções de ação podem realizar qualquer tipo de tarefa, incluindo a mudança do comportamento de como o WordPress funciona. | As funções de filtro só existem para modificar os dados passados a eles pelos filtros. |
Funções de ação não devem return nada. Entretanto, elas podem echo a saída ou interagir com o banco de dados. |
As funções de filtro devem return suas alterações como saída. Mesmo que uma função de filtro não mude nada, ela ainda deve return a entrada não modificada. |
| As ações podem executar quase tudo, desde que o código seja válido. | Os filtros devem funcionar de forma isolada, para que não tenham nenhum efeito colateral não intencional. |
| Resumo: Uma ação interrompe o processo normal de execução do código para fazer algo com as informações que recebe, mas não devolve nada de volta, e depois sai. | Resumo: Um filtro modifica a informação que recebe, retorna para a função do Hooks de chamada e outras funções podem usar o valor que ele retorna. |
Às vezes, você pode usar tanto uma ação quanto um filtro para atingir o mesmo objetivo. Por exemplo, se você quiser modificar o texto em um post, você pode registrar uma função de callback com a ação publish_post e alterar o conteúdo do post quando ele estiver sendo salvo no banco de dados.
// define the callback function to change the text
function change_text_callback() {
// add the code to change text here
}
// hook in to the 'publish_post' action with the add_action() function
add_action( 'publish_post', 'change_text_callback' );Ou você pode registrar outra função de callback com o filtro the_content para modificar o conteúdo do post antes que ele seja exibido no navegador.
// define the callback function to modify the text
function change_text_another_callback( $content ) {
// add the code to change text here and then return it
return $filtered_content;
}
// hook in to 'the_content' filter with the add_filter() function
add_filter( 'the_content', 'change_text_another_callback');Duas abordagens diferentes com o mesmo resultado. Saber quando usar uma sobre a outra é fundamental para ser um bom desenvolvedor do WordPress.
Como funcionam os hooks do WordPress?
O exemplo da casa foi simples o suficiente para entender o funcionamento básico dos hooks, mas não capta a complexidade de como eles funcionam. Mais importante ainda, os conceitos de posição e especificidade dos hooks.
Um exemplo melhor seria imaginar processar uma página web WordPress como montar um carro. Ao contrário da fabricação de um carro, que leva tempo, a montagem de uma página da web é quase instantânea.
Assim como um carro é montado peça por peça em uma moderna linha de montagem, uma página web WordPress é montada elemento por elemento pelo servidor e pelo cliente.
O WordPress Core é como o motor do carro, chassis e outros essenciais, potencializando a funcionalidade “core” do site.
Você pode ter um site funcional apenas com o WordPress Core, mas onde está a graça nisso? Você precisa adicionar recursos empolgantes ao site. É aí que entram os plugins e temas do WordPress, ambos usando hooks extensivamente.
No exemplo acima, cada estação numerada é como um Hooks dentro do WordPress Core. Existem dois tipos de estações, como ações e filtros. Cada estação inclui um tipo específico de slot que aceita apenas certas ferramentas, semelhantes a funções de ação e funções de filtro.
Todas as estações são colocadas em intervalos freqüentes para modularidade e eficiência.
Dependendo da necessidade em uma determinada posição, podemos acoplar (ou enganchar) a ferramenta mais apropriada para o trabalho naquela estação específica. Estas ferramentas são como as funções de callback utilizadas para interagir ou modificar o WordPress.
Algumas ferramentas podem alterar significativamente o funcionamento do carro, como os callbacks registrados para ações. Outras ferramentas são utilizadas apenas para personalizar a aparência do carro, como as callbacks registradas em filtros.
Usar as ferramentas certas nas estações certas é crucial para construir um carro de primeira linha. Da mesma forma, os hooks nos ajudam a personalizar o WordPress de acordo com nossas necessidades únicas.
Se você estender esta analogia, os plugins são como adicionar recursos úteis para automóveis, como airbags, console de entretenimento, sistema remoto sem chave, etc (como estes par amelhorar a funcionalidade do WooCommerce). Os temas são análogos para personalizar a parte visual do carro, como o design geral, pintura, jantes, etc. (veja aqui como customizar seu tema do WordPress).
Onde registrar os hooks e suas funções?
Existem duas formas recomendadas de adicionar hooks no WordPress:
- Plugins: Faça seu próprio plugin e adicione todo o seu código personalizado dentro dele.
- Tema Filho (Child Theme): Registre as funções de hooks e callback no arquivo
functions.phpdo seu tema filho.
Para este tutorial, vamos começar criando um plugin. Para isso, crie uma nova pasta no seu diretório /wp-content/plugins/plugins/.
Eu estou nomeando os meus plugin salhooks, mas você pode nomear o que quiser. De acordo com as diretrizes do WordPress, você precisa criar um arquivo PHP com o mesmo nome (salhooks.php) dentro do seu diretório de plugins.
Adicione os seguintes campos de cabeçalho ao seu arquivo de plugin para registrá-lo no WordPress. Você pode saber mais sobre os requisitos de cabeçalho do plugin no WordPress Codex.
<?php
/*
Plugin Name: Salhooks
Version : 1.0
Description: Demonstrating WordPress Hooks (Actions and Filters) with multiple examples.
Author : Salman Ravoof
Author URI : https://www.salmanravoof.com/
License : GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: salhooks
*/
//=================================================
// Security: Abort if this file is called directly
//=================================================
if ( !defined('ABSPATH') ) {
die;
}Salve este arquivo e depois ative o plugin no se upainel do WordPress. Eu estarei usando este plugin dentro de uma instalação local do WordPress para demonstrar como funcionam os hooks.
Como uma nota lateral, você também pode editar os arquivos do WordPress Core diretamente para registrar os hooks. Entretanto, não é recomendado, pois todo o seu código personalizado será sobrescrito toda vez que você atualizar o WordPress. Você não deve adicionar hooks dentro do seu tema pai pelo mesmo motivo.
Usando os Hooks do WordPress
Hooks WordPress por si só não faz nada. Ele apenas se senta no código, esperando por alguma função Hooks para ativá-lo. Para fazer uso de um Hook, você precisa chamar pelo menos 2 outras funções.
Primeiro, você precisa registrar os Hooks com uma função de Hooks e referenciar uma função de chamada de retorno dentro dele. E então você precisa definir a função de callback que você mencionou anteriormente na função Hooks. O WordPress irá executar esta função de callback toda vez que o Hooks for disparado.
A ordem em que você define estas funções não importa, mas é uma boa idéia colocá-las próximas umas das outras.
As ações e filtros têm funções de Hooks distintas. A partir de agora, vamos nos referir a elas como funções de ação e funções de filtro. Como você verá, elas têm seus próprios requisitos de sintaxe e parâmetros.
Ganhar uma ação
As ações fornecem uma maneira de executar seu código personalizado em um determinado ponto na execução do WordPress Core, plugins ou temas.
A função add_action() Ação
Você pode registrar uma função de callback com uma ação, seguindo estes passos:
- Defina uma função de Callback com o seu código personalizado dentro dela. Esta função de Callback será executada quando qualquer ação registrada for disparada durante a execução do código do WordPress.
- Prenda sua função callback à ação que você deseja com a função
add_action(). Conforme o Codex WordPress, a função add_action() precisa passar pelo menos dois parâmetros:- Nome da ação a ser tomada.
- Nome da função de callback que será executada quando a ação for acionada.
- A função
add_action()também aceita dois parâmetros opcionais para definir aprioritye onumber of arguments. Discutiremos os dois mais tarde.
É uma boa prática nomear os parâmetros da sua função de callback o mais próximo possível dos parâmetros passados pela função de Hooks.
Vamos ver um exemplo de utilização da função add_action().
// define the callback function, the arguments are optional
function example_callback( $arg1, $arg2 ) {
// make your code do something with the arguments
}
// hook the callback function to the 'example_action'
add_action( 'example_action', 'example_callback', [priority], [no_of_args] );
// 'priority' and 'number of arguments' are optional parametersExemplo de Engatar uma Ação
O WordPress inclui uma ação interna chamada init que dispara após o WordPress ter terminado de carregar e autenticar o usuário, mas antes de qualquer cabeçalho ser enviado. Muitos plugins usam este Hook como ponto de partida para instanciar seu código, pois quase todos os principais recursos do WordPress terminaram de carregar até o momento em que o WordPress executa esta ação.
O WordPress tem uma ação similar chamada admin_init. Ela dispara enquanto a tela de admin está sendo inicializada, enquanto a ação init dispara somente após o WordPress ter terminado de carregar.
Vamos executar um código personalizado para echo uma mensagem simples durante a execução da ação de init. Veja como fazer isso:
function custom_callback_function(){
// add your custom code here to do something
echo 'I will be fired on WordPress initialization';
}
add_action( 'init', 'custom_callback_function' );Você pode ver a mensagem sendo ecoada no canto superior esquerdo da minha instalação local do WordPress.
Encontrando Ações Suportadas pelo WordPress
O WordPress inclui ações toda vez que ele faz algo, como o login de um usuário ou a publicação de um novo post. Você pode encontrar uma lista completa de todas as ações executadas pelo WordPress na página Plugin API/Action Reference.
O Codex dividiu todas as ações ali listadas em várias categorias e as organizou da primeira à última na ordem de execução do WordPress.
Na maioria dos casos, muitas dessas ações não fazem nada, pois nada está ligado a elas. Mas se você precisar delas, elas estão lá para você se ligar a elas.
Sentindo-se um pouco sobrecarregado com todas as ações? É natural. À medida que você ganha mais experiência e passa pelo código fonte do WordPress Core, fica mais fácil encontrar o Hook perfeito para as suas necessidades. Basta fazer uma busca pelo termo “do_action” e você vai encontrar muitas ações que você pode se conectar.
Parâmetros adicionais para add_action()
A função add_action() pode aceitar mais dois parâmetros: um para definir a priority e o outro para definir o number of arguments. Enquanto eles são opcionais, se usados corretamente, podem ser super úteis.
Priority
O primeiro parâmetro adicional suportado pela função add_action() define a priority. Este parâmetro só pode ser um número inteiro positivo. Quanto menor o número de priority, mais cedo a função será executada. Seu valor padrão é 10 se você não especificá-lo.
Para ver como funciona, vamos registrar três funções de callback para a ação de init, mas cada uma com prioritys diferentes.
// priority is set to 9, which is lower than 10, hence it ranks higher
add_action( 'init', 'i_am_high_priority', 9 );
// if no priority is set, the default value of 10 will be used
add_action( 'init', 'i_am_default_priority');
// priority is set to 11, which is higher than 11, hence it ranks lower
add_action( 'init', 'i_am_low_priority', 11 );Nos exemplos acima, a função de callback com o menor número de priority será a primeira e a com o maior número será a última. Se suas prioritys forem as mesmas, então elas serão executadas na ordem em que você as registra.
A priority tem um papel importante quando um único Hook pode ter múltiplas funções de callback registradas com ele. Para evitar resultados inesperados, você pode definir uma priority para cada função de callback, para que eles disparem na ordem em que você quiser.
Number of Arguments
Por padrão, qualquer função de callback registrada através da função add_action() receberá apenas um argumento. Entretanto, algumas vezes você pode precisar passar dados extras para a função de callback.
Por esta razão a função add_action() aceita um parâmetro opcional para definir o number of arguments.
Um ótimo exemplo para mostrar isso é a ação comment_post. Esta ação é executada imediatamente após o WordPress adicionar um comentário ao banco de dados. Se você não definir o parâmetro number of arguments, ele passará apenas um único valor para a função callback, que neste caso será o comment_ID.
// register the hook with 'priority' and 'number of arguments' parameters
add_action( 'comment_post', 'show_message_function', 10, 3 );
// define the callback function
function show_message_function( $comment_ID, $comment_approved, $commentdata ) {
// check whether a comment is approved with the second parameter
if( 1 === $comment_approved ){
// runs the code only if the comment is approved
}
}Se você definir o parâmetro number of arguments para 3 como no exemplo acima, a função action passará três valores: comment_ID, comment_approved, e commentdata.
WordPress define o valor do comment_approved como 1 para comentários aprovados, 0 se não aprovado, e ‘spam‘ se o comentário for marcado como spam.
A variável commentdata é um array que inclui todos os dados do comentário, como nome do autor do comentário, endereço de e-mail, site e o conteúdo do comentário em si. Você pode conferir o Codex WordPress para encontrar todos os pares de valores-chave incluídos no array ‘commentdata’.
Você pode ter quantos argumentos você quiser, mas a função callback e a função add_action() precisam especificar o mesmo number of arguments.
Ao passar parâmetros adicionais para a função de callback, você pode fazer mais com o seu código. Por exemplo, você pode verificar se um comentário é aprovado ou não e enviar automaticamente o texto do comentário para o administrador, se for aprovado. Não é possível fazer isso sem especificar os argumentos adicionais, pois sua função de callback não terá acesso aos dados do comment_content.
Se você não quer definir a priority, mas quer apenas mudar o number of arguments, você ainda precisa definir uma priority. Basta usar seu valor padrão (i.e. 10).
Como o WordPress Core Utiliza as Ações
O próprio WordPress Core utiliza muitas de suas ações embutidas para realizar várias funções.
Pegue a ação wp_head, por exemplo. Ela é disparada quando o WordPress está emitindo a seção de cabeçalho das páginas web (o código que vai entre < head> e </head> ).
Você pode encontrar a maioria das funções de ação do WordPress Core relacionadas com o Hook wp_head no arquivo wp-includes/default-filters.php. Eu pesquisei o código e compilei uma lista de todas as funções add_action() que invocam a ação wp_head.
add_action( 'wp_head', 'rest_output_link_wp_head', 10, 0 );
add_action( 'wp_head', '_wp_render_title_tag', 1 );
add_action( 'wp_head', 'wp_enqueue_scripts', 1 );
add_action( 'wp_head', 'wp_resource_hints', 2 );
add_action( 'wp_head', 'feed_links', 2 );
add_action( 'wp_head', 'feed_links_extra', 3 );
add_action( 'wp_head', 'rsd_link' );
add_action( 'wp_head', 'wlwmanifest_link' );
add_action( 'wp_head', 'adjacent_posts_rel_link_wp_head', 10, 0 );
add_action( 'wp_head', 'locale_stylesheet' );
add_action( 'wp_head', 'noindex', 1 );
add_action( 'wp_head', 'print_emoji_detection_script', 7 );
add_action( 'wp_head', 'wp_print_styles', 8 );
add_action( 'wp_head', 'wp_print_head_scripts', 9 );
add_action( 'wp_head', 'wp_generator' );
add_action( 'wp_head', 'rel_canonical' );
add_action( 'wp_head', 'wp_shortlink_wp_head', 10, 0 );
add_action( 'wp_head', 'wp_custom_css_cb', 101 );
add_action( 'wp_head', 'wp_site_icon', 99 );
add_action( 'wp_head', 'wp_no_robots' );Isso é um monte de funções de callback ligadas a apenas uma ação. Definir a priority aqui é crucial para garantir que as funções mais importantes do Hook funcionem primeiro.
No exemplo acima, carregar os scripts com a função callback wp_enqueue_scripts() é mais importante (priority = 1) do que carregar as meta tags do ícone do site com a função callback wp_site_icon() (priority = 99).
Outras Funções de Ação
Enquanto add_action() é a função de ação mais utilizada, existem muitas outras que são igualmente úteis. Vamos ver como todos eles funcionam.
Esta função de ação verifica se uma ação foi enganchada. Ela aceita dois parâmetros. O primeiro é o nome da ação. O segundo parâmetro é opcional e é o nome da função callback.
has_action( 'action_name', 'function_to_check' );Se você especificar apenas o primeiro parâmetro, ele retorna true se alguma função estiver ligada ao parâmetro action_name.
Mas se você também especificar o segundo parâmetro, ele retornará false se a função de callback especificada não estiver registrada para a ação mencionada.
Se encontrar a função de callback anexada ao Hook de ação, no entanto, ele retornará a priority (um número inteiro) definida para essa função neste Hook de ação.
Nós já encontramos essa função de ação antes. O WordPress a utiliza para definir todas as suas ações padrão, permitindo que outras funções se conectem a elas. Assim como o WordPress, você também pode usar a função do_action() para criar uma nova ação personalizada, especificando um novo nome de ação como parâmetro.
do_action( 'action_name', [argument1], [argument2] );Só declarar esta função não fará nada por si só. Mas vai sentar-se no código, esperando que outras funções de ação a ativem. Passar qualquer argumento extra é opcional, mas é importante se você quiser que suas funções de retorno as utilizem.
Esta função de ação é idêntica a do_action(), exceto por uma diferença. Qualquer argumento passado por ela deve ser um array. Quando você tem muitos argumentos para passar ou seus argumentos já estão em um array, esta função é super útil.
// here's an example array
$arguments_array = array( 'arg_1', 'foo', true, 'arg_4' );
do_action_ref_array( 'example_action', $arguments_array );Como as arrays PHP são um mapa ordenado, certifique-se de que os argumentos que você passa estejam na ordem certa.
Um exemplo da utilização desta função de ação é a ação admin_bar_menu. Ela pode ser ligada para adicionar, manipular, ou remover os vários itens da barra admin. Todos os itens da barra de admin são definidos como elementos de um array.
Se você quiser contar o número de vezes que qualquer ação é disparada, você pode invocar esta função de ação.
did_action( 'action_name' );Esta função retorna um valor inteiro.
A função did_action() é extremamente útil quando você quer executar uma função de callback apenas na primeira vez que uma ação é executada e nunca mais.
function example_callback_function() {
if( did_action( 'example_action' ) === 1 ) {
// checks if the 'example_action' hook is fired once, and only runs then, and never again!
}
}
add_action('example_action', 'example_callback_function');Esta função de ação remove uma função de retorno de chamada ligada à ação especificada. Por exemplo, você pode usar esta função para remover as funções padrão do WordPress enganchadas em ações internas e substituí-las pelas suas próprias.
remove_action( 'action_name', 'function_to_be_removed', [priority] );Existem alguns pré-requisitos para chamar a função remove_action():
- A
function_to_be_removede os parâmetros deprioritydevem ser os mesmos que os usados originalmente na funçãoadd_action(). - Você não pode chamar a função
remove_action()diretamente. Você precisa chamá-la de dentro de outra função. - Se a função callback for registrada de uma classe, então a remoção tem outros requisitos. Você pode conferir a documentação do WordPress Codex para mais detalhes.
- Não é possível remover a função de retorno de chamada antes ou depois do seu registro.
Aqui está um exemplo de como o WooCommerce usa esta função de ação para remover a miniatura padrão do produto na página principal da loja.
remove_action( 'woocommerce_before_shop_loop_item_title', 'woocommerce_template_loop_product_thumbnail', 10 );Esta função de ação remove tudo o que está ligado a uma ação. O parâmetro de priority é opcional.
remove_all_actions( 'action_name', [priority] );Lembre-se que esta função não pode ser chamada a partir da ação da qual você gostaria de desregistar funções de callback. Isso causaria um loop infinito. Você pode se conectar a uma ação que foi disparada anteriormente para executar esta função sem erros.
Esta função de ação verifica se a ação especificada está sendo executada ou não. Ela retorna um valor booleano (true ou false).
// check whether the 'action_name' action is being executed
if ( doing_action( 'action_name' ) ) {
// execute your code here
}Você pode deixar o parâmetro action_name vazio para verificar se alguma ação está sendo executada. Ele retornará true toda vez que qualquer action for disparada.
// check if any action is running and do something
if ( doing_action() ) {
// the code here is run when any action is fired
}Exemplo de Ações 1: Mostrar uma Mensagem de Manutenção para os Visitantes do Seu Site
Às vezes, o melhor é desconectar seu site e colocar uma página em Manutenção. Felizmente, o WordPress fornece uma maneira fácil de fazer exatamente isso.
// show a maintenance message for all your site visitors
add_action( 'get_header', 'maintenance_message' );
function maintenance_message() {
if (current_user_can( 'edit_posts' )) return;
wp_die( '<h1>Stay Pawsitive!</h1><br>Sorry, we\'re temporarily down for maintenance right meow.' );
}Vamos quebrar o código e passar por cada passo:
- get_header é uma ação que é acionada antes que o arquivo de template do cabeçalho do site carregue. É uma ação perfeita para ser acionada se você quiser interromper o carregamento do site principal.
- Conecte-se à ação
get_headerusando a funçãoadd_action()com a função callback damaintenance_message(). - Defina a função
callback_message()de manutenção. current_user_can( 'edit_posts') é uma função de teste de capacidade do usuário que verifica se o usuário atual está logado e pode editar mensagens. Todo usuário registrado em um site WordPress, exceto aqueles com funções de Assinante, tem a capacidade de editar posts. Existem outras formas robustas de realizar esta verificação, mas vamos manter este método simples aqui.- Use a função wp_die() padrão para matar a execução do WordPress com graça e exibir uma página HTML com uma mensagem de erro. Você pode usar a sintaxe HTML no parâmetro da mensagem de erro para formatá-la.
Depois de salvar o código no meu plugin personalizado, carreguei minha instalação local do WordPress no modo de navegação privada. A página Em Manutenção é um sucesso!
O site é carregado com sucesso se eu estiver logado enquanto passa no teste de capacidade do usuário. Agora você pode continuar trabalhando na correção do seu site enquanto ele mostra aos visitantes regulares esta página.
Exemplo de Ações 2: Ocultar itens do menu Painel de Controle de Usuários Não-Admin
Se você está rodando um blog multi-autor ou gerenciando um site para seus clientes, então você pode precisar esconder certos menus de administração do painel de controle do WordPress para usuários não-administradores. Você pode fazer isso se conectando na ação admin_menu.
// remove specific dashboard menus for non-admin users
add_action( 'admin_menu', 'hide_admin_menus' );
function hide_admin_menus() {
if (current_user_can( 'create_users' )) return;
if (wp_get_current_user()->display_name == "Salman") return;
remove_menu_page( 'plugins.php' );
remove_menu_page( 'themes.php' );
remove_menu_page( 'tools.php' );
remove_menu_page( 'users.php' );
remove_menu_page( 'edit.php?post_type=page' );
remove_menu_page( 'options-general.php' );
}Aqui está um passo-a-passo do trecho de código acima:
- admin_menu é uma ação que é acionada antes que o menu admin carregue na área do painel de controle do WordPress.
- Conecte-se à ação
admin_menuusando a funçãoadd_action()usando a funçãohide_admin_menus()callback. - A função
hide_admin_menus()callback define a lógica do código. Ela é executada toda vez que a açãoadmin_menué acionada. - Dentro da função callback, a função
current_user_can( 'create_users' )verifica se o usuário logado é um administrador. Como apenas os administradores do site têm a capacidade decreate_user, a função termina com um comando dereturnse o usuário for um administrador. - A função wp_get_current_user() do WordPress recupera o objeto do usuário atual. Com esta função, podemos verificar se o usuário logado tem um conjunto particular de
display_name. Esta é uma linha opcional, caso você queira omitir certos usuários não-administrados de serem bloqueados devido a esta função de callback. - A função remove_menu_page() do WordPress remove menus de administração de nível superior. No exemplo de código acima, eu estou removendo os seguintes menus de administração: Plugins, Temas, Ferramentas, Usuários, Páginas, e Opções.
Após salvar o arquivo do plugin, aqui está um instantâneo do painel de controle do WordPress com um administrador logado.
E aqui está uma captura de tela do painel do WordPress com um usuário não-administrado logado.
Esta solução esconde apenas os itens do menu de administração especificados de aparecerem no painel do WordPress. Todos os usuários ainda podem acessá-los entrando com as URLs do menu em seus navegadores.
Para desabilitar certas funções do usuário de acessar menus específicos, você precisa editar suas capacidades.
Filtragem
Os filtros fornecem uma maneira para que seu código personalizado modifique os dados utilizados por outras funções do WordPress. Ao contrário das ações, as funções ligadas aos filtros precisam retornar um valor.
A função de filtro add_filter()
Você pode ligar uma função de callback a um filtro, seguindo estes passos:
- Defina uma função de Callback que será executada quando o WordPress disparar o filtro. Funções de Callback para filtros precisam ter pelo menos um argumento especificado, já que todos os filtros passam pelo menos um valor para suas funções de callback.
- Registre a função callback em um filtro com a função
add_filter(). O filtro se encarregará de chamar a função de callback. Conforme o Codex WordPress, a função add_filter() precisa passar pelo menos dois parâmetros:- Nome do filtro a ser conectado.
- Nome da função de callback que funcionará quando o filtro disparar.
- A função
add_filter()também aceita dois parâmetros opcionais adicionais para definir aprioritye onumber of arguments. Estes parâmetros funcionam da mesma forma que com a funçãoadd_action().
Aqui está um exemplo de como você pode usar a função add_filter() para enganchar uma função de callback para um filtro.
// define the filter callback function with at least one argument passed
// the number of arguments that you can pass depends on how the filter is defined
function filter_callback_function( $arg1, $arg2 ) {
// make your code do something with the arguments and return something
return $something;
}
// now hook the callback function to the 'example_filter'
add_filter( 'example_filter', 'filter_callback_function', [priority], [no_of_args] );
// '10' is the default priority set for the callback function
// and '1' is the default number of arguments passedExemplo de Filtragem
O WordPress fornece um filtro chamado login_message para filtrar a mensagem exibida na página de login acima do formulário de login. O valor retornado por este filtro pode ter uma marcação HTML.
Vamos conectar no filtro de login_message e modificar a mensagem mostrada na tela de login.
// show a custom login message above the login form
function custom_login_message( $message ) {
if ( empty( $message ) ) {
return "<h2>Welcome to Let's Develop by Salman Ravoof! Please log in to start learning.</h2>";
}
else {
return $message;
}
}
add_filter( 'login_message', 'custom_login_message' );A instrução if-else na função de retorno de chamada verifica se a mensagem de login já está definida, na maioria das vezes por outro plugin ou tema. Nesses casos, a função callback retorna o valor original sem alterações. Esta é uma forma de evitar conflitos com outros plugins ou temas.
Você pode ver a mensagem sendo exibida acima do formulário de login na página de login do WordPress.
Você pode estilizar todos os elementos da página de login, consultando as folhas de estilo personalizadas. Fazendo isso, você poderá personalizar totalmente sua página de login padrão do WordPress.
Você aprenderá como carregar folhas de estilo personalizadas usando ações na seção “Personalizar a Página de Login do WordPress com Hooks”.
Encontrando Filtros Suportados pelo WordPress
Em qualquer lugar onde o WordPress processa ou modifica dados, você pode quase certamente encontrar um filtro para se conectar e mudá-los. Pense em filtros como uma interface entre o banco de dados do WordPress e o navegador.
Você pode encontrar uma lista exaustiva de todos os filtros suportados pelo WordPress na página Plugin API/Filter Reference.
Todos os filtros ali listados são divididos em múltiplas categorias e dispostos de cima para baixo na ordem de execução do WordPress.
Se você quiser encontrar filtros para se conectar no código fonte do WordPress, faça uma busca pelo termo “apply_filters” e você terá toneladas de resultados. O Código de Referência do WordPress também é um ótimo lugar para procurar por tudo que está incluído no WordPress, incluindo ações e filtros.
Como o WordPress Core Utiliza os Filtros
O próprio WordPress Core utiliza muitos de seus filtros embutidos para modificar os dados utilizados pelas suas diversas funções.
Considere the_content filter, por exemplo. Ele filtra o conteúdo do post após ser recuperado do banco de dados e antes de ser exibido no navegador.
Assim como nas ações, você pode encontrar a maioria das funções de filtro do WordPress Core relacionadas ao_content hook no arquivo wp-includes/default-filters.php.
Aqui está uma lista de todas as funções do núcleo add_filter() que se encaixam no filtro_content:
add_filter( 'the_content', 'do_blocks', 9 );
add_filter( 'the_content', 'wptexturize' );
add_filter( 'the_content', 'convert_smilies', 20 );
add_filter( 'the_content', 'wpautop' );
add_filter( 'the_content', 'shortcode_unautop' );
add_filter( 'the_content', 'prepend_attachment' );
add_filter( 'the_content', 'wp_make_content_images_responsive' );
add_filter( 'the_content', 'do_shortcode', 11 ); // AFTER wpautop(). Observe a priority especificada para certas funções de callback.
Por exemplo, a função do_blocks() analisa quaisquer blocos dinâmicos no conteúdo do post e os torna compatíveis com o novo editor de blocos do WordPress. É especificada uma priority maior do que o padrão (10) para garantir que o conteúdo esteja pronto para o bloco antes que as outras funções sejam executadas.
A função convert_smilies() é definida para rodar com menor priority, pois sua tarefa é converter smileys de texto em sprites de imagem. Ter ele rodando no final após filtrar todo o conteúdo do post faz sentido.
Fato engraçado: Os códigos curtos são um subconjunto de filtros. Eles recebem a entrada do atalho, processam e retornam a saída de volta para ele. Saiba mais sobre atalhos neste guia final do WordPress Shortcodes.
Outras Funções do Filtro
Enquanto add_filter() é a função de filtro mais utilizada, existem muitas outras funções de filtro úteis. Vamos discuti-las todas em profundidade.
Esta função verifica se o filtro especificado está viciado por alguma função. Ela aceita dois parâmetros. O primeiro parâmetro é para inserir o nome do filtro. O segundo parâmetro é opcional e é para inserir o nome da função callback.
has_filter( 'filter_name', 'function_to_check' );Se você especificar apenas o primeiro parâmetro, ele retornará true se o filter_name estiver viciado por qualquer função.
Entretanto, se você especificar ambos os parâmetros, então ele retornará false se a função callback mencionada não for registrada com o filtro dado. Se encontrar a função de callback registrada com o filtro, então retornará a priority (um número inteiro) definida para aquela função neste filtro.
Uma possível aplicação da função has_filter() é verificar se algum filtro já foi viciado, e com base nisso avançar com a execução do código.
// check to see if 'the_content' filter has been hooked
if ( ! has_filter( 'the_content' ) {
// hook the filter if and only if it hasn't been hooked before
add_filter( 'the_content', 'modify_the_content' );
}Esta função de filtro é como a função do_action() action. Qualquer função de callback ligada a este filtro será executada onde quer que esta função esteja no código do WordPress.
Você também pode usar esta função para criar um novo filtro personalizado, especificando o nome do filtro e o valor do filtro como parâmetros.
apply_filters( 'filter_name', 'value_to_filter', [argument1], [argument2] );Não esqueça de especificar quaisquer argumentos adicionais se você quiser passá-los para suas funções de callback. A maioria dos filtros usa apenas um argumento, por isso é fácil não definir os argumentos adicionais.
Esta função é como a função apply_filters(), exceto que todos os argumentos que ela aceita são empacotados como um array.
// an example array
$arguments_array = array( 'some_value', 'foo', false, 'another_value' );
apply_filters_ref_array( 'example_filter', $arguments_array );Esta função de filtro pode ser útil quando você tem muitos argumentos para passar ou se todos eles já estão em um array. Certifique-se de que os argumentos dentro do array estão na ordem correta.
Esta função de filtro recupera o nome do filtro atual ou ação que está sendo executada. Você não precisa especificar nenhum parâmetro, pois ele roda dentro da função de retorno de chamada.
Aqui está um exemplo de seu uso:
function example_callback() {
echo current_filter(); // 'the_title' will be echoed
return
}
add_filter( 'the_title', 'example_callback' );Apesar de seu nome, esta função pode recuperar o nome tanto das ações como dos filtros.
Esta função de filtro remove a função de callback anexada ao filtro especificado. Ela funciona exatamente como a função remove_action(). Você pode usá-la para excluir funções padrão do WordPress registradas com um filtro específico, e se necessário substituí-las por suas próprias funções.
remove_filter( 'filter_name', 'function_to_be_removed', [priority] );Para desacoplar uma função de callback ligada a um filtro, a function_to_be_removed e os parâmetros de priority devem ser idênticos aos argumentos utilizados quando se liga a função de callback.
Se o filtro foi adicionado de dentro de uma classe, que normalmente é o caso quando eles são adicionados por plugins, então você precisa acessar a variável de classe para remover o filtro.
// access the class variable first, and then remove the filter through it
global $some_class;
remove_filter( 'the_content', array($some_class, 'class_filter_callback') );Vamos dar um ótimo exemplo de remove_filter() em ação.
O plugin WooCommerce usa a função de chamada wc_lostpassword_url() ligada ao seu filtro lostpassword_url para redirecionar “Lost Your Password? ” por usuários.
É necessário que qualquer usuário clique nesse link para uma página de frontend personalizada com a URL /my-account/lost-password. Sem esse filtro, ele os levaria para a URL padrão de login do WordPress em /wp-login.php.
Digamos que você queira redefinir esta funcionalidade e enviar seus usuários para a página padrão de recuperação de senha ou para uma página separada completamente. Você pode remover esta função de callback desta forma:
remove_filter( 'lostpassword_url', 'wc_lostpassword_url', 10 ); Esta função de filtro remove todas as funções de callback registradas em um filtro.
remove_all_filters( 'filter_name', [priority] );É similar à função remove_all_actions().
O popular plugin Advanced Excerpts usa esta função para remover todas as funções padrão ligadas ao_excerpt e aos_filtros get_the_excerpt. Depois de fazer isso, ele então engata sua própria função de callback no filtro.
// Ensure our filter is hooked, regardless of the page type
if ( ! has_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) ) ) {
remove_all_filters( 'get_the_excerpt' );
remove_all_filters( 'the_excerpt' );
add_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) );
}Esta função de filtro verifica se o filtro especificado está sendo executado no momento.
if ( doing_filter( 'save_post' ) ) {
// run your code here
}Ele retorna um valor booleano (true ou false).
Você deve notar a diferença entre esta função e a função current_filter(), que retorna o nome do filtro ou ação sendo executada (uma string).
Filtros Exemplo 1: Adicionando um filtro Profanity para comentários
Gerenciar todos os comentários no seu site WordPress pode ser um processo incômodo. O filtro comment_text permite que você defina regras para modificar os comentários antes que eles sejam impressos no display.
Você pode direcionar o WordPress para remover quaisquer expletivos automaticamente antes que eles sejam exibidos aos visitantes do seu site. Vamos a isso.
// hook into the 'comment_text' filter with the callback function
add_filter( 'comment_text', 'the_profanity_filter' );
// define a callback function to filter profanities in comments
function the_profanity_filter( $comment_text ) {
// define an array of profane words and count how many are there
$profaneWords = array('fudge', 'darn', 'pickles', 'blows', 'dangit');
$profaneWordsCount = sizeof($profaneWords);
// loop through the profanities in $comment_text and replace them with '*'
for($i=0; $i < $profaneWordsCount; $i++) {
$comment_text = str_ireplace( $profaneWords[$i], str_repeat('*', strlen( $profaneWords[$i]) ), $comment_text );
}
return $comment_text;
}Aqui está uma divisão do código linha a linha:
- comment_text é um Hook de filtro que permite modificar o texto de um comentário antes que o navegador o exiba. Você pode registrar sua função de callback com ele para filtrar sua saída.
- A função
add_filter()permite que você se conecte ao filtrocomment_texte anexe uma função de callback a ele. the_profanity_filter()é o nome da função callback. Ele aceita apenas um parâmetro, que é uma string contendo o texto do comentário. Defina esta função personalizada com a lógica de código apropriada.- Armazene todas as palavras profanas em um array PHP chamado
profaneWords. Você pode adicionar quantas palavras você quiser a este array. Eu estou armazenando o tamanho deste array na variávelprofaneWordsCountcom a ajuda da sizeof() PHP function. - Percorra todas as palavras profanas e use a str_ireplace() function padrão do PHP para substituir qualquer uma das profanidades correspondentes por símbolos
*. Como esta é uma função de substituição de str_ireplace, você não tem que se preocupar com a capitalização. Confira as diferentes maneiras de realizar a pesquisa e substituição. - Use
returnpara emitir o texto de comentário filtrado.
Salve as alterações no seu arquivo de plugin personalizado e recarregue qualquer post com comentários. Todas as palavras que você incluiu no array do profaneWords devem agora ser substituídas por símbolos ‘*’.
Os comentários originais ainda estarão disponíveis como estão no banco de dados. Este filtro apenas modifica o texto do comentário antes de ser enviado para o frontend.
Uma vez conectado ao filtro certo, você pode fazer um monte de coisas legais com ele.
Por exemplo, você também pode usar o filtro comment_text para remover quaisquer URLs de todos os comentários (certifique-se de ler este guia detalhado sobre como parar comentários de spam no WordPress).
Ou você pode se conectar ao filtro pre_comment_approved e marcar comentários como aprovados, spam, ou thrash com base em critérios pré-definidos.
Filtros Exemplo 2: Inserir conteúdo após uma postagem
Você já viu como o WordPress usa o filtro the_content para modificar o conteúdo do post ou da página. Vamos usar o mesmo filtro para adicionar algo no final de cada post.
// hook into 'the_content' filter with a callback function
add_filter( 'the_content', 'insert_content_below' );
// define the callback function to insert something below the post
function insert_content_below( $content ) {
// check to see if we're inside the main loop in a single post
if ( is_single() && in_the_loop() && is_main_query() ) {
return $content . "<h3 style=\"text-align: center;\">Let me insert myself here</h3><p style=\"text-align: center;border: 3px solid #5333ed;\">I'll appear after the post. You can insert anything here. Even HTML. Headers, links, images, scripts, I'll take them all and append it to the end of the post content. You can also give me a class, so you can style me easily with CSS style sheets.</p>" ;
}
return $content;
}Entendendo a lógica do código no exemplo acima:
the_contentfilter hook ajuda você a pegar o conteúdo do post atual e customizá-lo.- Use a função
add_filter()para enganchar no filtro_content com a funçãoinsert_content_below()callback. - Defina a função callback passando o conteúdo do post atual como parâmetro (
$content). - Dentro da função callback, verifique se você só está filtrando o conteúdo na consulta principal, que neste caso é o conteúdo do post. Se você não verificar isso, algumas vezes o código irá filtrar o conteúdo de outros lugares, como barras laterais e rodapés, sem querer.
- is_main_query() e in_the_loop() condicionals determinam se a consulta é uma consulta principal e acontece dentro do Loop principal do WordPress.
- is_single() verifica se a consulta é para um único post.
- Use o operador de concatenação de strings do PHP (
$content . “your additions”) para adicionar coisas extras ao conteúdo da página. returno comentário filtrado se todos os condicionantes acima forem verificados. Caso contrário, basta return o conteúdo sem alterações.
Salve seu arquivo de plugin, carregue qualquer post em seu site e vá até o final.
Você pode usar a mesma lógica para adicionar qualquer coisa ao início de todas as suas mensagens invertendo a posição dos parâmetros de concatenação de strings ("your additions" . $content).
Personalize a página de login do WordPress com hooks
Vamos usar tanto ações quanto filtros para customizar a página de login padrão do WordPress. Vou criar um novo plugin chamado Sal Custom Login Page para fazer isso. Você pode encontrar o código fonte completo deste plugin no final desta seção.
Vamos começar adicionando os campos padrão do cabeçalho do plugin e registrando-o com o WordPress.
<?php
/*
Plugin Name: Sal Custom Login Page
Version: 1.0
Description: Demonstrating WordPress Hooks (Actions and Filters) by customizing the WordPress login page.
Author: Salman Ravoof
Author URI: https://www.salmanravoof.com/License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: sal-custom-login-page
*/
// enqueueing the custom style sheet on WordPress login page
add_action( 'login_enqueue_scripts', 'salhooks_login_stylesheet');
function salhooks_login_stylesheet() {
// Load the style sheet from the plugin folder
wp_enqueue_style( 'sal-custom-login-page', plugin_dir_url( __FILE__ ).'sal-custom-login-page-styles.css' );
}Primeiro, conecte-se à ação login_enque_scripts para consultar sua folha de estilo personalizada. Quaisquer scripts ou estilos que você consultar aqui estão incluídos na seção de cabeçalho da sua página de login.
Se você quiser carregar scripts personalizados e folhas de estilo no frontend do seu site (e não no backend do administrador ou na área de login), então você precisa se conectar à ação wp_enqueue_scripts. Você pode ler mais sobre isso no artigo do WordPress Codex e Kinsta sobre como usar o wp_enqueue_scripts.
Dentro da função sal-custom-login_stylesheet() callback, use a função wp_enqueue_style() para carregar a folha de estilo personalizada (sal-custom-login-pagin-page-styles.css) colocada no mesmo diretório do plugin. A função plugin_dir_url( __FILE__ ) integrada ao WordPress facilita a obtenção do caminho da URL (com uma barra de deslocamento) do diretório atual do plugin.
Eu não vou explicar os estilos CSS aplicados aqui, mas você pode encontrá-los todos no código fonte ligado no final desta seção.
// Custom login ERROR message to keep the site more secure
add_filter( 'login_errors', 'salhooks_remove_login_errors', 10 );
function salhooks_remove_login_errors() {
return 'Incorrect credentials. Please try again!';
}Em seguida, conecte-se ao filtro login_errors para alterar a mensagem de erro exibida quando alguém entra com credenciais incorretas. A filtragem da mensagem de erro irá bloquear atacantes de adivinhar seu nome de usuário facilmente.
// Remove the login form box shake animation for incorrect credentials
add_action( 'login_head', 'remove_login_error_shake' );
function remove_login_error_shake() {
remove_action( 'login_head', 'wp_shake_js', 12 );
}Toda vez que alguém insere credenciais de login incorretas, a caixa do formulário de login se agita agressivamente. Este é um passo opcional, mas eu o incluí para mostrar que você também pode remover certos recursos da página de login.
Você vai aprender mais sobre as funções remove_action() e remove_filter() na seção final deste artigo.
// Change the logo and header link above the login form
add_filter( 'login_headerurl', 'salhooks_login_headerurl');
function salhooks_login_headerurl( $url ) {
$url = 'https://salmanravoof.com';
return $url;
}
add_filter( 'login_headertext', 'salhooks_login_headertext');
function salhooks_login_headertext( $text ) {
$text = 'Salman Ravoof';
return $text;
}O último passo é alterar a URL e o texto do cabeçalho do login. Você pode se conectar ao login_headerurl e aos filtros login_headertext para modificar ambos.
Se você quiser construir sobre este plugin e experimentar mais, você pode baixar o código fonte do plugin e começar a usá-lo.
Lista de Hooks e Recursos do WordPress
É difícil memorizar todos os vários hooks que o WordPress tem. Há milhares de ações e filtros embutidos para enganchar. Assim, encontrar um Hook apropriado às vezes pode parecer uma caça ao tesouro.
Felizmente, existem vários recursos que você pode utilizar para identificar o Hook perfeito para as suas necessidades.
O primeiro lugar para se familiarizar com hooks é o WordPress Codex, particularmente sua seção de hooks no Manual do Plugin. Aqui você pode encontrar informações essenciais sobre hooks e links para documentação completa sobre todas as ações e filtros.
Marque estes links úteis no Manual do Plugin para acelerar a sua pesquisa:
- Plugin API – Referência da função dos hooks
- Plugin API – Referência de ação
- Plugin API – Referência em Filtros
Tanto a referência da ação quanto as páginas de referência do filtro lhe darão uma lista de todos os hooks que normalmente rodam durante uma solicitação específica do WordPress.
Por exemplo, você pode encontrar todos os hooks demitidos quando você acessa uma página de administração, quando você está lidando com anexos de posta de página, ou com categorias.
O Codex WordPress também inclui uma útil ferramenta de busca para encontrar todas as suas funções, hooks, métodos e classes. Esta página também lista componentes novos e atualizados na versão mais recente do WordPress. Vá primeiro aqui se você quiser encontrar o que está acontecendo dentro do WordPress.
Este índice de hooks do WordPress classifica todos os hooks por tipo, a versão do WordPress que eles estrearam, e se eles estão depreciados.
Classificar os hooks por ordem de aparecimento mostrará que os hooks WordPress mais antigos ainda são os mais usados. Se você é novo no desenvolvimento do WordPress, familiarizar-se com essas ações e filtros populares é a maneira mais rápida de se atualizar.
Embora este índice não tenha sido atualizado desde o WordPress 5.1, ele ainda é útil para folhear todos os principais hooks.
Ainda tem dificuldade para encontrar o Hook que você quer? Uma busca on-line com a palavra-chave certa é sempre uma boa maneira de começar. Se tudo o resto falhar, você sempre pode pesquisar o código do WordPress.
Como encontrar hooks registrados em uma página do WordPress
Como já vimos, o WordPress tem toneladas de hooks disponíveis, mas nem todos os hooks disparam em todas as páginas. Se você conseguir descobrir em quais ações e filtros você pode se conectar em uma determinada página, então você ganhou metade da batalha.
Enquanto você pode usar ferramentas avançadas de depuração PHP como xdebug e PHPCS para ajudar com isso, existem ferramentas de desenvolvimento mais simples como Debug Bar e Query Monitor que você pode rodar dentro do WordPress.
Barra de Depuração com Complemento de Ações e Filtros
Debug Bar é um plugin oficial do WordPress que adiciona um menu de Debug à sua barra de administração. Ele mostra avisos e avisos PHP, solicitações de cache, consultas MySQL e outras informações úteis de depuração.
Após instalar o plugin, você precisa adicionar o trecho de código abaixo ao arquivo wp-config.php do seu site para habilitar seus recursos de depuração.
define( 'WP_DEBUG', true ); // tracks PHP Warnings and Notices
define( 'SAVEQUERIES', true ); // tracks and displays MySQL queriesAgora você deve ver a opção de menu Debug aparecer na sua barra de administração. Clicando nele, você será levado ao seu painel de controle, onde você poderá ver várias consultas e caches anexados à página de onde você acessou.
A seguir, você precisa instalar o plugin Debug Bar Actions and Filters Addon. É uma extensão útil que irá adicionar mais duas abas ao seu painel da Barra de Depuração para exibir ações e filtros acionados na requisição atual.
Também listará com priority todas as funções a eles associadas.
Você pode clicar no menu Debug de qualquer página do seu site para conhecer todas as ações e filtros em que você pode se conectar naquela página.
Query Monitor
O Query Monitor é um poderoso painel de ferramentas de desenvolvimento para WordPress. Você pode usá-lo para escavar os hooks disponíveis em uma página e sua ordem de carga.
Ao contrário do Debug Bar, você não precisa instalar nenhum addon para ver as ações e filtros acionados em uma determinada página.
O Query Monitor também lhe dá mais informações sobre de onde exatamente um Hook está sendo disparado.
Na coluna de componentes, você pode ver que a maioria dos hooks são registrados a partir do Núcleo. Mas alguns hooks são registrados a partir de um tema ou plugin. Alguns hooks podem ser registrados a partir de mais de um componente.
Você pode usar os menus suspensos de hooks e componentes para visualizar apenas os hooks que você precisa.
Nota: O Query Monitor utiliza o termo “Hooks” como um termo de catchall tanto para ações quanto para filtros, mas chama as funções de callback registradas de “Ações”. Esta é uma definição tecnicamente errada e pode confundir você, portanto, tenha isso em mente.
Você pode fazer mais do que apenas verificar todas as consultas e pedidos com o Query Monitor. Ele também inclui recursos avançados como estilos de listagem, scripts, idiomas, chamadas Ajax, verificações de capacidade do usuário e chamadas REST API.
O Hook “all”
O WordPress tem um Hook especial chamado ‘all’ que você pode enganchar para executar uma função de callback para cada Hook, independentemente de estar registrado com todos eles. É útil para depurar falhas de página ou se você quer saber quando um evento em particular está acontecendo.
Por exemplo, você pode usar o Hook all como no exemplo abaixo para echo todas as ações que estão sendo executadas.
// echo all the actions being run
function debug_helper_function(){
echo '<p>' . current_action() . '</p>';
}
add_action( 'all', 'debug_helper_function' );A debug_helper_function() definida acima será executada quando qualquer ação for acionada. Saber qual foi a última ação a ser executada lhe dará uma melhor idéia de onde você precisa olhar.
Onde estão armazenados os hooks do WordPress?
O WordPress usa a classe WP_Hook para implementar como funcionam os hooks. Esta classe central é usada para lidar com todas as ações e filtros embutidos do WordPress. Você pode encontrar quase todo o código relacionado a esta classe no arquivo wp-includes/class-wp-hook.php.
Tecnicamente, a classe WP_Hook é um array de objetos compreendendo propriedades como callbacks, iterações, priority_corrente, nível_de_encaixamento e ação_de_fazer. Ela também define muitas funções de Hooks úteis que podem ser chamadas usando os métodos WP_Hook.
A maioria dos desenvolvedores WordPress não tem que se preocupar muito com onde o WordPress armazena os hooks desde que eles sigam as diretrizes da API do Plugin.
Como criar seus hooks personalizados para WordPress
Você já viu os vários hooks que o WordPress fornece através do seu Plugin API. Você também já viu como você pode usar os hooks padrão para injetar seu próprio código em tempo de execução do WordPress.
Se você é um desenvolvedor de plugins ou temas, é uma boa prática fornecer a outros desenvolvedores uma maneira de interagir com o seu código da mesma maneira. Os hooks personalizados permitem que você faça exatamente isso. Eles permitem que outros desenvolvedores ampliem e modifiquem a funcionalidade de seus plugins e temas.
Criar suas próprias ações e filtros é bastante simples. Você utiliza as mesmas funções que o WordPress Core utiliza para criar hooks. Vejamos alguns exemplos.
Como Criar Ações Personalizadas no WordPress
Use a função do_action() para criar um Hook de ação personalizado. Aqui está como você faz isso:
// the position where you insert your action is where it'll run when called
do_action( ' my_unique_custom_action' );
// continue with the rest of your codeAgora, outros desenvolvedores podem se conectar ao seu plugin ou tema sem modificar o código fonte. Tudo que eles têm que fazer é registrar suas funções de callback na ação personalizada do seu plugin usando a função add_action().
add_action( 'my_unique_custom_action', 'some_callback_function' );
// define the callback function you mentioned in the above action function
some_callback_function() {
// this code will run wherever your custom action hook is
}Não deixe de documentar seus hooks personalizados detalhadamente, explicando o que eles fazem. Afinal, o principal uso da criação de hooks personalizados é ajudar outros desenvolvedores a interagir com o seu código.
Como Criar um Filtro Personalizado no WordPress
Use a função apply_filters() para criar um Hook de filtro personalizado. Aqui está como você pode fazer isso:
$value_to_filter = "I'm a string, but this can be any PHP data type";
// filters modify a value and are typically tied to a predefined variable
apply_filters( 'my_custom_filter', $value_to_filter );Os parâmetros do seu filtro personalizado devem incluir um identificador único e um valor a ser filtrado. Outros desenvolvedores podem se conectar ao seu filtro personalizado com a função add_filter() e modificar o valor passado.
add_filter( 'my_custom_filter', 'some_callback_function' );
// define the callback function you mentioned in the above filter function
function some_callback_function( $value_to_filter ) {
// modify the passed value (or not)
return $value_to_filter; // returning a value is a must for filters
}Quando você estiver definindo seu filtro personalizado, certifique-se de que ele não esteja posicionado antes que o valor que ele deve filtrar seja definido. Se você não posicionar o filtro corretamente, o valor filtrado será sobregravado pelo valor padrão depois.
Convenção de Nomenclatura de Hooks Personalizados
É importante escolher um nome único para todos os seus hooks personalizados. Como qualquer plugin ou tema pode ter seus próprios hooks personalizados, ter nomes de hooks idênticos pode causar colisões de código com resultados inesperados.
Por exemplo, se você nomear sua ação send_email, é altamente provável que outros desenvolvedores de plugins também possam escolher o mesmo termo, pois ele não é único o suficiente. Se algum site instalar tanto o seu quanto os plugins do outro desenvolvedor, isso pode causar erros que serão difíceis de rastrear.
Você pode prefixar todos os seus hooks personalizados com um identificador comum para mantê-los simples e únicos. Então, ao invés de send_email, você pode nomeá-lo como plugin_name_send_email (plugin_name_ é o prefixo único aqui).
Demonstração de hooks personalizados com um Plugin Extensível
Vamos criar um plugin extensível (ou pluggable plugin) que permitirá que outros desenvolvedores interajam com ele usando seus hooks personalizados.
Eu vou nomear este plugin como Custom Hooks Demo. Sua principal função é emitir uma caixa de cotação onde quer que você insira um código de atalho. Ele incluirá ações e filtros personalizados nos locais certos para possibilitar que outros desenvolvedores possam modificar ou ampliar sua funcionalidade.
Você pode consultar o meu guia de atalhos do WordPress para saber mais sobre como funcionam os atalhos.
Vamos começar com o plugin extensível.
<?php
/*
Plugin Name : Custom Hooks Demo
Description : Demonstrating how to create an extensible WordPress plugin using custom hooks.
Author : Salman Ravoof
Author URI : https://salmanravoof.com/
License : GPLv2 or later
License URI : https://www.gnu.org/licenses/gpl-2.0.html
Text Domain : custom-hooks-demo
*/
/**
* the [custom_hooks_demo] shortcode returns the HTML code for a quote box.
* @return string HTML code for a quote box
*/
add_shortcode( 'custom_hooks_demo', 'my_shortcode_callback' );
function my_shortcode_callback ( $arguments ) {
ob_start(); // start object buffering to collect all output before sending it to the browser
// set an action hook to run before you output anything
do_action( 'the_topmost_custom_action' );
// define your variables which you want to allow to be filtered
$quote_content = "Z.E.R.O. That's the number of people who'd like to have any website autoplay music on their browsers.";
$quote_author = "John Doenuts";
// create your custom filters after you've set the variables
$quote_content = apply_filters( 'custom_quote_content', $quote_content );
$quote_author = apply_filters( 'custom_quote_author', $quote_author );
// build the shortcode output template
echo "<div style=\"border:3px solid #5333ed;\"><blockquote style=\"margin:20px;border-color:#5333ed;\">";
echo $quote_content;
echo "<br><br>";
echo "― <strong>" . $quote_author . "</strong>";
echo "</blockquote></div>";
// set an action hook to run after you output everything
do_action( 'the_ending_custom_action' );
return ob_get_clean(); // get buffer contents, delete the buffer, and then stop buffering
}- A função
add_shortcode()é utilizada para criar o código de atalho personalizado. E então você define a função callback do shortcode com toda essa funcionalidade do plugin. - ob_start() é uma função PHP que habilita o buffer de saída. É uma função super útil que instrui o PHP a segurar qualquer saída na memória buffer do servidor ao invés de emiti-la imediatamente. Você pode usá-lo para construir código HTML complexo e legível no PHP.
do_action( 'the_topmost_custom_action' )define sua primeira ação personalizada. Para torná-la útil, você precisa defini-la antes que o plugin produza alguma coisa. Outros desenvolvedores podem se conectar a esta ação personalizada para executar seu código antes que este atalho personalizado imprima qualquer coisa.- Crie as variáveis que você deseja filtrar. Neste plugin, essas variáveis são
$quote_content e $quote_author. Elas são ambas strings neste exemplo, mas você pode configurá-las para serem qualquer tipo de dado PHP (por exemplo, integer, boolean, array). - Use a função
apply_filters()para criar seus filtros personalizados. Como todos os filtros retornam um valor, você pode atribuir as variáveis previamente definidas para o valor retornado por este filtro. Outros desenvolvedores podem agora se conectar a este filtro para modificar os valores padrão das variáveis pré-definidas. - Use os comandos de
echopara construir a saída do seu atalho linha por linha. Como ativamos o buffer de saída, nenhuma saída chegará ao navegador imediatamente. do_action( 'the_ending_custom_action' )define sua última ação personalizada. Você precisa defini-la no final, mas antes de return todo o conteúdo do buffer.- ob_get_clean() é uma função 3 em 1 padrão do PHP. Ela irá recuperar o conteúdo do buffer, eliminar todos os dados do buffer, e então parar o buffer de saída. Ele irá
returno conteúdo do buffer coletado como uma única string concatenada.
Uma vez salvo e ativado, adicionando o atalho [custom_hooks_demo] ao conteúdo do seu post, sairá uma caixa de cotação com os valores padrão.
Agora, vamos criar outro plugin chamado Custom Hooks Demo Extension. Ele irá se conectar a todos os hooks personalizados criados pelo plugin anterior e fazer ou modificar alguma coisa.
<?php
/*
Plugin Name : Custom Hooks Demo Extension
Description : Demonstrating how you can extend WordPress plugin functionality with its custom hooks.
Author : Salman Ravoof
Author URI : https://salmanravoof.com/
License : GPLv2 or later
License URI : https://www.gnu.org/licenses/gpl-2.0.html
Text Domain : custom-hooks-demo-extension
*/
/**
* replace the quote content by hooking into the 'custom_quote_content' filter
*/
add_filter( 'custom_quote_content', 'new_quote_content_callback' );
function new_quote_content_callback( $content ) {
$content = "There are no bugs in programming. Only unexpected features.";
return $content;
}
/**
* replace the quote author by hooking into the 'custom_quote_author'
*/
add_filter( 'custom_quote_author', 'new_quote_author_callback' );
function new_quote_author_callback( $author ) {
$author = "Jane Doodle";
return $author;
}
/**
* add an image to the top of the shortcode output by hooking into the 'the_topmost_custom_action'
*/
add_action( 'the_topmost_custom_action', 'quote_image_callback' );
function quote_image_callback() {
$url = "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f9/Quote-right-cs.svg/75px-Quote-right-cs.svg.png";
echo '<div><img class="aligncenter" src="'.$url.'"></div>';
}
/**
* add a button below the shortcut output by hooking into the 'the_ending_custom_action'
*/
add_action( 'the_ending_custom_action', 'add_button_callback' );
function add_button_callback() {
echo '<div style="text-align:center;"><button name="nice">Nice Quote!</button></div>';
}Como você pode ver, este plugin de extensão não contém nada além de ação e funções de filtragem que se encaixam no plugin original nos lugares certos para fazer modificações.
Ele usa as funções add_action() e add_filter() para registrar suas funções de callback com as ações e filtros personalizados criados pelo plugin original (por exemplo, the_topmost_custom_action, custom_quote_author).
Hooks de ação personalizados permitem que você interje seu código nos intervalos certos no plugin original e execute seus próprios scripts. Aqui, nós estamos adicionando uma imagem no topo e um botão no fundo.
Da mesma forma, hooks de filtro personalizados permitem modificar os valores do conteúdo da cotação e seu nome de autor. O resultado final é um plugin que é totalmente extensível por qualquer pessoa sem modificar o seu código fonte.
Trabalhando com Hooks Personalizados de Desenvolvedores Terceirizados
Hooks personalizados permitem que plugins e temas individuais para WordPress tenham um rico ecossistema de plugins extensíveis. Considere o plugin WooCommerce. Ele adiciona funcionalidade de comércio eletrônico ao WordPress, mas também inclui toneladas de hooks dentro de seu código.
O WooCommerce tem centenas de extensões e plugins que utilizam seus hooks para construir sobre sua funcionalidade principal e torná-la ainda melhor.
Você pode usar estas extensões para integrar o WooCommerce com Stripe, MailChimp, Salesforce, Zapier, e muito mais.
Uma boa prática é verificar a seção de documentação dos populares plugins do WordPress para ver como eles implementam hooks personalizados. Algumas das minhas principais sugestões são Easy Digital Downloads, BuddyPress, Quiz and Survey Master, e Gravity Forms.
Quando usar hooks personalizados?
Dependendo do tema ou plugin que você está criando, e a quem se destina, você pode se perguntar se precisa adicionar algum Hook personalizado.
Uma boa regra geral quando se decide se deve ou não adicionar hooks personalizados é verificar se eles oferecem algum benefício de extensibilidade para outros desenvolvedores. Se não, então é melhor esperar até que outros desenvolvedores lhe peçam para adicioná-los.
Você precisa estar altamente seguro sobre a adição de hooks personalizados ao seu plugin ou tema. Uma vez lançado, e se outros desenvolvedores já o utilizaram, você não poderá nunca mudá-lo sem quebrar a compatibilidade com versões anteriores.
Remoção das Funções de Callback dos Hooks do WordPress
Você já viu exemplos de como remover funções de callback registradas em determinados hooks. Estes callbacks podem ser registrados por plugins, temas, ou até mesmo pelo próprio WordPress Core. Vamos dar mais exemplos de como remover funções de callback com hooks.
Para remover uma função callback de um Hook, dependendo se ele está registrado em uma ação ou filtro, você precisa usar as funções remove_action() ou remove_filter().
Uma ressalva é que você precisa chamar estas funções com os mesmos parâmetros usados para registrar a função de retorno de chamada. Basicamente, copie-colar os parâmetros de suas funções add_action() ou add_filter().
Além disso, você pode remover as funções de callback somente após elas serem registradas. Se você tentar removê-las antes de serem cadastradas, o processo de remoção falhará. Você precisa obter a ordem de execução dos hooks corretamente.
Digamos que você queira remover uma função de callback registrada por um tema que acrescenta inchaço ao seu site (você want a fast site, não é mesmo?).
function wp_bloated_callback_function() {
// some code that adds a lot of bloat to the site
}
add_action( 'template_redirect', 'wp_bloated_callback_function', 5 );Por exemplo, a função de callback acima poderia carregar muitos scripts e folhas de estilo desnecessários. Removê-lo dará ao seu site um enorme aumento de desempenho.
Entretanto, você precisa garantir que a função remove_action() só seja executada após a ação template_redirect. Uma maneira de fazer isso é se conectar à ação after_setup_theme, pois ela é acionada após a ação template_redirect.
function wp_remove_bloat() {
// ensure all parameters are identical to the original add_action() function
remove_action( 'template_redirect', 'wp_bloated_callback_function', 5 );
}
// ensure that remove_action() is called only after add_action()
add_action( 'after_setup_theme', 'wp_remove_bloat' );O wp_bloated_callback_function() agora se desvincula da ação template_redirect.
Casos Especiais para Remoção de Funções de Callback
Há mais para remover as funções de callback do que simplesmente desativá-las completamente. Às vezes você pode precisar removê-las temporariamente, executar seu código e depois adicioná-las novamente.
Por exemplo, a ação save_post aciona toda vez que as funções wp_insert_post() e wp_publish_post() são chamadas. Você pode encontrá-las ambas definidas no arquivo wp-includes/post.php.
Então, se você tiver uma função de callback ligada à ação save_post, e se você chamar as funções wp_insert_post() ou wp_publish_post() dentro da sua função de callback, a ação save_post irá disparar várias vezes.
function some_callback_function( $post_id, $post ) {
// do something here
wp_insert_post( [some_array] ); // this function also calls the 'save_post' action
// maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );Uma função que chama a ação e que também a chama pode criar resultados inesperados. Uma maneira de contornar este problema é usar a função remove_action() dentro da sua função callback antes de chamar wp_insert_post().
function some_callback_function( $post_id, $post ) {
// do something here
// remove the callback function from the ‘save_post’ action
remove_action( 'save_post', 'some_callback_function', 10, 2 );
// now run the wp_insert_post() function
wp_insert_post( [some_array] );
// add the callback function back to the ‘save_post’ action
add_action( 'save_post', 'some_callback_function', 10, 2 );
// maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );Esse é outro uso prático das funções remove_action() ou remove_filter(). Cavar mais fundo no WordPress Core ajudará você a entender como você pode evitar essas situações melhor.
Tutoriais Bônus Hooks WordPress
- Adicionar Manualmente o Código ao Cabeçalho e Rodapé do WordPress
- Seu Guia Completo para a Biblioteca de Mídia WordPress
- Como Criar e Modificar um Trabalho de Cron do WordPress
- Como Criar um Tema filho WordPress
- Desativar o carregamento de plugins do WordPress em páginas e posts específicos
- Desabilitar Emojis no WordPress com Código
Resumo
Há múltiplas vantagens em usar os hooks do WordPress se você é um desenvolvedor do WordPress.
Os hooks não só permitem modificar ou ampliar a funcionalidade central do WordPress, como também podem ser usados para modificar plugins, temas e deixar outros desenvolvedores interagirem com seus plugins ou temas.
É hora de ficar viciado nos hooks do WordPress!
Deixe um comentário