ML Mailing Lists

Plugin de WordPress para xestionar listas de correo e subscricións con funcionalidades avanzadas de envío masivo e exportación.

📋 Características

• ✅ Xestión de listas de correo mediante taxonomías personalizadas
• ✅ Shortcode de subscrición personalizable e responsive
• ✅ Envío masivo de correos con editor WYSIWYG
• ✅ Variables de personalización nos emails
• ✅ Exportación de datos en CSV e TXT
• ✅ Sistema anti-spam con honeypot e rate limiting
• ✅ Interface en galego tanto para frontend como backend
• ✅ Vista previa antes do envío masivo
• ✅ Logging de actividade de envíos
• ✅ Seguridade reforzada con nonces e validacións

🚀 Instalación

1. Descarga o plugin
2. Sube a carpeta ml-mailing-lists ao directorio /wp-content/plugins/
3. Activa o plugin desde o panel de administración de WordPress
4. Configura as listas de correo en ML Mailing Lists > ML Lista

📖 Uso do Shortcode

Sintaxe básica

[ml_subscription_form list_id="123"]

Sintaxe completa con todos os parámetros

[ml_subscription_form
    list_id="123"
    title="Subscríbete á nosa newsletter"
    btn_text="Subscribirse agora"
    css_class="ml-subscription-form"
]

Parámetros dispoñibles

Parámetro	Descrición	Valor por defecto
list_id	Obrigatorio. ID da lista de correo	-
title	Título que aparece no formulario	"Subscríbete á nosa lista"
btn_text	Texto do botón de envío	"Subscribirse"
css_class	Clase CSS personalizada	"ml-subscription-form"

Exemplos de uso

Formulario básico:

[ml_subscription_form list_id="1"]

Formulario personalizado:

[ml_subscription_form
    list_id="2"
    title="Únete á nosa comunidade"
    btn_text="Subscríbeme xa!"
    css_class="mi-formulario-personalizado"
]

📧 Envío Masivo de Correos

Acceso á funcionalidade

1. Ve a ML Mailing Lists > Enviar Correo
2. Selecciona a lista de destinatarios
3. Configura os datos do remitente
4. Escribe o asunto e contido
5. Opcionalmente, envía unha vista previa
6. Confirma o envío masivo

Variables de personalización

O plugin soporta as seguintes variables no contido dos emails:

Variable	Descrición
{{nome}}	Nome do subscritor
{{apelido}}	Apelido do subscritor
{{correo}}	Correo electrónico do subscritor

Exemplo de email personalizado

<h2>Ola {{nome}}!</h2>
<p>Grazas por subscribirte á nosa lista con o correo {{correo}}.</p>
<p>Saúdos,<br>
O equipo de {{nome}} {{apelido}}</p>

📊 Exportación de Datos

Formatos dispoñibles

• CSV: Formato compatible con Excel e follas de cálculo
• TXT: Formato de texto plano lexible

Como exportar

1. Ve a ML Mailing Lists (listado principal)
2. Opcionalmente, filtra por unha lista específica
3. Fai clic en 📊 Exportar CSV ou 📄 Exportar TXT
4. O arquivo descargarase automaticamente

Datos incluídos na exportación

• Nome
• Apelido
• Correo electrónico
• Data de subscrición
• Listas ás que pertence

🔧 Configuración Avanzada

Personalización do CSS

O plugin inclúe CSS por defecto, pero podes personalizalo usando as variables CSS:

:root {
    --ml-primary-color: #a-túa-cor-principal;
    --ml-secondary-color: #a-túa-cor-secundaria;
    --ml-background-color: #cor-de-fondo;
    --ml-border-color: #cor-de-borde;
}

Hooks e filtros dispoñibles

Filtros de personalización:

// Personalizar datos antes de gardar a subscrición
add_filter( 'ml_subscription_name', 'mi_filtro_nome', 10, 2 );
add_filter( 'ml_subscription_surname', 'mi_filtro_apelido', 10, 2 );
add_filter( 'ml_subscription_email', 'mi_filtro_email', 10, 2 );

Accións de eventos:

// Executar código despois de crear unha subscrición
add_action( 'ml_subscription_created', 'mi_funcion_post_subscripcion', 10, 3 );

// Activación/desactivación do plugin
add_action( 'ml_plugin_activated', 'mi_funcion_activacion' );
add_action( 'ml_plugin_deactivated', 'mi_funcion_desactivacion' );

Hooks de inicialización:

// Despois da inicialización das clases
add_action( 'ml_core_initialized', 'mi_funcion_inicializacion' );

// Antes de procesar un formulario
add_action( 'ml_before_form_processing', 'mi_funcion_pre_formulario' );

Exemplos de extensión

Engadir validación personalizada:

add_filter( 'ml_subscription_email', function( $email, $list_id ) {
    // Bloquear dominios específicos
    $blocked_domains = ['example.com', 'spam.com'];
    $domain = substr(strrchr($email, '@'), 1);

    if (in_array($domain, $blocked_domains)) {
        return false; // Esto activará unha validación de erro
    }

    return $email;
}, 10, 2 );

Logging personalizado:

add_action( 'ml_subscription_created', function( $post_id, $email, $list_id ) {
    // Enviar notificación por Slack, Discord, etc.
    $list_name = get_term( $list_id, 'ml_lista' )->name;

    error_log( "Nova subscrición en '{$list_name}': {$email}" );

    // Ou enviar webhook
    wp_remote_post( 'https://hooks.slack.com/services/...', [
        'body' => json_encode([
            'text' => "Nova subscrición: {$email} en {$list_name}"
        ])
    ]);
}, 10, 3 );

🛡️ Características de Seguridade

Protección anti-spam

• Honeypot: Campo oculto que detecta bots
• Rate limiting: Máximo 3 intentos por IP por hora
• Nonces: Verificación de tokens de seguridade
• Validación de datos: Sanitización e validación estricta

Permisos de usuario

• Só usuarios con capacidade manage_options poden:
  • Enviar correos masivos
  • Exportar datos
  • Acceder ás funcionalidades de administración

📁 Estrutura de Arquivos con Namespaces

Estrutura modular do plugin

ml-mailing-lists/
├── ml-mailing-lists.php           # Arquivo principal - Cargador do plugin
├── README.md                      # Documentación completa
└── includes/                      # Classes modulares con namespace ML_Mailing_Lists
    ├── class-core.php          # Core - Xestor principal de dependencias
    ├── class-shortcode.php     # Shortcode - Xestión de formularios
    ├── class-security.php      # Security - Sistema de seguridade
    ├── class-admin.php         # Admin - Interface de administración
    ├── class-email-sender.php  # Email_Sender - Xestión de envío
    ├── class-export.php        # Export - Sistema de exportación
    └── functions.php              # Funcións auxiliares con namespace

Estrutura con namespaces

Todas as clases están baixo o namespace ML_Mailing_Lists para evitar conflitos:

namespace ML_Mailing_Lists;

// Inicialización do plugin
\ML_Mailing_Lists\Core::get_instance();

// Acceso ás clases
\ML_Mailing_Lists\Shortcode::get_instance();
\ML_Mailing_Lists\Security::get_instance();
\ML_Mailing_Lists\Admin::get_instance();
\ML_Mailing_Lists\Email_Sender::get_instance();
\ML_Mailing_Lists\Export::get_instance();

Descrición das clases

🔧 ML_Mailing_Lists\Core (class-core.php)

• Función principal: Cargador e inicializador do plugin
• Patrón: Singleton con namespace
• Responsabilidades:
  • Cargar todas as dependencias
  • Inicializar as clases modulares
  • Xestionar hooks de activación/desactivación
  • Cargar traduccións

📝 ML_Mailing_Lists\Shortcode (class-shortcode.php)

• Función principal: Xestión de formularios de subscrición
• Patrón: Singleton con namespace
• Responsabilidades:
  • Rexistrar e procesar shortcodes
  • Xerar HTML dos formularios
  • Procesar envíos de subscrición
  • Aplicar estilos CSS

🛡️ ML_Security (class-security.php)

• Función principal: Sistema de seguridade integral
• Patrón: Singleton con métodos estáticos
• Responsabilidades:
  • Xestión de nonces de seguridade
  • Rate limiting (control de frecuencia)
  • Detección de honeypot anti-spam
  • Validación e sanitización de datos
  • Obtención segura de IP de usuario

⚙️ ML_Admin (class-admin.php)

• Función principal: Interface de administración
• Patrón: Singleton
• Responsabilidades:
  • Páxinas de envío masivo
  • Interface de exportación
  • Xestión de menús de admin
  • Procesamento de formularios de admin

📧 ML_Email_Sender (class-email-sender.php)

• Función principal: Sistema de envío de emails
• Patrón: Singleton
• Responsabilidades:
  • Envío de emails individuais
  • Envío masivo con personalización
  • Xestión de variables de plantilla
  • Estatísticas de envío

📊 ML_Export (class-export.php)

• Función principal: Exportación de datos
• Patrón: Singleton
• Responsabilidades:
  • Exportación en formato CSV
  • Exportación en formato TXT
  • Validación de parámetros
  • Estatísticas de exportación

🔧 Funcións auxiliares (functions.php)

• Función principal: Utilidades globais
• Funcións principais:
  • ml_subscription_exists(): Verificar subscricións existentes
  • ml_get_subscriber_by_email(): Obter datos por email
  • ml_get_list_subscribers(): Obter subscriptores de lista
  • ml_get_list_stats(): Estatísticas das listas
  • ml_log_activity(): Sistema de logging
  • ml_format_date(): Formateo de datas
  • ml_user_can_manage_lists(): Verificación de permisos

�️ Arquitectura Técnica

Patrón de deseño implementado

O plugin segue unha arquitectura modular baseada no patrón Singleton que garante:

• Unha soa instancia de cada clase principal
• Carga eficiente de recursos
• Separación clara de responsabilidades
• Fácil mantemento e extensibilidade

Fluxo de inicialización

WordPress carga → ml-mailing-lists.php → ML_Core::get_instance()
                                           ↓
                                      Carga dependencias
                                           ↓
                    ┌─────────────────────────────────────────┐
                    │          ML_Core::init_plugin()        │
                    └─────────────────────────────────────────┘
                                           ↓
    ┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
    │   ML_Security   │  ML_Shortcode   │  ML_Email_Sender │    ML_Export    │
    │ ::get_instance()│ ::get_instance()│ ::get_instance() │ ::get_instance()│
    └─────────────────┴─────────────────┴─────────────────┴─────────────────┘
                                           ↓
                              ┌─────────────────────────┐
                              │       ML_Admin         │
                              │   ::get_instance()     │
                              │   (só en admin)        │
                              └─────────────────────────┘

Melloras de rendemento

• Lazy loading: As clases cárganse só cando se necesitan
• Singleton pattern: Evita instanciación múltiple
• Conditional loading: ML_Admin só se carga no backend
• Optimización de queries: Uso eficiente de meta_query e tax_query
• CSS estático: Evita duplicación de estilos

�🌐 Idiomas

O plugin está completamente traducido ao galego tanto no frontend como no backend, incluíndo:

• Formularios de subscrición
• Mensaxes de erro e confirmación
• Interface de administración
• Botóns e labels
• Mensaxes do sistema

⚙️ Requisitos Técnicos

• WordPress: 5.0 ou superior
• PHP: 7.4 ou superior
• Pods Plugin: Requerido para a xestión de CPT e taxonomías

🔧 Configuración Inicial

1. Crear listas de correo

1. Ve a Listas de correo > Listas
2. Engade unha nova lista
3. Anota o ID da lista para usar no shortcode

2. Configurar o shortcode

Usa o ID da lista no teu shortcode:

[ml_subscription_form list_id="O_TEU_ID_DE_LISTA"]

3. Configurar o envío de emails

1. Verifica a configuración de email de WordPress
2. Considera usar un plugin de SMTP para mellor entregabilidade
3. Proba o envío coa función de vista previa

📈 Rendemento e Escalabilidade

Optimizacións incluídas

• Delays no envío masivo: Prevén sobrecarga do servidor
• Limitación de consultas: Queries optimizadas
• CSS único: Cárgase só unha vez por páxina
• Logging eficiente: Mantén só os últimos 100 rexistros

Recomendacións para sitios con alto tráfico

• Usa un servizo de email transaccional (SendGrid, Mailgun, etc.)
• Considera a implementación de colas para envíos masivos grandes
• Monitoriza os logs de envío regularmente

🐛 Resolución de Problemas

Problemas comúns

O shortcode non aparece:

• Verifica que o plugin estea activado
• Comproba que o ID da lista sea correcto
• Asegúrate de que a lista existe e está publicada

Os emails non se envían:

• Verifica a configuración de email de WordPress
• Comproba os logs do servidor
• Considera usar un plugin de SMTP

Erro de permisos:

• Só usuarios administradores poden enviar emails masivos
• Verifica os roles e capacidades do usuario

Logs e debugging

Os logs de envío almacénanse na base de datos e poden consultarse desde o código:

$logs = get_option( 'ml_email_logs', array() );

📝 Changelog

Versión 1.0.2 - Namespaces e Modernización Completa

• ✅ Implementación de namespaces ML_Mailing_Lists en todas as clases
• ✅ Arquitectura moderna seguindo PSR-4 con namespace
• ✅ Actualización de clases a nomes sen prefixo (Security, Shortcode, etc.)
• ✅ Referencias actualizadas en todo o código para usar namespaces
• ✅ Documentación actualizada con exemplos de namespace
• ✅ Mellor organizacón evitando conflitos de nomes
• ✅ Compatibilidade mantida con todas as funcionalidades