claude-plugins/wordpress/skills/elementor/references/automation.md

Elementor — Automação Programática e Pipelines

Referência técnica para manipular o Elementor sem GUI: WP-CLI, MySQL, REST API, PHP Hooks, Kits e CSS.

---

1. WP-CLI + Elementor (CWP)

Formato Obrigatório CWP

PHP="/opt/alt/php-fpm83/usr/bin/php"
WP="$PHP /usr/local/bin/wp --allow-root --path=/home/USER/public_html"

Comandos Essenciais

# Regenerar CSS (SEMPRE após qualquer alteração programática)
$WP elementor flush-css --regenerate

# Substituição segura de URLs (evita corrupção JSON)
# NUNCA usar wp search-replace directamente em _elementor_data
$WP elementor replace-urls $URL_OLD $URL_NEW
$WP search-replace $URL_OLD $URL_NEW --skip-columns=guid

# Importar Kit (design system completo)
$WP elementor kit import /tmp/kit.zip \
  --include=site-settings,templates,content \
  --overrideConditions=all

# Sincronizar esquema BD após update do plugin
$WP elementor update db

# Modo manutenção
$WP maintenance-mode activate
$WP maintenance-mode deactivate

Pipeline de Deploy Completo

#!/bin/bash
# Pipeline de rebranding via WP-CLI (CWP)
PHP="/opt/alt/php-fpm83/usr/bin/php"
SITE_PATH="/home/USER/public_html"
KIT_PATH="/tmp/rebranding-2026.zip"
URL_OLD="https://staging.agencia.com"
URL_NEW="https://www.producao.com"
WP="$PHP /usr/local/bin/wp --allow-root --path=$SITE_PATH"

$WP maintenance-mode activate
$WP elementor kit import $KIT_PATH --include=site-settings,templates,content --overrideConditions=all
$WP elementor replace-urls $URL_OLD $URL_NEW
$WP search-replace $URL_OLD $URL_NEW --skip-columns=guid
$WP elementor flush-css --regenerate
$WP elementor update db
$WP maintenance-mode deactivate

Avaliação do Método

Critério	Análise
Complexidade	Baixa — sintaxe documentada, comportamento previsível
Segurança	Alta — invoca internos do WordPress, risco apenas em SSH
Usar quando	Deploy, purga de cache, migração de URLs, sincronização BD

---

2. Manipulação Directa via MySQL

Estrutura _elementor_data

O Elementor guarda layouts como JSON em wp_postmeta. Três meta keys obrigatórias:

Meta Key	Valor
_elementor_edit_mode	builder
_elementor_template_type	wp-page, kit, header, footer
_elementor_data	JSON array com toda a árvore de widgets

Estrutura JSON Interna

[{
  "id": "3130e2cf",
  "elType": "container",
  "isInner": false,
  "settings": { ... },
  "elements": [{
    "id": "a1b2c3d4",
    "elType": "widget",
    "widgetType": "button",
    "settings": {
      "text": "Clique aqui",
      "link": { "url": "https://exemplo.com" }
    }
  }]
}]

Query MySQL com JSON_REPLACE

-- Substituição cirúrgica num widget específico
-- SEMPRE fazer backup antes
UPDATE wp_postmeta
SET meta_value = JSON_REPLACE(
    meta_value,
    '$.elements.elements.settings.link.url',
    'https://www.novo-destino.com/contacto'
)
WHERE meta_key = '_elementor_data'
AND post_id IN (1042, 1045, 1088);

-- OBRIGATÓRIO após qualquer UPDATE directo:
-- Executar 'wp elementor flush-css --regenerate' via WP-CLI

Regra Crítica: NUNCA wp search-replace

# ERRADO — corrompe JSON silenciosamente (whitespace of death)
wp search-replace 'http://antigo.com' 'https://novo.com'

# CORRECTO — usa lógica nativa do Elementor
wp elementor replace-urls 'http://antigo.com' 'https://novo.com'

Avaliação do Método

Critério	Análise
Complexidade	Alta — parsing JSON, funções MySQL JSON_*
Segurança	Muito Baixa — sem validação, um char inválido corrompe a página
Usar quando	Auditoria forense, extracção analítica em massa (10.000+ posts)

---

3. REST API Custom Endpoint

Para agentes externos (n8n, Make, Python) manipularem layouts via HTTP.

Registar Endpoint (functions.php ou plugin MU)

<?php
add_action('rest_api_init', function () {
    register_rest_route('agencia-ai/v1', '/atualizar-layout', [
        'methods' => 'POST',
        'callback' => 'ai_agent_update_elementor_layout',
        'permission_callback' => function() {
            return current_user_can('edit_pages');
        }
    ]);
});

function ai_agent_update_elementor_layout(WP_REST_Request $request) {
    $post_id   = absint($request->get_param('post_id'));
    $json_data = $request->get_param('elementor_json');

    // wp_slash é OBRIGATÓRIO — protege JSON de corrupção de escape
    update_post_meta($post_id, '_elementor_data', wp_slash(json_encode($json_data)));
    update_post_meta($post_id, '_elementor_edit_mode', 'builder');

    // Invalidação de cache OBRIGATÓRIA
    delete_post_meta($post_id, '_elementor_css');
    if (did_action('elementor/loaded')) {
        \Elementor\Plugin::$instance->files_manager->clear_cache();
    }

    return rest_ensure_response([
        'status'  => 'success',
        'post_id' => $post_id
    ]);
}

Autenticação

# Via Application Passwords (WordPress 5.6+)
curl -X POST https://site.pt/wp-json/agencia-ai/v1/atualizar-layout \
  -H "Authorization: Basic $(echo -n 'user:app-password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"post_id": 2607, "elementor_json": [...]}'

Avaliação do Método

Critério	Análise
Complexidade	Média — endpoint PHP + formatar JSON _elementor_data válido
Segurança	Alta — usa permissões WordPress + HTTPS
Usar quando	Webhooks, n8n/Make, geração de páginas a partir de CRM

---

4. PHP Hooks — Dynamic Tags

Para conteúdo que se actualiza em runtime sem reescrever JSON.

Registar Dynamic Tag

<?php
// Herdeiro da classe base de Dynamic Tags
class IA_Agente_Metrica_Tag extends \Elementor\Core\DynamicTags\Tag {

    public function get_name()       { return 'tag-agente-ia'; }
    public function get_title()      { return 'Relatório Dinâmico IA'; }
    public function get_group()      { return 'text'; }
    public function get_categories() { return [\Elementor\Modules\DynamicTags\Module::TEXT_CATEGORY]; }

    // Render lê do Transients API — o agente IA popula externamente
    public function render() {
        $dados = get_transient('ia_agente_ultima_metrica');
        echo $dados ? wp_kses_post($dados) : 'A aguardar sincronização...';
    }
}

// Registar
add_action('elementor/dynamic_tags/register', function($manager) {
    $manager->register(new IA_Agente_Metrica_Tag());
});

Padrão: Agente IA actualiza Transient

// Agente IA executa isto remotamente (via eval-file ou endpoint)
set_transient('ia_agente_ultima_metrica', '<p>Taxa de conversão: 4.2%</p>', DAY_IN_SECONDS);

Avaliação do Método

Critério	Análise
Complexidade	Alta — OOP PHP, Event Loop WordPress, DynamicTags
Segurança	Muito Alta — lógica server-side, CI/CD, sem exposição JSON
Usar quando	Conteúdo em tempo real (cotações, stock, métricas) — requer Elementor Pro

---

5. Site Kits — Estrutura e Geração

Estrutura ZIP de um Kit

kit.zip
├── manifest.json          # Índice mestre — mapeamento de todos os ficheiros
├── site-settings.json     # Cores globais, tipografia, configurações do tema
├── header-template.json   # Template de cabeçalho
├── footer-template.json   # Template de rodapé
└── page-template.json     # Templates de páginas

manifest.json (estrutura mínima)

{
  "templates": [
    {
      "title": "Header Principal",
      "type": "header",
      "fileName": "header-template.json"
    }
  ],
  "site_settings": {
    "title": "Site Settings",
    "fileName": "site-settings.json"
  }
}

Geração em Python

import json, zipfile, os

kit_settings = {
    "version": "0.4",
    "title": "Site Settings",
    "settings": {
        "system_colors": [
            {"_id": "primary", "title": "Primária", "color": "#1E40AF"},
            {"_id": "secondary", "title": "Secundária", "color": "#10B981"}
        ],
        "system_typography": [
            {"_id": "primary", "title": "Principal", "typography_font_family": "Inter"}
        ]
    }
}

manifest = {
    "templates": [],
    "site_settings": {"title": "Site Settings", "fileName": "site-settings.json"}
}

os.makedirs('/tmp/kit_build', exist_ok=True)

with open('/tmp/kit_build/site-settings.json', 'w') as f:
    json.dump(kit_settings, f)

with open('/tmp/kit_build/manifest.json', 'w') as f:
    json.dump(manifest, f)

with zipfile.ZipFile('/tmp/agencia-kit.zip', 'w') as z:
    z.write('/tmp/kit_build/manifest.json', 'manifest.json')
    z.write('/tmp/kit_build/site-settings.json', 'site-settings.json')

# Importar via WP-CLI (CWP)
# /opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp elementor kit import /tmp/agencia-kit.zip \
#   --include=site-settings,templates --overrideConditions=all \
#   --allow-root --path=/home/USER/public_html

---

6. CSS — Invalidação de Cache

Localização dos Ficheiros CSS

wp-content/uploads/elementor/css/post-{ID}.css   # CSS por página
wp-content/uploads/elementor/css/global.css       # CSS global

Invalidação Programática (PHP)

// Após qualquer alteração directa a _elementor_data ou post_meta
if (did_action('elementor/loaded')) {
    \Elementor\Plugin::$instance->files_manager->clear_cache();
}

// Alternativa: apagar meta específica
delete_post_meta($post_id, '_elementor_css');

Rebranding Global — Kit Activo

// Obter ID do kit activo
$kit_id = get_option('elementor_active_kit');

// Ler configurações globais
$settings = get_post_meta($kit_id, '_elementor_page_settings', true);

// Alterar cor primária
if (!empty($settings['system_colors'])) {
    foreach ($settings['system_colors'] as &$cor) {
        if ($cor['_id'] === 'primary') {
            $cor['color'] = '#FF0000';
        }
    }
}

// Guardar (wp_slash protege o JSON)
update_post_meta($kit_id, '_elementor_page_settings', $settings);

// Invalidar cache CSS
if (did_action('elementor/loaded')) {
    \Elementor\Plugin::$instance->files_manager->clear_cache();
}

---

7. Regras Críticas e Riscos

Nunca fazer

Erro	Consequência	Correcto
wp search-replace em _elementor_data	Corrupção silenciosa do JSON, layout desaparece	wp elementor replace-urls
UPDATE MySQL sem flush-css	CSS desactualizado, design dessincronizado	Sempre wp elementor flush-css --regenerate
update_post_meta sem wp_slash()	Corrupção de escapes no JSON	wp_slash(json_encode($data))
Múltiplos agentes a editar o mesmo post	Sobreposição de dados	Locks ou filas de processamento

IDs de Widgets São Aleatórios

Os IDs de nós JSON (ex: "id":"3130e2cf") são alfanuméricos aleatórios. Para manipular um widget específico via MySQL ou REST API:

1. Fazer parsing da árvore JSON completa primeiro
2. Encontrar o widget pelo widgetType ou conteúdo
3. Só então operar no ID correcto

Limitações Elementor Free vs Pro

Funcionalidade	Free	Pro
wp elementor flush-css	✅	✅
wp elementor kit import	✅	✅
Dynamic Tags	❌	✅
Theme Builder (header/footer)	❌	✅

---

8. MCP Elementor (Integração Futura)

O projecto Ultimate Elementor MCP expõe ~60 ferramentas para manipulação via linguagem natural:

• create_container, create_heading, delete_element
• get_page_structure — lê árvore JSON (resolve problema dos IDs aleatórios)
• update_widget_settings

Autenticação: Application Passwords ou JWT (mesma arquitectura do REST API).

Quando usar: Assistentes conversacionais, automações complexas onde formatar JSON raw em Python seria impraticável.

Referência: Ultimate Elementor MCP — LobeHub

---

Automação Elementor | Descomplicar® | Baseado em: Manipulação Programática do Elementor — Automação via IA | 18-02-2026