Applicazione per l'invio delle email con la libreria PHPMailer

PHPMailer gestisce l'invio di email in formato html e con autenticazione smtp.
Il sito ufficiale della libreria PHPMailer è http://phpmailer.worxware.com/.

INSTALLAZIONE

1. Scaricare la libreria dal repository github https://github.com/Synchro/PHPMailer
2. Decomprimere il file del progetto nella directory lib di gino e rinominare la directory PHPMailer, ad esempio:

   # mv PHPMailer_master PHPMailer

Il file PHPMailer/class.phpmailer.php deve essere caricato una sola volta nello script (poi si potranno inviare infinite email).

UTILIZZO

1. Includere nel metodo che si occupa dell'invio delle email il file plugin.phpmailer.php

   require_once(PLUGIN_DIR.OS.'plugin.phpmailer.php');

2. Utilizzare il metodo sendMail() per inviare le email; questo metodo si interfaccia alla libreria PHPMailer.
   La scelta dell'utilizzo della libreria PHPMailer o della funzione base di php (mail) per l'invio di una email avviene tramite l'opzione php_mail:
   • php_mail true, funzione mail (default)
   • php_mail false, libreria PHPMailer

Optando per la libreria PHPMailer è inoltre possibile scegliere la tipologia di mailer; di default il valore è mail.

ESEMPIO

Esempio di metodo per l'invio di una email con la tipologia di mailer smtp

public function testEmail(){
  require_once(PLUGIN_DIR.OS.'plugin.phpmailer.php');
  $mailer = new \Gino\Plugin\plugin_phpmailer();
  $send = $mailer->sendMail("support@test.com", "info@test.com", "Prova invio da plugin", "Testo dell'email", 
  array(
    'php_mail'=>false, 
    'mailer'=>'smtp', 
    'debug'=>2, 
    'reply_email'=>'reply@test.com', 
    'reply_name'=>'Test Email', 
    'ishtml'=>false, 
    'smtp_server'=>'smtp.example.com', 
    'smtp_auth'=>true, 
    'smtp_user'=>"smtp@test.com", 
    'smtp_password'=>"password"
  ));
  
  return $send;
}

CONTENUTO DELL'EMAIL

Una email può essere in formato html o testo. Per definire il tipo di formato impostare l'opzione ishtml nel metodo sendMail()

array(
  ...
  'ishtml'=>[true|false], 
)

ALLEGATI

Per allegare dei file all'email utilizzare l'opzione attachments nel metodo sendMail(). Ogni file viene definito come un array con le chiavi path e name

array(
  ...
  'attachments'=>array(
    array(
      'path'=>CONTENT_DIR.OS.'attachment'.OS.'prova1.pdf', 
      'name'=>'pippo.pdf'
    ), 
    array(
      'path'=>CONTENT_DIR.OS.'attachment'.OS.'prova2.pdf', 
      'name'=>'pluto.pdf'
    )
  ), 
)

FORMATO HTML

Utilizzando il formato html è possibile formattare il corpo dell'email con i tag html. Il contenuto può essere definito nel codice all'interno di una variabile oppure in una specifica vista.
Nel primo caso avremo ad esempio

$contents = "
<table align=\"center\" width=\"600\" border=\"0\" bgcolor=\"FFFFFF\">
  <tr>
    <td><div style=\"text-align:left; padding:8px 4px; background-color:#F2F2F2; font-size:10px;\">Testo dell'email</div></td>
  </tr>
</table>";

Nel caso della vista il contenuto viene definito nella classe controller attraverso la classe Gino.View; prendendo come riferimento per la costruzione delle email html il template mailing.php (presente nel progetto) abbiamo ad esempio:

$view = new \Gino\View($this->_view_dir);
$view->setViewTpl('mailing');

$root_absolute_url = $this->_registry->request->root_absolute_url;
$dict = array(
  'image' => $root_absolute_url.'app/blog/img/image.gif',
  'title' => _("Mailing"), 
  'subtitle' => null, 
  'items' => $items,
);
$contents = $view->render($dict);

CREARE UN MESSAGGIO DA UNA STRINGA HTML

Per creare un messaggio in modo automatico a partire da una stringa html occorre attivare l'opzione automatic_html nel metodo sendMail()

array(
  ...
  'automatic_html'=>true, 
)

Con questa opzione si richiama PHPMailer::MsgHTML() che effettua in modo automatico le modifiche per le immagini inline e i background, e crea una versione di solo testo convertendo il codice html. PHPMailer::MsgHTML() sovrascrive qualsiasi valore esistente in PHPMailer::$Body e PHPMailer::$AltBody.
Il contenuto dell'email è quello passato nel parametro $contents di sendMail(), come ad esempio

$contents = file_get_contents('contents.html');

IMMAGINI INLINE

Se si vuole costruire una email con delle immagini incorporate nel testo è necessario allegare le immagini e collegarle con il tag

<img src="cid:CID" />

dove CID è il content ID dell'allegato, ovvero il riferimento dell'immagine.
Le immagini devono essere allegate con l'opzione embedded_images nel metodo sendMail(). Ogni file viene definito come un array con le chiavi path, cid e name

array(
  ...
  'embedded_images'=>array(
    array(
      'path'=>SITE_ROOT.OS.'app/blog/img/image.gif', 
      'cid'=>'img1'
    )
  ), 
)

NOTE SULLA COSTRUZIONE DELLE EMAIL IN FORMATO HTML

1. Usare CSS inline per il testo e i link (ovvero senza servirsi di file css esterni o caricati sul server): inserire gli stili CSS direttamente nel corpo dell'email. Outlook non riconosce gli sfondi nelle tabelle perciò usate solo tinte unite tramite l’attributo bgcolor dei CSS.
   
2. Usare solo Tabelle e non elementi DIV. Purtroppo Microsoft scansa accuratamente i DIV e le E-mail vanno costruite con le Tabelle.
   
3. Usare inline anche gli attributi di stile delle tabelle, ovvero direttamente nel TAG TABLE (p.e. <TR style="...">).
   
4. Usare le immagini jpeg (scordarsi la trasparenza dei png)

ECCEZIONI

Per attivare le eccezioni impostare l'opzione exception nel metodo sendMail()

array(
  ...
  'exception'=>true, 
)

Esempio di eccezioni

$mail = new PHPMailer(true);
$mail->IsSMTP();
try {
  $mail->Host       = "mail.yourdomain.com";
  $mail->SMTPDebug  = 2;
  ...
  $mail->Send();
  echo "Message Sent OK<p></p>\n";
} catch (phpmailerException $e) {
  echo $e->errorMessage(); //Pretty error messages from PHPMailer
} catch (Exception $e) {
  echo $e->getMessage(); //Boring error messages from anything else!
}