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

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ção	is_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.php, post.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)