Guia: Como usar corretamente o AJAX no WordPress

AJAX é uma técnica que você pode usar em Javascript para buscar dados do servidor e atualizar o conteúdo de sua página sem recarregá-la em seu navegador. Neste post vamos mergulhar em como usar corretamente o AJAX no WordPress.

A maioria de vocês provavelmente está familiarizada com a execução de solicitações AJAX fora do WordPress e deseja ver como fazer isso no WordPress. Você pode estar se perguntando sobre as seguintes perguntas:

1. Qual URL você deve enviar suas solicitações AJAX em seu Javascript.
2. Como realmente capturar a solicitação AJAX em PHP, buscar seus dados e enviar algo de volta.
3. Certificando-se de que suas solicitações AJAX são seguras.

No WordPress você pode realizar requisições AJAX no admin e/ou frontend; o processo é o mesmo com algumas diferenças em responder às perguntas acima. Vamos mergulhar direto!

O básico para executar a solicitação AJAX no WordPress

A primeira coisa que você precisa é, obviamente, do javascript onde você deseja enviar a solicitação AJAX. Ele deve ser enfileirado usando um método válido de adicionar scripts ao WordPress, seja frontend ou backend. Muito provavelmente você já tem um script configurado onde você só precisa da parte de enviar ou solicitar algo do WordPress.

Postar AJAX no WordPress requer que você passe uma variável de objeto Javascript como dados para a solicitação. No objeto você precisa fornecer no mínimo uma propriedade; ‘ action‘. O valor da actionpropriedade ‘ ‘ é uma string que pode ser (quase) o que você quiser. Esta ação é o que diz ao WordPress como rotear a solicitação AJAX. Mas também define parte do nome do gancho que você precisará conectar no PHP para lidar com a solicitação AJAX.

Quando se trata de responder à pergunta 1 acima: para qual URL você deve enviar sua solicitação AJAX? Isso difere dependendo se seu script está enfileirado em admin ou frontend. Como o AJAX já está embutido nas telas de administração do WordPress, você pode simplesmente usar a variável global ajaxurl. Mas para solicitações de frontend fica um pouco mais complicado porque você precisa fornecer a URL AJAX manualmente junto com seu Javascript. Mais sobre isso abaixo.

Para lidar com solicitações AJAX em PHP, você se conecta à ação wp_ajax_<your action name>. Se você deseja executar solicitações AJAX no frontend para usuários não logados, você também pode conectar-se ao wp_ajax_nopriv_<your action name>. Mais sobre isso abaixo. Dentro da sua função hooked você pode acessar os dados passados ​​do Javascript referenciando o $_POSTarray. Para emitir algo de volta, você simplesmente ecoa algo. Essa é a resposta curta para a pergunta 2 acima.

Vamos mergulhar direto no código. Começaremos com como adicionar solicitações AJAX no painel de administração.

Executando solicitações AJAX no administrador do WordPress

Suponho que você já tenha um script enfileirado que reage a alguma ação do usuário, coleta dados e está pronto para executar uma solicitação AJAX, seja para atualizar algo, ou para solicitar algumas informações de volta do WordPress. O código abaixo é um exemplo bem simplificado; o código enfileira um arquivo Javascript no tema para admin e, dentro do código Javascript, ele configura algumas variáveis ​​aleatórias, executa o AJAX no carregamento da página e gera a resposta no console.

add_action('admin_enqueue_scripts', function() {
    wp_enqueue_script('awhitepixel-script', get_stylesheet_directory_uri(). '/assets/js/awhitepixel-ajax.js', ['jquery'], '', true);
});

jQuery(document).ready(function($) {
    var data = {
        'action': 'awhitepixel_send_something',
        'something': 'Hello world',
        'another_thing': 14
    }
    $.post(ajaxurl, data, function(response) {
        console.log(response);
    });
});

Como você pode ver no código Javascript acima, você configura um objeto Javascript (pense nele como um array) com todos os dados que deseja passar, incluindo a importante actionpropriedade ‘ ‘.

Também como mencionado acima, como o AJAX já está embutido nas telas de administração do WordPress, você simplesmente usa a variável global ajaxurlcomo URL do AJAX.

Agora vamos adicionar o código para aceitar esta solicitação AJAX em PHP. Como eu forneci ‘ awhitepixel_send_something‘ como valor de action‘, preciso me conectar a wp_ajax_awhitepixel_send_something.

add_action('wp_ajax_awhitepixel_send_something', function() {
    $something = $_POST['something'];
    $another_thing = (int) $_POST['another_thing'];
 
    echo 'You sent '. $something. ' with '. $another_thing;
 
    wp_die();
});

Dentro de sua função enganchada você tem acesso total ao WordPress; você pode usar quaisquer funções do WordPress, consultas e acessar variáveis ​​globais (por exemplo, $wpdbpara consultas de banco de dados). Todas as variáveis ​​que você passou em Javascript estarão disponíveis dentro $_POSTdo array com as chaves que você forneceu no objeto Javascript.

É opcional passar algo de volta para o Javascript (por exemplo, quando você deseja apenas enviar uma solicitação para atualizar ou salvar algo e não precisa de confirmação). Se você quiser passar algo de volta, simplesmente echosua saída. Para gerar variáveis ​​mais complexas do que simplesmente uma string, você deve retorná-la como uma matriz codificada em json para que o Javascript possa lê-la e analisá-la corretamente. Algo assim;

Uma nota final importante na última linha; wp_die(). Todas as funções de retorno de chamada AJAX devem "fechar o encadeamento" ou terminar corretamente fazendo die()ou exit(). No WordPress, usamos wp_die()para integração adequada, mas o resultado é o mesmo. Se acontecer de você receber um "0" estranho em suas respostas AJAX, é mais provável que não fez wp_die()ou die(). Sempre, sempre certifique-se de que “você morre" no final de todas as funções conectadas ao wp_ajax.

Executando solicitações AJAX no frontend do WordPress

O processo de execução do AJAX no frontend é o mesmo que no admin, mas um pouco mais complicado para responder à pergunta 1: em qual URL o AJAX deve postar. No exemplo acima para realizar AJAX em admin já tínhamos uma variável Javascript global, ajaxurl, mas esta variável não está disponível no frontend. Precisamos fornecê-lo nós mesmos. Para obter o valor da URL AJAX do WordPress que você usa admin_url('admin-ajax.php')(sim, “admin url” para frontend).

Ao enfileirar um script de frontend que realizará solicitações AJAX em seu tema ou plugin, você precisa passar a URL AJAX do WordPress como variável para esse Javascript, usando wp_localize_script().

Agora, no seu Javascript você tem acesso a um objeto Javascript global Theme_Variables(esse nome pode ser o que você quiser), com a URL AJAX do WordPress como valor para a ajax_urlpropriedade ‘ ‘. Sua função AJAX seria algo assim:

jQuery(document).ready(function($) {
    var data = {
        'action': 'awhitepixel_frontend_stuff',
        'something': 'Hello world',
        'another_thing': 14
    }
    $.post(Theme_Variables.ajax_url, data, function(response) {
        console.log(response);
    });
});

Ao lidar com AJAX no frontend, há mais uma coisa a ter em mente em relação ao gancho que você usa para aceitar solicitações AJAX. Você ainda se conecta ao wp_ajax_<your action name>, mas este gancho só funcionará para visitantes que estão logados. Se você deseja executar solicitações AJAX para visitantes que não estão logados, você precisa (também) conectar ao wp_ajax_nopriv_<your action name>. Normalmente, para solicitações AJAX de frontend necessárias para que o tema funcione corretamente, você conectaria ambos, apontando-os para a mesma função.

add_action('wp_ajax_awhitepixel_frontend_stuff', 'awhitepixel_ajax_frontend');
add_action('wp_ajax_nopriv_awhitepixel_frontend_stuff', 'awhitepixel_ajax_frontend');
function awhitepixel_ajax_frontend() {
    $something = $_POST['something'];
    $another_thing = (int) $_POST['another_thing'];
 
    echo 'You sent '. $something. ' with '. $another_thing;
    wp_die();
}

Quanto ao conteúdo de sua função de gancho AJAX, é o mesmo que para solicitações de administrador. Você tem acesso completo ao WordPress, obtém as variáveis ​​passadas de $_POST, opcionalmente retorna algo executando echo, e deve sempre lembrar de “morrer” wp_die()no final.

Protegendo suas solicitações AJAX

Como o AJAX facilita muito a passagem de dados entre o script e o back-end, você definitivamente deve tomar as medidas necessárias para tornar seu código seguro. Isso inclui limpar todos os dados antes de salvá-los, mas também utilizar a funcionalidade “nonce” do WordPress para verificar se as solicitações vêm de locais corretos e aceitos. Leia a documentação do WordPress imediatamente se você não estiver familiarizado com ele.

A premissa básica é esta; você usa um método WordPress gerando um valor nonce (wp_create_nonce()) ou gerando um campo de entrada oculto com o valor nonce (wp_nonce_field()). Na sua requisição AJAX você passa o valor nonce (que é codificado pelo WordPress) na requisição, e na parte de aceitação (wp_ajax_gancho) você verifica o nonce com o que você definiu originalmente.

Vamos adicionar alguma segurança ao código de exemplo que fizemos acima. Primeiro vamos gerar um nonce e passá-lo em nosso wp_localize_scriptURL AJAX. Como parâmetro para wp_create_nonce()definirmos uma string única que somente nós devemos conhecer, por assim dizer. No exemplo abaixo eu estou indo para ‘ awhitepixel-nonce‘.

O que é passado como ‘ nonce‘ em nossas variáveis ​​Javascript para o frontend é um número aleatório gerado pelo WordPress. Ninguém além de nós, autores deste roteiro, sabemos que o nonce válido é ‘ awhitepixel-nonce‘. Em nosso Javascript, pegamos o valor nonce e o passamos de volta em nossa solicitação AJAX:

jQuery(document).ready(function($) {
    var data = {
        'action': 'awhitepixel_frontend_stuff',
        'something': 'Hello world',
        'another_thing': 14,
        'nonce': Theme_Variables.nonce
    }
    $.post(Theme_Variables.ajax_url, data, function(response) {
        console.log(response);
    });
});

E, finalmente, em nossa wp_ajaxfunção hooked, devemos começar verificando se o nonce era válido com wp_verify_nonce(). Fornecemos a string exclusiva que definimos acima e, se o WordPress não corresponder ao valor codificado exclusivo transmitido com essa string, encerramos imediatamente:

add_action('wp_ajax_awhitepixel_frontend_stuff', 'awhitepixel_ajax_frontend');
add_action('wp_ajax_nopriv_awhitepixel_frontend_stuff', 'awhitepixel_ajax_frontend');
function awhitepixel_ajax_frontend() {
    if (!isset($_POST['nonce']) || !wp_verify_nonce($_POST['nonce'], 'awhitepixel-nonce')) {
        wp_die(-1);
    }
 
    $something = $_POST['something'];
    $another_thing = (int) $_POST['another_thing'];
 
    echo 'You sent '. $something. ' with '. $another_thing;
    wp_die();
}