Exportar dados do WordPress nem sempre exige um plugin. Se precisa de posts, utilizadores, submissões de formulários ou encomendas WooCommerce numa folha de cálculo, o método certo depende do tamanho do conjunto, de quem consome o ficheiro e de com que frequência o trabalho corre.
Use CSV simples na maioria das exportações, faça stream com fputcsv() para downloads no browser, processe em lotes com WP_Query e passe para WP-CLI quando um pedido de admin bater nos limites de memória ou timeout. Recorra à REST API quando outro sistema precisa de dados estruturados em vez de um ficheiro.
Escolher o método de exportação certo
Três abordagens cobrem quase todos os trabalhos de exportação no WordPress:
- PHP dentro do WordPress para downloads no admin com verificação de capacidades
- WP-CLI para conjuntos grandes e trabalhos agendados no servidor
- REST API para dashboards, warehouses, CRMs e consumidores headless
Exportações ocasionais e pequenas cabem bem num download PHP. Tabelas recorrentes ou muito grandes pertencem à CLI. Sistemas externos devem puxar JSON via REST e moldar o CSV fora do WordPress quando ainda precisarem de uma folha.
Combine o método com o modo de falha. Downloads no browser falham por timeout. Plugins falham quando tentam construir um objeto de folha inteiro num único pedido. Dumps SQL ad hoc falham quando os nomes das colunas mudam após uma atualização de plugin. Escolha o caminho que mantém a exportação reproduzível no mês seguinte, não só hoje.
Numa loja portuguesa a enviar relatórios financeiros por email, o padrão que mais vezes salvou o pedido foi WP-CLI à noite e CSV diurno só para amostras. Precisa de um exportador ligado ao seu stack? Fale com um programador WordPress que já tenha enviado exportações em produção, ou contacte-nos.
CSV vs XLSX
Comece por CSV a menos que um stakeholder tenha um requisito rígido de .xlsx.
Pontos fortes do CSV
- Fácil de gerar com PHP ou WP-CLI
- Fácil de inspecionar e depurar num editor de texto
- Abre no Excel, Numbers e Google Sheets
- Evita bibliotecas XLSX e o custo de memória delas
Compromissos do XLSX
- Formato binário com folhas, estilos e strings partilhadas
- Precisa de uma biblioteca como PhpSpreadsheet ou de um passo de conversão pós-exportação
- Constrói mais estado em memória antes do ficheiro estar completo
- Mais difícil de fazer stream com segurança durante um pedido HTTP longo
Padrão prático: exporte CSV a partir do WordPress e converta depois com Excel, LibreOffice ou um script offline pequeno se alguém insistir em XLSX. Assim o pedido WordPress mantém-se leve.
Dica Excel: ficheiros CSV em UTF-8 por vezes precisam de um BOM (\xEF\xBB\xBF) para o Excel no Windows abrir corretamente acentos e cedilhas. Escreva o BOM antes da linha de cabeçalho quando o público vive no Excel.
Exportar CSV com PHP
Em ferramentas de admin personalizadas, faça stream do CSV para o browser. As verificações de capacidade vêm primeiro. Depois defina cabeçalhos, abra php://output, escreva a linha de cabeçalho e faça stream das linhas de dados.
function wppoland_export_users_csv() {
if ( ! current_user_can( 'manage_options' ) ) {
wp_die( 'Acesso negado.' );
}
header( 'Content-Type: text/csv; charset=utf-8' );
header( 'Content-Disposition: attachment; filename=users-export.csv' );
$output = fopen( 'php://output', 'w' );
// BOM opcional para Excel no Windows:
// fwrite( $output, "\xEF\xBB\xBF" );
fputcsv( $output, array( 'ID', 'Email', 'Registered' ) );
$users = get_users(
array(
'fields' => array( 'ID', 'user_email', 'user_registered' ),
'number' => 500,
)
);
foreach ( $users as $user ) {
fputcsv(
$output,
array(
$user->ID,
$user->user_email,
$user->user_registered,
)
);
}
fclose( $output );
exit;
}Este padrão funciona para exportações mais pequenas e ferramentas internas de admin. Não reúna todas as linhas num array PHP gigante para depois fazer implode. Faça stream de cada linha à medida que a obtém.
Proteja o endpoint com nonce e verificação de capacidade. Exportações de utilizadores e encomendas costumam conter dados pessoais, por isso trate-as como qualquer outra ação privilegiada de admin sob regras no espírito do RGPD: registe quem correu a exportação e mantenha o ficheiro fora de URLs públicas.
Processar em lotes com WP_Query e evitar limites de memória
O modo de falha habitual é carregar demasiado de uma vez. Limites de memória PHP, max_execution_time e timeouts de reverse proxy matam exportações longas no admin. Processe em lotes com WP_Query usando posts_per_page e offset, ou, melhor, pagine com um cursor estável quando o offset fica caro em tabelas grandes.
$offset = 0;
$limit = 500;
do {
$query = new WP_Query(
array(
'post_type' => 'post',
'post_status' => 'publish',
'posts_per_page' => $limit,
'offset' => $offset,
'fields' => 'ids',
'no_found_rows' => true,
'update_post_meta_cache' => false,
'update_post_term_cache' => false,
)
);
foreach ( $query->posts as $post_id ) {
fputcsv( $output, array( $post_id, get_the_title( $post_id ) ) );
}
$offset += $limit;
wp_cache_flush(); // opcional em loops muito longos em CLI/ferramentas de admin
} while ( ! empty( $query->posts ) );Porque isto ajuda:
fields => 'ids'mantém a hidratação de objetos leve- Desativar caches de meta e termos impede o object cache de crescer sem limite
- Tamanhos de lote fixos mantêm o pico de memória perto de uma página de linhas
- Stream com
fputcsv()evita guardar a string CSV completa em RAM
Em tabelas muito grandes, o próprio offset fica lento porque o MySQL ainda percorre as linhas descartadas. Prefira keyset pagination: WHERE ID > last_id ORDER BY ID ASC LIMIT N. Em trabalhos CLI, esse padrão vale o código extra.
Referência oficial dos argumentos de consulta: a classe WP_Query em developer.wordpress.org.
Usar WP-CLI para exportações pesadas
Quando exporta dezenas de milhares de linhas, o WP-CLI evita o browser e a cadeia de timeouts do servidor web.
wp post list --post_type=post --fields=ID,post_title,post_date --format=csv > posts.csvÚtil para:
- catálogos grandes de posts ou produtos
- dumps de encomendas WooCommerce que dariam timeout no wp-admin
- exportações noturnas via cron para object storage ou uma pasta partilhada
- entregas de migração e reporting
Documentação do comando: wp post list.
Também pode escrever um comando WP-CLI personalizado que abre um ficheiro, pagina com WC_Order_Query ou WP_Query e escreve CSV em disco. Isso mantém a memória previsível e permite retomar a partir de um checkpoint se o trabalho for interrompido.
Usar a REST API quando outro sistema precisa dos dados
Se o consumidor é software, não uma pessoa com Excel, a REST API é muitas vezes mais limpa do que gerar CSV dentro do WordPress.
Casos típicos:
- sincronizar conteúdo para um warehouse ou ferramenta de BI
- alimentar um CRM a partir de utilizadores ou leads
- front ends headless que precisam de payloads estruturados de posts
Referência da coleção de posts: endpoint de Posts.
A REST devolve JSON. Paginem com page e per_page, autentiquem com Application Passwords ou fluxos OAuth que o hosting suporte, e respeitem rate limits. Construam o CSV a jusante se ainda for preciso uma folha. Essa divisão mantém o WordPress responsável pelo acesso autorizado e deixa a formatação do ficheiro ao consumidor.
Não exponha rotas privilegiadas de exportação sem autenticação. Trate endpoints de exportação como qualquer outra superfície de admin adjacente a escrita, mesmo quando só leem.
Armadilhas na exportação de encomendas WooCommerce
Exportações de encomendas parecem simples até linhas de item, reembolsos e HPOS mudarem o quadro.
Linhas de item não são uma única linha. Uma encomenda pode ter vários produtos, taxas, portes e impostos. Decida à partida se uma linha CSV significa uma encomenda ou uma linha de item. Misturar ambos sem um esquema claro produz folhas inutilizáveis.
Meta e campos personalizados explodem a largura. IDs de gateway de pagamento, números de tracking e meta de plugins criam colunas largas e esparsas. Exporte só os campos de que o relatório precisa. Adicione um segundo ficheiro para linhas de item se tiver de manter as duas formas.
Os backends de armazenamento diferem. Posts clássicos shop_order e tabelas High-Performance Order Storage (HPOS) não se consultam da mesma forma. Prefira o CRUD do WooCommerce (wc_get_orders() / WC_Order_Query) em vez de WP_Query cru em shop_order, para o exportador sobreviver a mudanças de storage.
Filtros de estado importam. Rascunhos, pagamentos falhados, reembolsos e lixo inflacionam ou distorcem relatórios de receita. Documente que estados inclui.
PII e acesso. Encomendas incluem nomes, emails e moradas. Verificações de capacidade (manage_woocommerce ou uma capacidade personalizada), nonces e logs de auditoria pertencem a todos os exportadores de admin. Prefira WP-CLI para dumps em volume para o ficheiro nunca ficar num caminho de uploads publicamente alcançável.
Desempenho. Juntar todas as chaves de meta de encomenda num único SQL parece rápido até a tabela crescer. Paginem as encomendas, hidratem cada uma com wc_get_order(), escrevam a linha e descartem o objeto. Esse padrão é mais lento por encomenda do que um JOIN gigante e bem mais estável sob limites de memória.
Moeda e formatação. Guarde totais como números simples. Deixe o Excel formatar moeda. Separadores de milhares específicos do locale dentro de campos CSV partem importações noutros ferramentas.
Campos de data. Guarde ISO-8601 ou timestamps Unix no CSV e formate na folha. Strings de data locais misturadas (03/04/2026 vs 04/03/2026) causam bugs silenciosos de reordenação quando o ficheiro atravessa regiões - comum entre equipas em Lisboa e clientes no Reino Unido.
Reembolsos e reembolsos parciais. Decida se totais reembolsados aparecem como linhas negativas, IDs de reembolso separados ou totais líquidos da encomenda. Documente a escolha num README junto ao cron de exportação para finanças e engenharia concordarem na mesma folha.
Juntar as peças
- Prefira CSV a XLSX dentro do WordPress.
- Faça stream com
fputcsv()e verificações de capacidade para downloads pequenos no admin. - Processe em lotes com
WP_Queryou consultas WooCommerce; desative caches desnecessários. - Passe trabalhos grandes ou agendados para WP-CLI.
- Use a REST API quando outro sistema puxa dados estruturados.
- No WooCommerce, defina o grão da linha (encomenda vs linha de item) e use APIs CRUD para o HPOS não partir o exportador.
Bem feito, as exportações WordPress ficam aborrecidas: colunas previsíveis, memória limitada e sem timeouts surpresa durante um relatório de pico de tráfego.
