Tutorial: Endpoints de URL personalizados com a API de reescrita do WordPress
Já desejou poder estender postagens únicas, páginas ou seus tipos de postagem personalizados com um modelo personalizado que mantém sua própria estrutura de URL? Com o WordPress Rewrite API, isso é totalmente possível e nada difícil.
Neste tutorial, veremos como anexar uma única visualização de tipo de postagem personalizada com outro slug que carrega um modelo diferente. Em outras palavras, se uma única postagem de tipo de postagem personalizada tiver o URL "example.com/destination/venice/", você poderá adicionar regras de URL para páginas separadas com informações relacionadas a cada destino, por exemplo"example.com/destination/venice /activities/" e “example.com/destination/venice/attractions/”.
Se você estiver interessado em como adicionar endpoints à página “Minha conta” do WooCommerce, tenho outro post sobre isso!
A API do WordPress Rewrite tem muitas funções úteis para escrever suas próprias regras de URL personalizadas. Você pode ter visto a função mais conhecida e ampla; add_rewrite_rule(). Este tutorial, no entanto, usa o similar add_rewrite_endpoint(), que é muito útil para adicionar “endpoints” de URL (basicamente adicionando slugs de URL personalizados após algo que já existe, por exemplo, após o final de um único post ou única categoria). Você pode obter o mesmo resultado usando, add_rewrite_rule()mas o processo de adição de endpoints é mais simples.
O que vamos fazer
Este guia assumirá que criamos dois tipos de postagem personalizados; ‘filme’ e ‘ator’. A regra de permalink para um único filme é “example.com/movie/fight-club/” e para um único ator “example.com/actor/brad-pitt/”. Queremos uma página separada para cada filme que mostre todos os atores desse filme, localizada em “example.com/movie/fight-club/actors/” e, da mesma forma, uma página separada para cada ator que mostre todos os filmes em que o ator participou, localizado em “example.com/actor/brad-pitt/movies/”.
Não entrarei em detalhes sobre como adicionar esses dois tipos de postagem personalizados; se você precisar de ajuda para fazer esta parte, recomendo ler meu post sobre como adicionar tipos de postagem personalizados.
Escrevendo o código
A primeira etapa é chamar add_rewrite_endpoint()uma função vinculada a init(geralmente todas as funções na API Rewrite são vinculadas a init). para registrar nossos dois endpoints desejados; ‘filmes’ e ‘atores’. A função recebe dois argumentos; primeiro o ponto de extremidade que você deseja (por exemplo, ‘filmes’) e, em segundo lugar, uma constante para onde o ponto de extremidade deve “morar” (por exemplo, páginas, autor, arquivos, etc). Consulte a documentação para quais constantes você pode usar; quanto a este exemplo, o geral EP_PERMALINKestá bem:
add_action('init', function() {
add_rewrite_endpoint('movies', EP_PERMALINK);
add_rewrite_endpoint('actors', EP_PERMALINK);
});NB: Se o seu tipo de postagem personalizado é hierárquico, o que significa que tem 'hierarchical' => trueem seu register_post_type(), você precisa trocar a constante EP_PERMALINKpor EP_PAGES.
Depois de salvar este código, você precisa ir para Configurações> Permalinks e simplesmente clicar no botão Salvar para atualizar os permalinks. Sempre que você adiciona ou modifica uma regra de reescrita, você precisa atualizar seus permalinks para que ela funcione!
Manipulando as vars de consulta
A maneira como você, como desenvolvedor de temas ou plugins, pode descobrir se deve ou não mostrar os modelos para esses endpoints é verificando “query vars”; basicamente o objeto de consulta global do WordPress. Fazemos isso chamando get_query_var()com a consulta como argumento (‘filmes’ ou ‘atores’).
Se você já trabalhou com add_rewrite_rule()ou get_query_var()antes, você já deve estar ciente de que o WordPress não adiciona automaticamente vars de consulta personalizadas. Normalmente, você teria que filtrar query_varse adicionar suas variáveis personalizadas para que o WordPress as preenchesse. No entanto add_rewrite_endpoint(), automaticamente faz isso para nós.
No entanto, se tentarmos chamá get_query_var('movies')-lo, nunca parecerá definido. Isso porque ele assume que precisa ter um valor para ser definido. As regras de endpoint pressupõem que o que vem depois do endpoint é o valor. Por exemplo, “example.com/actor/brad-pitt/movies/some-value/” funcionaria, porque nesta página get_query_var('movies')retornaria o valor ‘some-value’. Mas não é isso que queremos, queremos que funcione apenas com o endpoint único. Para resolver isso, precisamos nos conectar ao requestfiltro do WordPress e informar ao WordPress que, se estivermos em nossos endpoints, a consulta vars deve adicionar o endpoint com algum valor (acabamos de defini-lo como true).
add_filter('request', function($vars) {
if (isset($vars['movies'])) {
$vars['movies'] = true;
}
if (isset($vars['actors'])) {
$vars['actors'] = true;
}
return $vars;
});Se você tentar agora usar get_query_vars('movies')quando em “example.com/actor/brad-pitt/movies/” você obterá o valor true(o importante é que ele realmente foi definido).
Carregando modelo
A próxima etapa é decidir o que deve acontecer nesses dois endpoints; ou em outras palavras, quais modelos você deseja carregar. Esta parte é com você, você pode se conectar, template_redirectmas isso só é recomendado se você quiser executar um redirecionamento real. Eu recomendo conectar-se ao template_includefiltro e simplesmente dizer ao WordPress quais modelos usar quando estivermos em nossos endpoints personalizados. Vamos supor que o tema tenha os templates PHP single-actor-movies.phppara “example.com/actor//movies/ e single-movie-actors.phppara “example.com/movie//actors/”.
add_filter('template_include', function($template) {
if (is_singular() && get_query_var('movies')) {
$post = get_queried_object();
return locate_template(['single-actor-movies.php']);
}
if (is_singular() && get_query_var('actors')) {
$post = get_queried_object();
return locate_template(['single-movie-actors.php']);
}
return $template;
});Com esse filtro em vigor, o WordPress deve carregar os modelos fornecidos para nossos terminais personalizados e, dentro desses modelos, o $postobjeto global seria o objeto de postagem único relacionado antes do terminal – por exemplo, o objeto de postagem de ator único quando estivermos no modelo para mostrar todos filmes em que o ator apareceu. Isso facilita a consulta das informações que queremos mostrar.
Obtendo a URL para seu endpoint
Ter nossos endpoints e páginas personalizados é bom e elegante, mas em algum lugar você precisaria vincular a eles. Por exemplo, no modelo de filme único, você gostaria de um link “Ver todos os atores” que vá para o seu endpoint.
Infelizmente, não existe uma função WordPress tão simples para isso. Você precisará criar o URL por conta própria. Eu recomendo usar [get_site_url](https://developer.wordpress.org/reference/functions/get_site_url/)()para endpoints em todo o site ou, no caso acima, você se referiria a uma postagem específica [get_the_permalink](https://developer.wordpress.org/reference/functions/get_the_permalink/)()(dentro do loop ou fornecendo um ID de postagem) e anexando o endpoint depois dela, assim:
echo get_the_permalink(). '/actors';