Qual é a diferença entre is_single() e is_singular() do WordPress e quando utilizar cada função?3 min leitura

Aprenda qual é a diferença entre as tags condicionais is_singular() e is_single() e não erre mais ao escrever códigos para o WordPress.

Aprender o que são e como utilizar tags condicionais (Conditional Tags) é um passo bem importante para quem está começando com desenvolvimento no WordPress. Elas são funções booleanas (retornam verdadeiro ou falso) utilizadas para executar uma ação dependendo do tipo de conteúdo que o usuário está visualizando. Entre elas, duas costumam ser bastante confundidas: is_single() e is_singular(). Vamos ver qual é a diferença entre as duas?

Como funciona a função is_single()

A função is_single() determina se o visitante está vendo um conteúdo individual de qualquer tipo de post (incluindo Custom Post Types), que não seja uma página ou página de anexo.

A função aceita um parâmetro opcional, com quatro tipos de valores:

  • ID do post (int), exemplo: is_single( 10 );
  • Título (string), exemplo: is_single( 'Teste Novo' );
  • Slug (string), exemplo: is_single( 'teste-novo' );
  • Array com ID do post e/ou slug (int[]|string[]), exemplo: is_single( array( 10, 'teste-novo') ).

Um aviso importante: is_single() não faz distinção entre o que é um ID do post, título ou slug. Isto quer dizer que is_single( 10 ) irá retornar verdadeiro para um post com título, slug ou ID iguais a 10, ou seja, pode ser verdadeiro para até 3 posts diferentes.

Como funciona a função is_singular()

A função is_singular() determina se o visitante está vendo um conteúdo individual de qualquer tipo de post (incluindo Custom Post Types), página ou página de anexo.

A função aceita um parâmetro opcional, com dois formatos de valores:

  1. Um nome de tipo de post (string), exemplo: is_singular( 'livro' );
  2. Mais de um nome de tipo de post (string[]), exemplo: is_singular( array( 'livro', 'filme') ).

Uma maneira alternativa de entender esta função, é considerar que ela retorna verdadeiro para is_single() ou is_page() ou is_attachment().

Utilizo esta função bastante quando preciso executar um código somente para um Custom Post Type específico.

Diferença entre is_single() e is_singular()

Para ajudar a visualizar a diferença entre as duas funções, montei uma tabela com a aplicação das mesmas em diferentes cenários.

Conteúdo / Retorno Funçãois_single()is_singular()is_singular( ‘livro’ )
Post do CPT “livro” (ex: /livro/trabalho-focado/)✅ Verdadeiro✅ Verdadeiro✅ Verdadeiro
Post do blog (ex: /contrato-habito-semanal/)✅ Verdadeiro✅ Verdadeiro❌ Falso
Página de anexo❌ Falso✅ Verdadeiro❌ Falso
Página (ex: /contato/)❌ Falso✅ Verdadeiro❌ Falso

Informações adicionais

É importante saber que o WordPress carrega o arquivo functions.php antes de executar a query de um conteúdo. Portanto, se você simplesmente adicionar uma tag condicional dentro deste arquivo, ela não vai funcionar.

Há duas maneiras de implementar Tags Condicionais:

  1. Dentro de um arquivo de template, exemplos: header.phppost.php e page.php;
  2. Criando uma função dentro do functions.php conectada com uma action ou filter executada em um outro momento;

Veja abaixo um exemplo que como seria um código utilizando segunda opção, que executa a função antes do início de um loop:

add_action( 'loop_start', 'danielkossmann_tag_condicional' ); function danielkossmann_tag_condicional() { if ( is_singular() ) { echo "<hr>É singular.<hr>"; } }
Code language: PHP (php)

Similar Posts

Você tem algo construtivo sobre este texto para dizer? Então comente abaixo