Shortcodes no WordPress: criar e usar com segurança

Atualizado em 19/06/2026

Um shortcode é uma etiqueta entre colchetes — [galeria], [contato email="..."] — que o WordPress substitui por HTML gerado pelo seu código no momento da exibição. É a forma clássica de dar ao editor um "bloco dinâmico" sem expô-lo a PHP. A API é minúscula (basicamente add_shortcode()), mas há um punhado de armadilhas que derrubam quem está começando — e a primeira delas, o uso de echo no lugar de return, é tão comum que vale começar por ela.

O mapa da API de shortcodes

O callback DEVE retornar (nunca echo)

Esta é a regra de ouro e o erro nº 1. O callback de um shortcode tem que retornar a string final; ele nunca deve imprimir com echo ou print. Entender o porquê resolve o problema de uma vez por todas.

Shortcodes são expandidos pela função do_shortcode(), que está registrada como um filter em the_content. Quando o WordPress vai exibir um post, ele monta o texto do conteúdo em memória e passa essa string pelos filtros. O do_shortcode() procura suas tags nessa string e substitui cada tag pelo valor retornado pelo callback, na posição exata. Se o seu callback faz echo, ele escreve direto no fluxo de saída antes de essa string montada ser impressa — resultado: o conteúdo do shortcode aparece deslocado, tipicamente no topo da página, e a tag em si vira string vazia.

<?php
add_shortcode( 'saudacao', 'dwp_sc_saudacao' );

// ERRADO: imprime fora de ordem (sobe para o topo da página).
function dwp_sc_saudacao_errado( $atts ) {
    echo '<p>Olá!</p>'; // NUNCA faça isto num shortcode
}

// CERTO: retorna a string para o WordPress encaixá-la no lugar.
function dwp_sc_saudacao( $atts ) {
    return '<p>Olá!</p>';
}

Shortcode com atributos e shortcode_atts()

Atributos chegam ao callback no primeiro parâmetro, $atts. Dois fatos definem como você os trata: eles sempre chegam como string (não há tipagem) e $atts pode até ser uma string vazia quando nenhum atributo é informado. Por isso você nunca lê $atts direto — passa por shortcode_atts(), que mescla com seus padrões, descarta chaves desconhecidas e garante um array previsível:

<?php
add_shortcode( 'botao', 'dwp_sc_botao' );

function dwp_sc_botao( $atts, $content = null, $tag = '' ) {
    // Mescla com padrões; o 3º arg habilita filtros por tag.
    $a = shortcode_atts(
        array(
            'url'   => '#',
            'texto' => 'Clique aqui',
            'cor'   => 'azul',
        ),
        $atts,
        $tag
    );

    // Atributos são entrada NÃO confiável: escape conforme o contexto.
    $url   = esc_url( $a['url'] );
    $texto = esc_html( $a['texto'] );
    $cor   = sanitize_html_class( $a['cor'] ); // vira classe CSS segura

    return sprintf(
        '<a class="btn btn--%1$s" href="%2$s">%3$s</a>',
        esc_attr( $cor ),
        $url,
        $texto
    );
}
// Uso no editor: [botao url="https://exemplo.com" texto="Comprar" cor="verde"]

Três pontos de especialista aqui. Primeiro, shortcode_atts() só mantém as chaves que você declarou nos padrões — se alguém passar [botao onmouseover="..."], esse atributo é simplesmente ignorado. Segundo, os nomes dos atributos são minúsculos: [botao COR="verde"] chega como cor. Terceiro, escapamos cada valor segundo o contexto: esc_url() para a URL, esc_html() para o texto visível e esc_attr()/sanitize_html_class() para a classe — porque atributos do editor são dados não confiáveis como quaisquer outros.

Shortcodes de fechamento (enclosing)

Quando o shortcode envolve conteúdo — [destaque]texto aqui[/destaque] — o WordPress entrega o miolo no segundo parâmetro, $content. O mesmo callback pode servir aos dois formatos: basta tratar o caso em que $content chegou. E, crucialmente, se você quer que shortcodes dentro do conteúdo também sejam processados, precisa chamar do_shortcode( $content ) — o WordPress não faz isso recursivamente sozinho:

<?php
add_shortcode( 'destaque', 'dwp_sc_destaque' );

function dwp_sc_destaque( $atts, $content = null, $tag = '' ) {
    $a = shortcode_atts(
        array( 'tipo' => 'info' ),
        $atts,
        $tag
    );

    // Sem conteúdo? Devolve vazio em vez de quebrar.
    if ( null === $content ) {
        return '';
    }

    // do_shortcode() processa shortcodes ANINHADOS dentro do conteúdo.
    $interno = do_shortcode( $content );

    return sprintf(
        '<div class="destaque destaque--%1$s">%2$s</div>',
        esc_attr( $a['tipo'] ),
        $interno
    );
}
// Uso: [destaque tipo="aviso"]Texto com [botao texto="ação"] dentro.[/destaque]

Note que não escapamos $content com esc_html(): ele é HTML do editor (pode conter <strong>, links, outros shortcodes) e escapá-lo exibiria as tags como texto cru. Passamos por do_shortcode() e confiamos na sanitização que o WordPress já aplica ao conteúdo do post. O cuidado com escaping recai sobre os atributos, que são os valores realmente arbitrários.

Rodando shortcodes em templates: do_shortcode()

Shortcodes só são expandidos onde o filtro de shortcode roda — ou seja, no the_content. Se você está num arquivo de template do tema, num cabeçalho, num campo personalizado ou em qualquer string que não passe por aquele filtro, a tag aparece literalmente. A solução é processar a string explicitamente com do_shortcode():

<?php
// Em um template do tema (ex.: page.php, sidebar.php):
echo do_shortcode( '[botao url="/contato" texto="Fale conosco"]' );

// Ou processando um campo personalizado que pode conter shortcodes:
$texto = get_post_meta( get_the_ID(), 'rodape_promocional', true );
echo do_shortcode( $texto );

Aqui o echo é legítimo: estamos num template, fora do filtro the_content, e do_shortcode() nos retorna a string já expandida — somos nós que decidimos imprimir. Isso não contradiz a regra anterior: a proibição de echo vale dentro do callback do shortcode, não em quem chama do_shortcode().

Utilitários: existência e remoção

Como o registro é global, a última chamada a add_shortcode() para uma tag vence — sobrescrevendo silenciosamente quem registrou antes. Para conviver bem com outros plugins, há dois utilitários:

• shortcode_exists( 'tag' ) — retorna true se a tag já está registrada. Útil para não atropelar um plugin existente ou para registrar só se ninguém o fez.
• remove_shortcode( 'tag' ) — desregistra uma tag (por exemplo, para substituir o comportamento de um shortcode de outro plugin). Existe também remove_all_shortcodes(), que raramente deve ser usado em produção por afetar tudo.

<?php
// Registre cedo, mas só se a tag ainda não existir.
add_action( 'init', function () {
    if ( ! shortcode_exists( 'destaque' ) ) {
        add_shortcode( 'destaque', 'dwp_sc_destaque' );
    }
} );

// Substituir um shortcode de terceiro pelo seu:
remove_shortcode( 'destaque' );
add_shortcode( 'destaque', 'dwp_sc_destaque' );

Armadilhas comuns

Boas práticas

• Sempre return, jamais echo dentro do callback. Se algo só imprime, capture com ob_start()/ob_get_clean().
• Use shortcode_atts() com padrões explícitos. Ele documenta os atributos aceitos, descarta o resto e evita avisos de chave indefinida.
• Trate atributos como entrada não confiável. Converta tipos e escape na saída segundo o contexto — atributos vêm do editor, que pode ser um usuário com permissões limitadas.
• Prefixe a tag com o slug do seu projeto ([dwp_botao]) para reduzir colisão com outros plugins no namespace global de shortcodes.
• Mantenha o callback barato. Ele roda a cada exibição do conteúdo; consultas pesadas pedem cuidado e, idealmente, cache.
• Registre em um hook (init), não no escopo do arquivo, e considere shortcode_exists() antes de sobrescrever.
• Em blocos modernos, lembre que o editor de blocos oferece o bloco "Shortcode"; ainda assim, a sintaxe [tag] continua válida e amplamente compatível.

Resumindo a mentalidade: um shortcode é uma função pura que recebe atributos e conteúdo e devolve uma string de HTML seguro. Quem internaliza isso — retornar, normalizar com shortcode_atts(), escapar atributos e usar do_shortcode() onde o filtro não chega — escreve shortcodes que não brigam com o tema, com outros plugins nem com a segurança do site.