24 de junio de 2025

Enviar emails con adjunto utilizando PHP

La solución moderna y recomendada es utilizar una librería dedicada para comunicarse con un servidor SMTP. En este White Paper nos centraremos en la solución más popular y robusta de la industria: PHPMailer. Aprenderás a instalarla y a usarla de forma correcta y segura para enviar correos con archivos adjuntos.

Envío de emails utilizando PHP Mailer

Paso 1: Instalación con Composer

La forma moderna de gestionar dependencias en PHP es a través de Composer. Si aún no lo tienes instalado, puedes descargarlo desde su web oficial (https://getcomposer.org/). Una vez instalado, abre un terminal en la raíz de tu proyecto y ejecuta el siguiente comando para añadir PHPMailer:

composer require phpmailer/phpmailer

Este comando creará una carpeta vendor en tu proyecto, que contendrá la librería de PHPMailer y un fichero autoload.php para cargarla automáticamente.

Paso 2: Código de ejemplo completo

Una vez instalada la librería, el siguiente código muestra cómo configurar y enviar un email con un archivo adjunto. Asegúrate de que el fichero vendor/autoload.php es accesible desde tu script.

<?php
// Importar las clases de PHPMailer al namespace global
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;
use PHPMailer\PHPMailer\SMTP;

// Cargar el autoloader de Composer
require 'vendor/autoload.php';

// Crear una instancia; pasar `true` habilita las excepciones
$mail = new PHPMailer(true);

try {
    // ---- CONFIGURACIÓN DEL SERVIDOR ----
    // Habilitar salida de depuración detallada (desactivar en producción)
    // $mail->SMTPDebug = SMTP::DEBUG_SERVER;                     
    $mail->isSMTP();
    $mail->Host       = 'smtp.ejemplo.com'; // Servidor SMTP (ej: smtp.hostalia.com)
    $mail->SMTPAuth   = true;
    $mail->Username   = 'origen@ejemplo.com'; // Tu usuario SMTP
    $mail->Password   = 'P4ssw0rd'; // Tu contraseña SMTP
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS; // Habilitar encriptación TLS
    $mail->Port       = 587; // Puerto TCP (587 para TLS, 465 para SSL)

    // ---- REMITENTE Y DESTINATARIOS ----
    $mail->setFrom('info@hostalia.com', 'Hostalia');
    $mail->addAddress('micorreo@midominio.com', 'Nombre Destinatario'); // Añadir destinatario

    // ---- ADJUNTOS ----
    $mail->addAttachment('ficheros/fichero_adjunto.zip'); // Añadir un adjunto
    // $mail->addAttachment('ficheros/imagen.jpg', 'nueva_imagen.jpg'); // Opcional: con nombre personalizado

    // ---- CONTENIDO DEL CORREO ----
    $mail->isHTML(true); // Establecer el formato del email a HTML
    $mail->Subject = 'Envío de correo utilizando PHPMailer';
    $mail->Body    = 'Este es el cuerpo del mensaje en <b>formato HTML</b>. Aquí iría el texto.';
    $mail->AltBody = 'Este es el cuerpo en texto plano para clientes de correo que no soportan HTML.';
    
    $mail->CharSet = 'UTF-8'; // Asegurar la codificación correcta para tildes y caracteres especiales

    $mail->send();
    echo 'Correo enviado con éxito';

} catch (Exception $e) {
    echo "El mensaje no pudo ser enviado. Error de PHPMailer: {$mail->ErrorInfo}";
}

Paso 3: Explicación del código

• Carga y namespaces: Con Composer, solo necesitas un require ‘vendor/autoload.php’;. Las sentencias use al principio nos permiten usar las clases PHPMailer, Exception y SMTP sin tener que escribir su ruta completa cada vez.

• Instanciación y manejo de errores: Al crear el objeto con new PHPMailer(true);, activamos el modo de excepciones. Esto nos permite envolver todo el proceso en un bloque try…catch para capturar cualquier error de forma limpia y profesional, en lugar de que el script se detenga bruscamente.

• Configuración del servidor SMTP: Aquí se definen los datos de tu servidor de correo. Host, Username, y Password son las credenciales de tu cuenta de email. SMTPSecure y Port son cruciales para establecer una conexión segura.

¡Importante! Nunca almacenes contraseñas directamente en el código (conocido como «hardcoding»). En una aplicación real, estas credenciales deben cargarse desde variables de entorno (usando librerías como vlucas/phpdotenv) o desde un fichero de configuración seguro fuera del control de versiones (Git).

• Remitente y destinatarios: Con setFrom() defines quién envía el correo y con addAddress() a quién va dirigido. Puedes llamar a addAddress() varias veces para enviar a múltiples destinatarios. También existen métodos como addCC() y addBCC().

• Adjuntar archivos: El método addAttachment() es muy sencillo. Solo necesitas pasarle la ruta al archivo que quieres adjuntar. PHPMailer se encargará automáticamente de determinar el tipo de archivo (MIME type).

• Contenido del correo: isHTML(true) le dice a PHPMailer que el cuerpo principal está en HTML. Es una buena práctica proporcionar siempre un AltBody con el contenido en texto plano para clientes de correo antiguos o que no soportan HTML.

• Envío y gestión de errores: $mail->send() intenta realizar el envío. Si tiene éxito, el código continúa. Si falla por cualquier motivo (credenciales incorrectas, servidor no disponible, etc.), se lanza una excepción que es capturada por el bloque catch, mostrando un mensaje de error detallado a través de $mail->ErrorInfo.

Como hemos visto, que no podamos o no debamos utilizar la función mail() de PHP no es un impedimento para enviar correos electrónicos de forma profesional. La clave está en adoptar las herramientas estándar de la industria:

1. Usar Composer para gestionar las dependencias de nuestro proyecto.

2. Apoyarse en librerías robustas y seguras como PHPMailer.

Comentarios