🛠 Como adicionar um campo personalizado a muitos artigos no WordPress

Um site em WordPress cresceu para centenas de artigos, e cada um precisa de um novo campo personalizado. Abrir cada artigo à mão e clicar em «Atualizar» é um trabalho de meio dia, no mínimo.

Especialmente se estiver a refinar um tema ou a ligar um plugin de SEO que precisa da mesma meta_key em todo o feed de artigos. O painel de administração do WordPress não oferece um botão «aplicar a todos», mas dá-lhe duas formas de resolver isto com código.

Abaixo, ambos os métodos com snippets prontos a usar: rápido (uma consulta SQL para todo o lote) e simples (um ciclo sobre os IDs usando a função nativa add_post_meta). Escolha com base na tarefa.

💡 Resumo rápido:

• Pode atribuir em massa o mesmo campo personalizado a todos os artigos usando add_post_meta num ciclo, 4 linhas de código.
• Se houver centenas de artigos e a velocidade for importante, um INSERT direto na tabela wp_postmeta através de uma função personalizada.
• Ambos os métodos funcionam através do functions.php do tema ou do plugin Code Snippets. Faça uma cópia de segurança da base de dados antes de executar qualquer SQL.

Porquê adicionar um campo a muitos artigos de uma vez

Os campos personalizados (também conhecidos como post meta) armazenam informações adicionais sobre um registo: contagem de visualizações, tags para filtragem interna, um indicador de «favorito», um ID de produto relacionado. Qualquer coisa que não caiba nos campos padrão post_title e post_content.

Normalmente, um campo é adicionado caso a caso: abre-se um artigo, encontra-se o bloco «Campos Personalizados» no editor, insere-se um par chave-valor. Mas quando o campo tem de aparecer em todos os 200 artigos de uma vez, o método manual está fora de questão.

Cenários típicos onde a ação em massa é necessária:

• Ativou um tema filho que usa get_post_meta($post_id, 'featured_post', true) para marcar artigos populares. Sem o preenchimento em massa, os artigos antigos não aparecerão no output.
• Uma auditoria de SEO exigiu definir noindex para um tipo de conteúdo específico através de um campo meta, em vez de o fazer via robots.txt.
• Migração de outra plataforma: os dados do CMS antigo chegaram num CSV e precisam de ser carregados na wp_postmeta para milhares de registos.

O WordPress não tem uma função nativa add_multiple_posts_meta. Mas existem dois caminhos comprovados, escolha com base na situação.

Método 1. Uma consulta SQL para todos os artigos

O método mais rápido, um INSERT direto na tabela wp_postmeta numa única transação. Em vez de 200 consultas individuais à base de dados, faz uma, e executa em milissegundos.

Abaixo, a função add_multiple_posts_meta, que aceita um array de IDs de artigos e espelha a assinatura da função nativa add_post_meta: mesmos parâmetros, mesma ordem.

Adicione o código ao functions.php do tema filho ou através do plugin Code Snippets. A própria função verifica se tal campo já existe para o artigo (se $unique = true for passado) e filtra IDs inválidos.

1
if( !function_exists( 'add_multiple_posts_meta' ) ){
2
    function add_multiple_posts_meta( $post_ids, $meta_key, $meta_value, $unique = false ){
3
 
4
        // If key or ID is not set — exit
5
        if( !$meta_key || empty( $post_ids ) ){
6
            return false;
7
        }
8
 
9
        // One post — pass to native add_post_meta
10
        if( is_numeric( $post_ids ) || ( is_array( $post_ids ) && count( $post_ids ) === 1 ) ){
11
            return add_post_meta(
12
                is_array( $post_ids ) ? $post_ids[0] : $post_ids,
13
                $meta_key,
14
                $meta_value,
15
                $unique
16
            );
17
        }
18
 
19
        global $wpdb;
20
 
21
        // Filter out invalid IDs and duplicates
22
        $valid_post_ids = array_unique(
23
            array_filter( $post_ids, function( $post_id ) use ( $wpdb, $meta_key, $unique ){
24
                return $post_id
25
                    && is_numeric( $post_id )
26
                    && get_post_status( $post_id )
27
                    && (
28
                        ! $unique
29
                        || ! $wpdb->get_var( $wpdb->prepare(
30
                            "SELECT COUNT(*) FROM $wpdb->postmeta WHERE post_id = %d AND meta_key = %s",
31
                            $post_id,
32
                            $meta_key
33
                        ) )
34
                    );
35
            } )
36
        );
37
 
38
        if( ! count( $valid_post_ids ) ){
39
            return false;
40
        }
41
 
42
        // Sanitization
43
        $meta_key   = wp_unslash( $meta_key );
44
        $meta_value = sanitize_meta( $meta_key, wp_unslash( $meta_value ), 'post' );
45
 
46
        // Collect data and format strings for a single INSERT
47
        $insert_data    = [];
48
        $insert_formats = [];
49
 
50
        foreach( $valid_post_ids as $post_id ){
51
            array_push( $insert_data, $post_id, $meta_key, $meta_value );
52
            $insert_formats[] = '(%d, %s, %s)';
53
        }
54
 
55
        $sql_string = "INSERT INTO $wpdb->postmeta (`post_id`, `meta_key`, `meta_value`) VALUES "
56
            . implode( ', ', $insert_formats );
57
 
58
        // ... unpacks the array into separate arguments for prepare
59
        $sql_query = $wpdb->prepare( $sql_string, ...$insert_data );
60
 
61
        return $wpdb->query( $sql_query );
62
    }
63
}

O que acontece aqui linha a linha. A verificação !function_exists é uma salvaguarda contra conflitos: se outro plugin já tiver declarado uma função com esse nome, não haverá erro fatal. O bloco is_numeric($post_ids) passa um único ID para a função nativa add_post_meta, para que a mesma função funcione tanto com um único artigo como com um array. O filtro array_filter descarta IDs de rascunhos, registos eliminados e aqueles para os quais o campo único já existe. A sanitização via wp_unslash e sanitize_meta é obrigatória: sem ela, dados serializados e caracteres especiais quebrarão a consulta.

*Nota importante sobre ...$insert_data.* O operador ... (splat) desempacota o array numa lista plana de argumentos. Sem ele, $wpdb->prepare receberia um argumento array em vez de um conjunto de (%d, %s, %s), e a consulta falharia com um erro de contagem de placeholders. PHP 5.6+ (o WordPress requer um mínimo de 7.0, por isso está seguro).

Como usar

Passe um array de IDs de artigos, a chave e o valor como uma chamada normal. O quarto parâmetro, o indicador de unicidade: true não adicionará o campo se ele já existir para o artigo.

1
$post_ids   = [ 1, 2, 3, 42, 108 ];
2
$meta_key   = 'featured_priority';
3
$meta_value = 'high';
4
$unique     = false; // will set for all, even if the field already existed
5
 
6
add_multiple_posts_meta( $post_ids, $meta_key, $meta_value, $unique );

É conveniente executar tal chamada através do hook init (uma vez, depois removê-lo) ou via WP-CLI com o comando wp eval-file. Após a execução, certifique-se de remover o código do functions.php, caso contrário a função será executada em cada carregamento de página.

Método 2. Ciclo sobre IDs com add_post_meta

Se não quiser mexer diretamente em SQL, use a função nativa add_post_meta num ciclo. O código é quatro vezes mais curto e depende inteiramente do núcleo do WordPress.

1
$post_ids   = [ 1, 2, 3, 42, 108 ];
2
$meta_key   = 'featured_priority';
3
$meta_value = 'high';
4
$unique     = false;
5
 
6
foreach( $post_ids as $post_id ){
7
    add_post_meta( $post_id, $meta_key, $meta_value, $unique );
8
}

O ciclo itera sobre o array e chama add_post_meta para cada ID. A própria função verifica a existência do registo, a unicidade da chave (se $unique = true estiver definido) e a correção dos dados; não é necessária validação adicional.

Desempenho. Com uma centena de artigos, a diferença em relação à consulta SQL é impercetível. Mas se tiver 5.000 registos, cada chamada add_post_meta gera um INSERT separado, mais hooks internos (added_post_meta, update_post_meta_cache). Com esses volumes, o primeiro método com uma única consulta será executado 10 a 20 vezes mais rápido.

Para operações pontuais com um par de dúzias de artigos, use o ciclo, não complique.

Comparação de abordagens

Uma regra universal: se houver menos de cem artigos e a operação for pontual, use o ciclo. Se envolver sincronização regular ou migração de milhares de registos, apenas a consulta direta com a função preparada.

⁉️🤔 Perguntas frequentes

Posso atribuir um campo seletivamente, apenas a artigos de uma categoria específica?

Sim. Obtenha os IDs dos artigos via get_posts com o parâmetro 'category' => ID_рубрики e, em seguida, passe o array para um dos dois métodos acima. Para milhares de artigos, adicione 'numberposts' => -1 e 'fields' => 'ids'; a consulta devolverá apenas um array de IDs, sem carregar objetos.

Aqui está um exemplo pronto a usar: $post_ids = get_posts( [ 'category' => 5, 'numberposts' => -1, 'fields' => 'ids', 'post_type' => 'post' ] );. Depois, chame add_multiple_posts_meta($post_ids, ...) ou um ciclo com add_post_meta.

E se eu precisar de um valor de campo diferente para artigos diferentes?

A inserção em massa não funcionará aqui. Construa um array associativo [ ID_поста => значение ] e itere sobre ele num ciclo com add_post_meta ou update_post_meta. Um valor para todos, SQL; valores diferentes para artigos diferentes, apenas um ciclo.

Para mais de 50 artigos com valores únicos, use update_post_meta em vez de add_post_meta: não cria duplicados se o campo já existir.

É seguro escrever consultas SQL diretamente na wp_postmeta?

É seguro sob duas condições. Primeiro: execute sempre os dados através de $wpdb->prepare; escapa caracteres especiais e bloqueia injeções de SQL. Segundo: faça uma cópia de segurança completa da base de dados antes de executar. Um UPDATE incorreto sem WHERE e a wp_postmeta é limpa para todos os registos.

Comando de cópia de segurança via WP-CLI: wp db export backup-before-meta.sql. Restauro: wp db import backup-before-meta.sql.

Como é que add_post_meta difere de update_post_meta?

add_post_meta adiciona uma nova linha à wp_postmeta, mesmo que a chave já exista para o artigo, resultando num duplicado. update_post_meta verifica a existência da chave: se existir, atualiza o valor; se não, cria-o. Para preenchimento em massa onde há uma chave por artigo, add_post_meta com $unique = true produz o mesmo efeito.

Na prática: add_post_meta($id, 'views', 0, true) criará o campo uma vez e nunca mais lhe tocará. update_post_meta($id, 'views', $count) sobrescreverá o valor em cada chamada.

Onde devo colocar o código, no tema ou num plugin?

Para operações pontuais, no functions.php do tema filho, com remoção imediata após a execução. Para tarefas recorrentes, empacote-o como um plugin Must-Use (pasta wp-content/mu-plugins/) ou adicione-o ao Code Snippets com o indicador «Executar uma vez». Código num tema ativo sem remoção irá atingir a base de dados em cada carregamento de página; isso é carga desnecessária.

O que escolher para a sua tarefa

A prática mostra: 9 em cada 10 casos são cobertos pelo ciclo com add_post_meta. São quatro linhas de código, uma função nativa e sem surpresas.

Uma consulta SQL direta justifica-se em duas situações: migração em massa (milhares de artigos, o tempo é valioso) e sincronização periódica onde controla a sanitização na entrada. Caso contrário, não complique.

O que fazer agora:

• Se precisar de atribuir um campo a ≤100 artigos, copie o ciclo do segundo método, insira os seus IDs e execute-o.
• Se houver vários milhares de artigos, use a função do primeiro método, mas teste-a primeiro numa cópia do site.
• Em qualquer cenário, faça uma cópia de segurança da base de dados antes de executar. Isto não é uma precaução; é uma regra.

E que método costuma usar para adicionar campos personalizados: através do painel de administração, código ou um plugin como o ACF? Escreva nos comentários, é interessante comparar abordagens.