LIBMAIL

Descrizione

Questa libreria fornisce un approccio orientato agli oggetti per l'invio di e-mail in PHP.

Indice

Licenza

Questo script è distribuito sotto licenza GPL

NON C'E' NESSUNA GARANZIA PER IL PROGRAMMA, PER QUANTO CONSENTITO DALLE VIGENTI NORMATIVE. ECCETTO QUANDO ALTRIMENTI STABILITO PER ISCRITTO, I DETENTORI DEL COPYRIGHT E/O LE ALTRE PARTI FORNISCONO IL PROGRAMMA "COSI' COME È" SENZA GARANZIA DI ALCUN TIPO, NE' ESPRESSA NE' IMPLICITA, INCLUSE, MA NON LIMITATE A, LE GARANZIE DI COMMERCIABILITA' O DI UTILIZZABILITA' PER UN PARTICOLARE SCOPO. L'INTERO RISCHIO CONCERNENTE LA QUALITA' E LE PRESTAZIONI DEL PROGRAMMA E' DEL LICENZIATARIO. SE IL PROGRAMMA DOVESSE RISULTARE DIFETTOSO, IL LICENZIATARIO SI ASSUME I COSTI DI MANUTENZIONE, RIPARAZIONE O CORREZIONE.

Autori

Questo script è un'estensione di libMail scritto originariamente da Leo West

Script originale di Leo West - west_leo@yahoo.com
URL: http://lwest.free.fr/doc/php/lib/Mail/
Ultima modifica : Nov 2001
Versione : 1.3

Modificato da Setec Astronomy - setec@freemail.it
URL : http://digilander.iol.it/setecastronomy/
Ultima modifica : Gen 2004
Versione : 1.4

Modificato da Pier Luigi Pau - eregilofdarkwood@yahoo.com
URL : http://eregil.altervista.org/
Ultima modifica : Gen 2008
Versione : 1.4.2
Versione : 1.5.0

Alcune delle funzionalità di libMail:

ChangeLog - Cambiamenti

versione 1.5.0

Questa versione è rilasciata contemporaneamente alla 1.4.2; mentre la 1.4.2 cerca di essere un perfetto sostituto della 1.4.1 (l'interfaccia della classe non cambia in maniera radicale), questa versione aggiunge delle funzionalità non banali, in particolare il supporto per le e-mail in formato MIME multipart/alternative. Di conseguenza, il modo per inviare e-mail in HTML è cambiato e gli script che utilizzano questa classe a tale scopo dovranno essere modificati.

versione 1.4.2

Questa versione cerca di essere un sostituto perfetto della 1.4.1, ma in ogni caso, si raccomanda caldamente di testarla in maniera approfondita, prima di sostituire il vostro libmail.php su un server di produzione.

versione 1.4.1

versione 1.4

versione 1.3

versione 1.2

versione 1.1

Sinossi

	include "libmail.php";
	$m= new Mail; // crea l'oggetto mail
	$m->From ("leo@isp.com");
	$m->To ("destination@somewhere.fr");
	$m->Subject ("oggetto dell'e-mail");
	$m->Body ("Hello\nThis is a test of the Mail component"); // corpo del messaggio
	$m->Cc ("someone@somewhere.fr");
	$m->Bcc ("someoneelse@somewhere.fr");
	$m->Priority (4) ;	// bassa priorità
	$m->Attach ("/home/leo/toto.gif", "image/gif", "inline") ; // allega un file di tipo image/gif da visualizzare nel messaggio
	$m->Send ();	// invia l'e-mail
	echo "Mail was sent:<br><pre>", $m->Get (), "</pre>";

Installazione

Scarica libmail.zip

Contenuto:

(*) Nota: più versioni di libMail possono essere distributite in un unico archivio. Sebbene più versioni dello script possano essere distribuiti insieme, ciascuna versione deve comunque essere considerata come uno script distinto, che può essere utilizzato, alterato e ridistribuito nel rispetto dei termini della licenza GPL.

Non è necessaria alcuna configurazine particolare nella libreria. In php.ini:

	SMTP           = smtp.isp.com			; for win32 only
	sendmail_from  = valid_address@chezmoi.fr	;for win32 only

Documentazione

Costruttore

Crea un'istanza di Mail.

	$mail = new Mail ();

Subject ([string subject])

Definisce l'oggetto dell'e-mail.

	$mail->Subject ("Hello world!");

From (string from_email, [string from_name])

Definisce il mittente dell'e-mail. Questa chiamata è obbligatoria. È possibile specificare anche il nome.

	$mail->From( "me@isp.com" );
	$mail->From( "me@isp.com", "Me at ISP" );

To (mixed address)

Definisce il destinatario o i destinatari. Questa chiamata è obbligatoria. Il parametro può essere un indirizzo (stringa) o un array di indirizzi. È possibile specificare anche i nomi.

	$mail->To ("you@isp.com");
	$tos = array ("you@isp.com", "u2@isp.com");
	$mail->To ($tos);
	$tos = array ("you@isp.com" => "You at ISP", "u2@isp.com" => "U2 at ISP"); // DEPRECATO A PARTIRE DALLA 1.4.2
	$mail->To ($tos);
	$tos = array ("You at ISP <you@isp.com>", "U2 at ISP <u2@isp.com>");
	$mail->To ($tos);

CC (mixed address)

Definisce uno o più destinatari in Carbon-copy (Copia per Conoscenza). Il parametro può essere un indirizzo (stringa) o un array di indirizzi. È possibile specificare anche i nomi.

	$mail->CC ("you@isp.com");
	$ccs = array ("you@isp.com", "u2@isp.com");
	$mail->CC ($ccs);
	$ccs = array ("you@isp.com" => "You at ISP", "u2@isp.com" => "U2 at ISP"); // DEPRECATO A PARTIRE DALLA 1.4.2
	$mail->CC ($ccs);
	$ccs = array ("You at ISP <you@isp.com>", "U2 at ISP <u2@isp.com>");
	$mail->CC ($ccs);

BCC (mixed address)

Definisce uno o più destinatari in Blind Carbon-copy (Copia per Conoscenza Nascosta). Il parametro può essere un indirizzo (stringa) o un array di indirizzi. È possibile specificare anche i nomi.

	$mail->BCC ("you@isp.com");
	$bccs = array ("you@isp.com", "u2@isp.com");
	$mail->BCC ($bccs);
	$bccs = array ("you@isp.com" => "You at ISP", "u2@isp.com" => "U2 at ISP"); // DEPRECATO A PARTIRE DALLA 1.4.2
	$mail->BCC ($bccs);
	$bccs = array ("You at ISP <you@isp.com>", "U2 at ISP <u2@isp.com>");
	$mail->BCC ($bccs);

Body ([string body], [string charset])

Definisce il corpo del messaggio in formato testo. Il parametro opzionale charset definisce il set di caratteri utilizzato. Il valore di default è "us-ascii". Il set di caratteri deve corrispondere a quello utilizzato nel corpo del messaggio sia in formato testo che in HTML. Solitamente sarà iso-8859-1 se sono presenti caratteri come le lettere accentate.

	$mail->Body ("Message in english");
	$mail->Body ("Message avé dé accents", "iso-8859-1");
Nota: non inviare e-mail in HTML in questo modo. Vedere i Suggerimenti al riguardo.

Text ([string body], [string charset])

Alias di Body(). Disponibile a partire dalla versione 1.5.0

Html ([string html_body], [string charset])

Definisce il corpo del messaggio in formato HTML. Vedere i Suggerimenti per gli esempi.
Il parametro opzionale charset funziona come nel metodo Body(). Notare che viene utilizzato soltanto l'ultimo charset specificato, fra tutte le chiamate a Body(), Text(), Html() e SetCharset() che vengono eseguite; non è possibile utilizzare set di caratteri diversi per testo e HTML.
Il metodo Html() è disponibile a partire dalla versione 1.5.0

SetCharset (string charset)

Definisce il set di caratteri del messaggio. Può essere chiamato esplicitamente, invece di specificare il charset in uno dei metodi sopra descritti. Vedere Body() e Html().
Disponibile a partire dalla versione 1.5.0

	$mail->SetCharset ("iso-8859-1");

Attach( string filepath, [string mimetype], [string disposition], [string filename] )

Allega un file $filepath all'e-mail.

	$mail->Attach ("logo.gif", "image/gif");
	$mail->Attach ("C:\\My Documents\\resume.doc", "application/x-msword", "attachment");
	$mail->Attach ("C:\\My Documents\\resume.doc", "application/x-msword", "attachment", "cv.doc");

AttachString( string content, [string mimetype], [string disposition], [string filename] )

Crea un file che abbia come contenuto la stringa $content e lo allega all'e-mail (il file non sarà memorizzato automaticamente sul disco!). Disponibile a partire dalla versione 1.4.2

	$some_content = "A text file containing this string will be created and attached.\n";
	$mail->AttachString($some_content, "text/plain", "attachment", "some_text.txt");

Organization (string $org)

Definisce il campo header Organization field. Opzionale.

	$mail->Organization ("My company");

ReplyTo (string replyto_email, [string replyto_name])

Definisce un indirizzo "Reply To" (Rispondi a) differente da quello del mittente. È possibile specificare anche un nome.

ReturnPath (string returnpath_email, [string returnpath_name])

Definisce un indirizzo "Return Path" differente da quello del mittente. È possibile specificare anche un nome.

	$mail->ReturnPath ("answer@mycompany.com");
	$mail->ReturnPath ("answer@mycompany.com", "My Company Support");

Priority ([integer $priority])

Definisce la priorità del messaggio. Opzionale.

La priorità deve essere un intero compreso tra 1 (massima) e 5 (minima). Questo valore è solitamente utilizzato dai client per evidenziare i messaggi marcati come urgenti.

	$mail->Priority (1); // urgente
	$mail->Priority (3); // normale
	$mail->Priority (5); // priorità minima

Receipt ([boolean flag])

Aggiunge una richiesta di ricevuta all'e-mail. La ricevuta viene inviata dal destinatario quando apre l'e-mail, se il suo client supporta questa funzionalità. La ricevuta è inviata all'indirizzo definito come mittente (From), a meno che non sia definito un indirizzo di risposta (ReplyTo) differente.
Il parametro flag è disponibile a partire dalla versione 1.5.0; il default è true. Se impostato a false, annulla l'eventuale richiesta di ricevuta impostata con le chiamate precedenti di Receipt().

	$mail->Receipt ();
	$mail->Receipt (false); // ho cambiato idea (1.5.0 e superiori)
Attenzione: le ricevute non fanno parte dello standard, perciò possono non essere supportate dai client e-mail.

Send ()

Invia l'e-mail. Non dimenticate di chiamare questo metodo. :)

	$mail->Send ();

Get ([boolean full_headers])

Restituisce l'intera e-mail (header + corpo + allegati) in formato "e;raw"e;. Utile per visualizzare l'e-mail o salvarla come testo o in un database.

Nelle versioni 1.4.2 e precedenti, il parametro full_headers non è disponibile; gli header Subject e To non sono inclusi nel valore di ritorno.

Nelle versioni 1.5.0 e successive, il parametro full_headers determina se gli header Subject e To debbano essere inclusi nel valore di ritorno.
true: Subject e To sono inclusi (default).
false: Subject e To non sono inclusi (comportamento come le versioni 1.4.x).

In altre parole, a partire dalla versione 1.5.0, gli header Subject e To sono inclusi nel valore di ritorno, ma è possibile chiamare Get(false) per forzare il comportamento che si aveva nelle versioni 1.4.x.

	$msg = $mail->Get ();
	// mostra il messaggio nella pagina
	echo "Messaggio inviato:<br><pre>", nl2br( $msg ) , "</pre>";
	// salva in un database
	$msg = str_replace ("'", "''", $msg);
	$bdd->exec ("insert into Mailbox( user, folder, message, senttime ) values ( 'toto', 'Sent', '$msg', $FCT_CURRENT_TIME");

Suggerimenti

Inviare un'e-mail in formato HTML

N.B. alcuni utenti non gradiscono ricevere e-mail in formato HTML.

Per inviare e-mail in HTML mail con libMail 1.4.x e precedenti, è necessario allegare il sorgente HTML come file:

	$file = "mail.html";
	$mail->Body ("Questa e-mail e' in HTML - che triste");
	// inline significa che il client e-mail cercherà di visualizzare l'HTML nel messaggio
	$mail->Attach ($file, "text/html", "inline");

Con libMail 1.4.2, non è necessario salvare l'HTML come file; è possibile fare ricorso al nuovo metodo AttachString:

	$html_content = "<html>...</html>";
	$mail->Body ("Questa e-mail e' in HTML - che triste");
	$mail->AttachString ($html_content, "text/html", "inline");

Un bug in libMail 1.4.1 e precedenti permetteva anche di inviare e-mail in HTML in questo modo:

	$html_content = "<html>...</html>";
	$mail->Body ($html_content);
	$mail->Attach ("noattach"); // o qualsiasi file non esistente

In questo modo si generava una e-mail malformata, che alcuni client e webmail erano comunque in grado di visualizzare "correttamente", mentre altri client non vi riuscivano.
Poiché la versione 1.4.2 cerca di replicare il funzionamento della 1.4.1, nel codice è stato inserito un kludge (un artifizio) che fa in modo che questa funzionalità scorretta sia mantenuta, a patto che il corpo del messaggio inizi con un tag <html> (oppure <! o <?). Questo kludge è rimosso nella versione 1.5.0. Non si dovrebbe comunque usare questo metodo per inviare e-mail in HTML, dal momento che alcuni utenti non saranno in grado di visualizzarle correttamente, pur possedendo un client con supporto HTML.

A partire da libMail 1.5.0, i modi descritti sopra sono tutti deprecati (inclusi quelli "buoni") in favore del nuovo metodo Html(); il contenuto HTML dovrebbe inoltre essere accompagnato da un'alternativa di puro testo:

	$text_content = "Hello, world!\n";
	$html_content = "<html><body><p>Hello, world!</p></body></html>";
	$mail->Body ($text_content);
	$mail->Html ($html_content);

In questo modo si genera un'e-mail in multipart/alternative che include le due versioni del contenuto. Sebbene sia possibile usare Html() da solo, senza impostare un'alternativa di puro testo con Body(), cioò non è consigliato. Inoltre, non si deve usare Body() per il contenuto in HTML.

Se la vostra pagina HTML contiene immagini o link non dimenticate di adottare una delle seguenti soluzioni:

Status

Name libmail
Lang php4 (4.3.0 and up)
Version 1.5.0
Lastmod Fri Jan 04 09:55 GMT 2008
Authors Leo West, Setec Astronomy, Pier Luigi Pau

Indice

  1. LIBMAIL
    1. Descrizione
    2. ChangeLog
    3. Sinossi
    4. Installazione
    5. Documentazione
      1. Costruttore
      2. Subject ([string subject])
      3. From (string from_email, [string from_name])
      4. To (mixed address)
      5. CC (mixed address)
      6. BCC (mixed address)
      7. Body ([string body], [string charset] )
      8. Text ([string body], [string charset] )
      9. Html ([string body], [string charset] )
      10. SetCharset (string charset)
      11. Attach (string filepath, [string mimetype], [string disposition], [string filename])
      12. AttachString (string content, [string mimetype], [string disposition], [string filename])
      13. Organization (string $org)
      14. ReplyTo (string replyto_email, [string replyto_name])
      15. ReturnPath (string returnpath_email, [string returnpath_name])
      16. Priority ([integer $priority])
      17. Receipt ([boolean flag])
      18. Send ()
      19. Get ([boolean full_headers])
    6. Suggerimenti
      1. Inviare un'e-mail in formato HTML
    7. Status
    8. Indice