Clase de correo electrónico

La sólida clase de correo electrónico de Higgs admite las siguientes características:

  • Múltiples protocolos: correo, sendmail y SMTP

  • Cifrado TLS y SSL para SMTP

  • Múltiples destinatarios

  • CC y BCC

  • Correo electrónico HTML o texto sin formato

  • Archivos adjuntos

  • Ajuste de palabras

  • Prioridades

  • Modo por lotes BCC, que permite dividir listas de correo electrónico grandes en pequeñas

    Lotes BCC.

  • Herramientas de depuración de correo electrónico

Usando la biblioteca de correo electrónico

Envío de correo electrónico

Enviar correo electrónico no sólo es sencillo, sino que también puedes configurarlo sobre la marcha o establezca sus preferencias en el archivo app/Config/Email.php.

A continuación se muestra un ejemplo básico que demuestra cómo se puede enviar un correo electrónico:

<?php

$email = \Config\Services::email();

$email->setFrom('your@example.com', 'Your Name');
$email->setTo('someone@example.com');
$email->setCC('another@another-example.com');
$email->setBCC('them@their-example.com');

$email->setSubject('Email Test');
$email->setMessage('Testing the email class.');

$email->send();

Configuración de preferencias de correo electrónico

Hay 21 preferencias diferentes disponibles para personalizar la forma en que su correo electrónico se envían mensajes. Puede configurarlos manualmente como se describe aquí, o automáticamente a través de las preferencias almacenadas en su archivo de configuración, descritas en Preferencias de correo electrónico.

Configuración de preferencias de correo electrónico pasando una matriz

Las preferencias se establecen pasando una serie de valores de preferencia al método de inicialización de correo electrónico. A continuación se muestra un ejemplo de cómo podría configurar algunos preferencias:

<?php

$config['protocol'] = 'sendmail';
$config['mailPath'] = '/usr/sbin/sendmail';
$config['charset']  = 'iso-8859-1';
$config['wordWrap'] = true;

$email->initialize($config);

Nota

Most of the preferences have default values that will be used si no los configura.

Configuración de preferencias de correo electrónico en un archivo de configuración

Si prefiere no establecer preferencias utilizando el método anterior, puede en su lugar, colóquelos en el archivo de configuración. Simplemente abre el app/Config/Email.php y establezca sus configuraciones en el Propiedades del correo electrónico. Luego guarde el archivo y se utilizará automáticamente. NO necesitarás usar el método $email->initialize() si usted establece sus preferencias en el archivo de configuración.

SSL versus TLS para protocolo SMTP

Para proteger el nombre de usuario, la contraseña y el contenido del correo electrónico mientras se comunica con el servidor SMTP, Se debe utilizar cifrado en el canal. Se utilizan ampliamente dos estándares diferentes y Es importante comprender las diferencias al intentar solucionar problemas de envío de correo electrónico. asuntos.

La mayoría de los servidores SMTP permiten conexiones en los puertos 465 o 587 al enviar correos electrónicos. (El El puerto original 25 rara vez se usa debido a que muchos ISP tienen reglas de bloqueo implementadas y ya que la comunicación está enteramente en texto claro).

La diferencia clave es que el puerto 465 espera que el canal de comunicación esté protegido mediante TLS. desde el principio según RFC 8314<https://tools.ietf.org/html/rfc8314> _. Una conexión al puerto 587 permite la conexión de texto sin cifrar y posteriores actualizará el canal para usar cifrado usando el comando SMTP STARTTLS.

La actualización de una conexión en el puerto 465 puede ser compatible o no con el servidor, por lo que el El comando SMTP STARTTLS puede fallar si el servidor no lo permite. Si configura el puerto en 465, debería intentar configurar SMTPCrypto en una cadena vacía ('') ya que la comunicación es asegurado usando TLS desde el principio y el STARTTLS no es necesario.

Si su configuración requiere que se conecte al puerto 587, lo más probable es que deba configurar SMTPCrypto a tls ya que esto implementará el comando STARTTLS mientras se comunica con el servidor SMTP para cambiar de texto sin cifrar a un canal cifrado. La comunicación inicial se realizará en texto claro y el canal se actualizará a TLS con el comando STARTTLS.

Revisar preferencias

La configuración utilizada para el último envío exitoso está disponible en el propiedad de instancia $archivo. Esto es útil para probar y depurar. para determinar los valores reales en el momento de la llamada send().

Preferencias de correo electrónico

La siguiente es una lista de todas las preferencias que se pueden configurar cuando enviando correo electrónico.

Anular el ajuste de palabras

Si tiene habilitado el ajuste de palabras (recomendado para cumplir con RFC 822) y tienes un enlace muy largo en tu correo electrónico que también puede incluirse, haciendo que la persona que lo recibe no pueda hacer clic en él. Higgs le permite anular manualmente el ajuste de palabras dentro de parte de su mensaje como este:

El texto de su correo electrónico que
se envuelve normalmente.

{desenvolver}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}

Más texto que será
Envuelto normalmente.

Coloque el elemento entre el que no desea ajustar palabras: {unwrap} {/unwrap}

Referencia de clase

class Higgs\Email\Email
setFrom($from[, $name = ''[, $returnPath = null]])
Parámetros:

  • $from (string) – dirección de correo electrónico «De»

  • $nombre (string) – nombre para mostrar «De»

  • $returnPath (string) – Dirección de correo electrónico opcional para redirigir el correo electrónico no entregado

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece la dirección de correo electrónico y el nombre de la persona que envía el correo electrónico:

<?php

$email->setFrom('you@example.com', 'Your Name');

También puede establecer una ruta de retorno para ayudar a redirigir el correo no entregado:

<?php

$email->setFrom('you@example.com', 'Your Name', 'returned_emails@example.com');

Nota

Return-Path can’t be used if you’ve configured “smtp” as su protocolo.

setReplyTo($replyto[, $name = ''])
Parámetros:

  • $replyto (string) – dirección de correo electrónico para respuestas

  • $nombre (string) – nombre para mostrar de la dirección de correo electrónico de respuesta

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece la dirección de respuesta. Si no se proporciona la información, Se utiliza la información del método setFrom. Ejemplo:

<?php

$email->setReplyTo('you@example.com', 'Your Name');
setTo($to)
Parámetros:

  • $to (mixed) – cadena delimitada por comas o una matriz de direcciones de correo electrónico

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece las direcciones de correo electrónico de los destinatarios. Puede ser un solo correo electrónico, una lista delimitada por comas o una matriz:

<?php

$email->setTo('someone@example.com');

<?php

$email->setTo('one@example.com, two@example.com, three@example.com');

<?php

$email->setTo(['one@example.com', 'two@example.com', 'three@example.com']);
setCC($cc)
Parámetros:

  • $cc (mixed) – cadena delimitada por comas o una matriz de direcciones de correo electrónico

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece las direcciones de correo electrónico CC. Al igual que el «para», puede ser un solo correo electrónico, una lista delimitada por comas o una matriz.

setBCC($bcc[, $limit = ''])
Parámetros:

  • $bcc (mixed) – cadena delimitada por comas o una matriz de direcciones de correo electrónico

  • $limit (int) – Número máximo de correos electrónicos para enviar por lote

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece las direcciones de correo electrónico CCO. Al igual que el método setTo(), puede ser un único correo electrónico, una lista delimitada por comas o una matriz.

Si se establece $limit, se habilitará el «modo por lotes», que enviará los correos electrónicos en lotes, y cada lote no exceda el especificado $límite.

setSubject($subject)
Parámetros:

  • $asunto (string) – línea de asunto del correo electrónico

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece el asunto del correo electrónico:

<?php

$email->setSubject('This is my subject');
setMessage($body)
Parámetros:

  • $body (string) – cuerpo del mensaje de correo electrónico

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece el cuerpo del mensaje de correo electrónico:

<?php

$email->setMessage('This is my message');
setAltMessage($str)
Parámetros:

  • $str (string) – cuerpo del mensaje de correo electrónico alternativo

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Establece el cuerpo del mensaje de correo electrónico alternativo:

<?php

$email->setAltMessage('This is the alternative message');

Esta es una cadena de mensaje opcional que se puede utilizar si envía Correo electrónico con formato HTML. Te permite especificar un mensaje alternativo. sin formato HTML que se agrega a la cadena de encabezado para personas que no aceptan correo electrónico HTML. Si no estableces el tuyo mensaje Higgs extraerá el mensaje de su correo electrónico HTML y quitar las etiquetas.

setHeader($header, $value)
Parámetros:

  • $encabezado (string) – nombre del encabezado

  • $valor (string) – valor del encabezado

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Agrega encabezados adicionales al correo electrónico:

<?php

$email->setHeader('Header1', 'Value1');
$email->setHeader('Header2', 'Value2');
clear($clearAttachments = false)
Parámetros:

  • $clearAttachments (bool) – si se borran o no los archivos adjuntos

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Inicializa todas las variables de correo electrónico a un estado vacío. Este método está diseñado para usarse si ejecuta el método de envío de correo electrónico en un bucle, permitiendo que los datos se restablezcan entre ciclos.

<?php

foreach ($list as $name => $address) {
    $email->clear();

    $email->setTo($address);
    $email->setFrom('your@example.com');
    $email->setSubject('Here is your info ' . $name);
    $email->setMessage('Hi ' . $name . ' Here is the info you requested.');
    $email->send();
}

Si establece el parámetro en verdadero, todos los archivos adjuntos se borrarán como Bueno:

<?php

$email->clear(true);
send($autoClear = true)
Parámetros:

  • $autoClear (bool) – si se borran los datos del mensaje automáticamente

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

El método de envío de correo electrónico. Devuelve un valor booleano verdadero o falso según éxito o fracaso, lo que permite su uso condicional:

<?php

if (! $email->send()) {
    // Generate error
}

Este método borrará automáticamente todos los parámetros si la solicitud fue exitoso. Para detener este comportamiento, pase falso:

<?php

if ($email->send(false)) {
    // Parameters won't be cleared
}

Nota

In order to use the printDebugger() method, you need para evitar borrar los parámetros del correo electrónico.

Nota

If BCCBatchMode is enabled, and there are more than destinatarios BCCBatchSize, este método siempre devolverá booleano true.

attach($filename[, $disposition = ''[, $newname = null[, $mime = '']]])
Parámetros:

  • archivo (string $nombre de) – nombre de archivo

  • $disposición (cadena) – “disposición” del archivo adjunto. Mayoría Los clientes de correo electrónico toman su propia decisión independientemente del MIME. especificación utilizada aquí. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml

  • $newname (string) – nombre de archivo personalizado para usar en el correo electrónico

  • $mime (string) – tipo MIME a usar (útil para datos almacenados en buffer)

Devuelve:

Higgs\Email\Email instancia (encadenamiento de métodos)

Tipo del valor devuelto:

Higgs\Correo electrónico\Correo electrónico

Le permite enviar un archivo adjunto. Coloque la ruta/nombre del archivo en el primero parámetro. Para varios archivos adjuntos, utilice el método varias veces. Por ejemplo:

<?php

$email->attach('/path/to/photo1.jpg');
$email->attach('/path/to/photo2.jpg');
$email->attach('/path/to/photo3.jpg');

Para utilizar la disposición predeterminada (adjunto), deje el segundo parámetro en blanco, de lo contrario, utilice una disposición personalizada:

<?php

$email->attach('image.jpg', 'inline');

También puedes usar una URL:

<?php

$email->attach('http://example.com/filename.pdf');

Si desea utilizar un nombre de archivo personalizado, puede utilizar el tercer parámetro:

<?php

$email->attach('filename.pdf', 'attachment', 'report.pdf');

Si necesita utilizar una cadena de búfer en lugar de un archivo físico real, puede use el primer parámetro como búfer, el tercer parámetro como nombre de archivo y el cuarto parámetro como tipo mime:

<?php

$email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');
setAttachmentCID($filename)
Parámetros:

  • $filename (string) – nombre de archivo adjunto existente

Devuelve:

ID de contenido del archivo adjunto o falso si no se encuentra

Tipo del valor devuelto:

cadena

Establece y devuelve el ID de contenido de un archivo adjunto, lo que le permite insertar un archivo en línea (imagen) adjunto en HTML. El primer parámetro debe ser el nombre del archivo ya adjunto.

<?php

$filename = '/img/photo1.jpg';
$email->attach($filename);

foreach ($list as $address) {
    $email->setTo($address);
    $cid = $email->setAttachmentCID($filename);
    $email->setMessage('<img src="cid:' . $cid . '" alt="photo1">');
    $email->send();
}

Nota

Content-ID for each e-mail must be re-created for it to be unique.

printDebugger($include = ['headers', 'subject', 'body'])
Parámetros:

  • $include (array) – qué partes del mensaje imprimir

Devuelve:

datos de depuración formateados

Tipo del valor devuelto:

cadena

Devuelve una cadena que contiene los mensajes del servidor, los encabezados de correo electrónico y el mensaje de correo electrónico. Útil para depurar.

Opcionalmente, puede especificar qué partes del mensaje deben imprimirse. Las opciones válidas son: encabezados, asunto, cuerpo.

Ejemplo:

<?php

// You need to pass false while sending in order for the email data
// to not be cleared - if that happens, printDebugger() would have
// nothing to output.
$email->send(false);

// Will only print the email headers, excluding the message subject and body
$email->printDebugger(['headers']);

Nota

By default, all of the raw data will be printed.