8.4 Mail_IMAPv2 
| Besprochene Version: 0.1.0 | Lizenz: BSD-Lizenz |
| Klassendatei(en): Mail/IMAPv2.php; Mail/IMAPv2/ManageMB/ManageMB.php | |
Das Paket Mail_IMAPv2 stellt nicht nur die Möglichkeit zur Verfügung, auf ein IMAP-Postfach zuzugreifen, wie der Name vermuten lässt. Es handelt sich um einen objektorientierten Wrapper, der auf den IMAP-Funktionen von PHP basiert. Somit können Sie mit diesem Paket auf POP3-, IMAP- und NNTP-Server zugreifen. Allerdings setzt das Paket auch voraus, dass die IMAP-Erweiterung unter PHP verfügbar ist.
Sollte Ihre PHP-Installation nicht über die IMAP-Erweiterung verfügen, müssten Sie anstelle von Mail_IMAPv2 auf das Paket Net_IMAP zurückgreifen.
Um eine Verbindung zu einem Mailserver aufzubauen, benötigen Sie zuerst ein Mail_IMAPv2-Objekt, mit dem Sie dann die Methode connect() aufrufen. Diese bekommt einen String übergeben, der, ähnlich einem DSN, das verwendete Protokoll, den Usernamen, das Passwort und den Namen des Servers enthält. Ein solcher Verbindungsaufbau könnte so aussehen:
// Ausschalten von Notices error_reporting(E_ALL ^ E_NOTICE); // Einbinden der Klassendateien require_once ('Mail/IMAPv2.php'); require_once('PEAR.php'); // Ableiten eines neuen Objekts $imap = new Mail_IMAPv2; // Kodieren von Benutzername und Passwort $user=urlencode('user'); $pass=urlencode('passwort'); // Aufbau der Verbindung $erg = $imap->connect( "imap://$user:$pass@imap.domain.com/INBOX"); // Pruefen, ob ein Fehler aufgetreten ist if (false == $erg) { $err = $imap->error->pop(); die("Fehler: $err[message]"); } // Verarbeitung der Mails // Verbindung zum Server schliessen $imap->close();
Listing 8.7 Aufbau einer Verbindung zu einem IMAP-Server
Der String, der der Methode connect() übergeben wird, beginnt mit dem Protokoll, in diesem Fall also imap. An dieser Stelle könnten Sie also auch pop oder nntp nutzen. Nach dem Doppelpunkt und den beiden Slashes folgen der Benutzername und das Passwort, die durch einen Doppelpunkt getrennt sind. Um sicherzustellen, dass Sonderzeichen kein Problem darstellen, werden die beiden Werte zuerst an urlencode() übergeben. Danach folgen ein @ und der Name des Servers. Sollte es nötig sein, können Sie hier auch noch einen Port angeben, über den die Verbindung aufgebaut werden soll. Er wird auch mit einem Doppelpunkt angehängt.
Wenn Sie IMAP nutzen, folgt als Letztes der Name des Ordners, der verwendet werden soll. Dazu muss man wissen, dass IMAP sich deutlich von dem bekannten POP3-Protokoll unterscheidet. IMAP arbeitet komplett server-basierend. Die E-Mails werden nicht vom Server auf den Client kopiert, sondern verbleiben auf dem Server. Dabei ist es auch möglich, serverseitig verschiedene Ordner anzulegen, um die E-Mails zu verwalten.
In diesem Kapitel werde ich mich auf die Arbeit mit dem IMAP-Protokoll konzentrieren.
Kann die Verbindung aufgebaut werden, gibt die Methode true zurück, andernfalls false. Sollte ein Problem beim Aufbau der Verbindung auftreten, kann es passieren, dass die Methode eine Notice generiert. Daher ist in der ersten Zeile von Listing 8.7 die Ausgabe der Notices ausgeschaltet worden.
Der Rückgabewert wird genutzt, um zu testen, ob ein Fehler aufgetreten ist. Das Paket nutzt einen PEAR_ErrorStack, der in der Eigenschaft error abgelegt ist, um Fehler zu verwalten. Somit hätte ich auch mit
testen können, ob ein Fehler vorliegt. Innerhalb der if-Abfrage wird der Fehler mit pop() vom Stack entfernt und dann ausgegeben.
In der letzten Zeile des Codes wird die Verbindung zum Mail-Server mithilfe von close() wieder abgebaut.
Beim Aufbau einer Verbindung wird automatisch die Methode getMailboxInfo() aufgerufen: Diese liest aus, wie viele Nachrichten in der Mailbox vorhanden sind, und legt diese Informationen in der Eigenschaft mailboxInfo ab. Hierbei handelt es sich um ein Array. Im Schlüssel 'user' ist der Benutzername abgelegt, unter dem sich das Script zu dem Server verbunden hat, der in 'host' zu finden ist. Die Eigenschaft 'Nmsgs' speichert die Gesamtzahl der E-Mails, die sich in dem Postfach befinden. 'Unread' informiert Sie darüber, wie viele dieser Nachrichten noch nicht gelesen wurden, und in 'Deleted' ist die Anzahl der gelöschten E-Mails zu finden. E-Mails, die »gelöscht« sind, verbleiben auch auf dem Server, werden allerdings als gelöscht markiert.
Zusätzlich finden Sie in 'Size' noch die Anzahl der belegten Bytes und in 'Date' das Datum und die Uhrzeit, wann diese Informationen gesammelt wurden.
In diesem Zusammenhang ist unter Umständen auch die Methode getQuota() hilfreich. Sie gibt ein Array zurück, in dem die Information enthalten ist, wie viel Speicherplatz momentan belegt wird und wie viel Speicherplatz diesem Account zur Verfügung steht. Stellt der Server diese Daten nicht zur Verfügung, wird false zurückgegeben. Ein solches Array hat diesen Aufbau:
array(3) { ["usage"]=> int(10) // Belegter Speicherplatz in KB ["limit"]=> int(1024000) // Gesamter Speicherplatz in KB ["STORAGE"]=> // Die gleichen Zahlen in aufbereiteter Form array(2) { ["usage"]=> string(5) "10 KB" ["limit"]=> string(7) "1000 MB" } }
Mit diesen Informationen können Sie nun schon eine Oberfläche erstellen, die Ihnen eine Übersicht über die vorhandenen Mails gibt. Mit der Methode getHeaders() können Sie Informationen zu einer Mail abholen. Die Methode bekommt die Nummer der E-Mail als Parameter übergeben. Die E-Mails innerhalb des Postfachs werden hierbei durchnummeriert, wobei die Nummerierung mit eins beginnt. Die Nummer muss der Methode als Variable übergeben werden, da die Methode eine Referenz erwartet.
// Notices ausschalten error_reporting(E_ALL ^ E_NOTICE); require_once ('Mail/IMAPv2.php'); require_once('PEAR.php'); // Neues Objekt ableiten $imap = new Mail_IMAPv2; // Usernamen und Passwort kodieren $user=urlencode('user'); $pass=urlencode('passwort'); // Verbindung zum Server aufbauen $erg = $imap->connect( "imap://$user:$pass@imap.1und1.com/INBOX"); // Ist ein Fehler aufgetreten? if (false == $erg) { $err = $imap->error->pop(); die("Fehler: $err[message]"); } // Informationen ueber die Mailbox auslesen $mails_gesamt = $imap->mailboxInfo['Nmsgs']; $mails_unread = $imap->mailboxInfo['Unread']; $mails_deleted = $imap->mailboxInfo['Deleted']; // Anzahl der gelesenen E-Mails berechnen $mails_read=$mails_gesamt-$mails_deleted-$mails_unread; echo "<p>E-Mails insgesamt: $mails_gesamt<br />"; echo "<cite>gelesen: $mails_read<br />"; echo "ungelesen: $mails_unread<br />"; echo "gelöscht: $mails_deleted</cite></p>"; echo '<table>'; echo '<tr> <th>Absender</th> <th>Betreff</th> <th>Datum</th> <th>Uhrzeit</th> <th colspan="3">Status</th> </tr>'; // E-Mails einzeln in einer Schleife auslesen for ($cnt=1; $cnt <= $mails_gesamt; $cnt+=1) { // E-Mail abrufen $headers =$imap->getHeaders($cnt); $timestamp=strtotime($headers['MailDate']); echo '<tr>'; echo '<td>'.htmlentities($headers[fromaddress]).'</td>'; echo "<td><a href='show.php?mid=$cnt'>". htmlentities($headers[Subject])."</a></td>"; echo "<td>".date("d.m.Y",$timestamp)."</td>"; echo "<td>".date("H:i:s",$timestamp)."</td>"; echo "<td>$headers[Unseen]</td>"; echo "<td>$headers[Answered]</td>"; echo "<td>$headers[Deleted]</td>"; echo '</tr>'; } echo '</table>'; // Quotas auslesen und ausgeben $quotas=$imap->getQuota(); echo "<p>belegter Speicherplatz: {$quotas['STORAGE']['usage']}"; echo " insgesamt verfügbar: {$quotas['STORAGE']['limit']}</p>"; $imap->close();
Listing 8.8 Auslesen eines IMAP-Postfachs mit Mail_IMAPv2
Abbildung 8.2 Ausgabe des Scripts im Browser
getHeaders() liefert umfangreiche Daten zurück, wie Sie dem Listing schon entnehmen können. Für jede Mail erhalten Sie ein Array mit den Schlüsseln aus Tabelle 8.2.
Die Elemente 'Recent', 'Flagged', 'Unseen', 'Answered', 'Deleted' und 'Draft' können nur in Kombination mit dem IMAP-Protokoll sinnvoll genutzt werden.
Nicht alle Server geben das Flag Recent zurück, so dass es sinnvoll sein kann, nur auf Unseen zurückzugreifen, um festzustellen, ob eine E-Mail bereits gelesen wurde.
In dem Array sind noch weitere Schlüssel enthalten, die hier nicht aufgeführt sind, da die Inhalte (Name des Servers in der Absenderadresse etc.) sich aus den oben genannten Werten ableiten lassen.
Die so dargestellte Übersicht bezieht sich immer nur auf einen Ordner in einem Postfach. Wenn Sie das IMAP-Protokoll nutzen, stehen unter Umständen mehrere Ordner zur Verfügung. Welche Ordner vorhanden sind, können Sie mit der Methode getMailboxes() auslesen. Die vorhandenen Ordner gibt die Methode als numerisches Array zurück. Um eine Verbindung zu einem anderen Postfach aufzubauen, beenden Sie die bestehende Verbindung und öffnen eine neue Verbindung zu dem gewünschten Postfach. Möchten Sie beispielsweise eine Verbindung zu dem Ordner Junk-E-Mail öffnen, den Microsoft Outlook standardmäßig anlegt, nutzen Sie:
In Listing 8.8 sind die Betreffzeilen der E-Mails mit einem Link auf die Datei show.php hinterlegt, der die ID einer E-Mail als Parameter übergeben wird. Diese Datei soll die E-Mail komplett darstellen.
Dazu benötigen Sie zusätzlich zu den besprochenen Methoden noch getParts() und getBody(). getParts() analysiert die E-Mail und teilt Ihnen mit, ob Anhänge vorhanden sind. Diese Informationen werden in der Eigenschaft msg abgelegt. getBody() ist die Methode, mit der Sie die einzelnen Bestandteile der Nachricht vom Server abholen können.
error_reporting(E_ALL ^ E_NOTICE); if (false === isset($_GET['mid'])) { die ('Die Message-ID muss ueber die URL uebergeben werden'); } // Message-ID auslesen $mid = $_GET['mid']; require_once ('Mail/IMAPv2.php'); require_once('PEAR.php'); $imap = new Mail_IMAPv2; $user=urlencode('user'); $pass=urlencode('passwort'); $erg = $imap->connect( "imap://$user:$pass@imap.example.com/INBOX"); if (false == $erg) { $err = $imap->error->pop(); die("Fehler: $err[message]"); } // Header auslesen $headers =$imap->getHeaders($mid); if (false == $headers) { $err = $imap->error->pop(); die("Fehler: $err[message]"); } echo "<p>Von: ".htmlentities($headers['fromaddress']); echo "<br />Betreff: ".htmlentities( $headers['subject'])."</p>"; // Koerper der E-Mail auslesen und ausgeben $body=$imap->getBody($mid); // Nur fuer Text-Mails! $body_ausg=htmlentities($body['message']); echo (nl2br($body_ausg)); // Mithilfe von getParts analysieren $erg=$imap->getParts($mid); // Analysieren, ob die E-Mail Anhaenge hat $parts=$imap->msg[$mid]; if (false===isset($parts['at'])) { echo '<p>Die Nachricht hat keine Anhänge</p>'; } else { // Dateianhaenge in Schleife ausgeben echo "<p>Die Nachricht hat die folgenden Anhänge:<br />"; for($cnt = 0; $cnt < count($parts['at']['fname']); $cnt+=1) { echo "Datei: <a href= 'download.php?mid=$mid&pid={$parts['at']['pid'][$cnt]}'> {$parts['at']['fname'][$cnt]}</a>"; echo " Größe: ".$imap->convertBytes( $parts['at']['fsize'][$cnt])."<br />"; } } $imap->close();
Listing 8.9 Darstellen einer einzelnen Mail im Browser
Das Paket geht davon aus, dass eine E-Mail aus mindestens einem Teil, nämlich dem eigentlichen Inhalt, besteht. Verfügt eine E-Mail über Anhänge, werden diese als eigene, zusätzliche Bestandteile eingestuft. Die einzelnen Teile werden beginnend mit 1 durchnummeriert.
Zum Auslesen dieser Teile steht getBody() zur Verfügung. Die Methode bekommt mindestens die ID der E-Mail übergeben und gibt dann den eigentlichen Body der E-Mail als Teil eines Arrays zurück. Zusätzlich können Sie ihr noch eine zweite Zahl übergeben, um zu spezifizieren, dass nicht der erste Teil der E-Mail, sprich der Body, sondern der zweite oder ein weiterer Teil ausgelesen werden soll. Der Inhalt des Teils, der ausgelesen wurde, ist im Schlüssel 'message' abgelegt. Das heißt, hier ist dann der dekodierte Text der E-Mail oder der dekodierte Dateianhang zu weiteren Verwendung zu finden.
Der Schlüssel 'ftype' enthält den MIME-Type, und in 'fname' ist der Name der Datei zu finden. Der Name wird natürlich nur bei einem Dateianhang genutzt. Der letzte Schlüssel ist 'charset'. Hier wird der Zeichensatz abgelegt, was allerdings nur dann der Fall ist, wenn es sich um den Körper der E-Mail handelt.
Die Methode getParts() bekommt die ID einer E-Mail übergeben und analysiert, aus wie vielen Teilen diese besteht. Diese Daten werden in der Eigenschaft msg abgelegt. Bei der Eigenschaft handelt es sich um ein mehrfach verschachteltes Array. Die Informationen zu einer E-Mail finden Sie jeweils unter der ID der Nachricht, die in der ersten Ebene als Schlüssel fungiert. Ist in diesem Array ein Schlüssel namens 'at' für Attachment enthalten, so verfügt die E-Mail über Anhänge. In diesem Array sind vier Schlüssel vorhanden, die wiederum auf ein Array verweisen. Der Schlüssel 'fname' verweist somit auf ein indiziertes Array, in dem für jeden der Dateianhänge ein Feld vorhanden ist, in dem der Name der Datei abgelegt ist. 'ftype' verweist auf ein Array, in dem für jede der Dateien der dazugehörige MIME-Type enthalten ist, und unterhalb von 'fsize' sind die Größenangaben der Dateien in Bytes zu finden. Der Schlüssel 'pid' schließlich enthält die »Part IDs«, also die Nummer der E-Mail-Bestandteile, unter denen Sie diese Bestandteile mit getBody() ansprechen können.
In Listing 8.9 finden Sie auch noch die Methode convertBytes(). Hierbei handelt es sich um eine Hilfsmethode, der Sie einen Integer-Wert übergeben können. Die Methode konvertiert die Zahl jeweils in die größtmögliche Einheit (Bytes, KByte, MByte, GByte) und gibt die resultierende Zahl inklusive der Einheit zurück.
Jeder Dateiname wird für die Ausgabe mit einem Link auf die Datei download.php hinterlegt, der die ID von Nachricht und die des herunterzuladenden Teil übergeben werden. Das Script zum Herunterladen von Dateianhängen könnte so aussehen:
error_reporting(E_ALL ^ E_NOTICE); if (false === isset($_GET['mid']) || false === isset($_GET['pid'])) { die ('Die Message-ID und Part-ID muessen uebergeben werden'); } // Message-ID auslesen $mid = $_GET['mid']; $pid = $_GET['pid']; require_once ('Mail/IMAPv2.php'); require_once('PEAR.php'); $imap = new Mail_IMAPv2; $user=urlencode('user'); $pass=urlencode('passwort'); $erg = $imap->connect( "imap://$user:$pass@imap.1und1.com/INBOX"); if (false == $erg) { $err = $imap->error->pop(); die("Fehler: $err[message]"); } // Anhang auslesen $body=$imap->getBody($mid,$pid); $mime=$body['ftype']; $name=$body['fname']; $content =$body['message']; // Header senden und Datei uebertragen header("Content-type: $mime"); header("Content-Disposition: attachment; filename='$name'"); echo $content;
Listing 8.10 Download eines Dateianhangs mit Mail_IMAPv2
Möchten Sie eine E-Mail in einem Ordner zum Löschen markieren, übergeben Sie der Methode delete() die ID dieser Nachricht. Um alle E-Mails, die in einem Ordner zum Löschen markiert sind, wirklich zu entfernen, rufen Sie die Methode expunge() auf. Wenn Sie ein POP3-Postfach nutzen, werden die E-Mails nicht dauerhaft zum Löschen markiert. Die Markierung geht nach Ende des Scripts wieder verloren. In diesem Fall müsste expunge() also sofort aufgerufen werden, wenn eine E-Mail zum Löschen markiert wurde, was bei Nutzung des IMAP-Protokolls nicht notwendig ist.
Möchten Sie, wenn Sie IMAP nutzen, bestimmte Flags setzen, ist die Methode setFlags() hilfreich. Sie bekommt als ersten Parameter die ID der Nachricht übergeben und als zweiten Parameter '\\Seen', um eine E-Mail als gelesen zu markieren. '\\Answered' legt fest, dass die Nachricht beantwortet wurde, '\\Draft' besagt, dass die E-Mail ein Entwurf ist, und '\\Flagged' markiert sie. Zusätzlich können Sie mit '\\Deleted' eine Nachricht auch zum Löschen markieren.
Mit dieser Methode können Sie ein bestimmtes Flag auch wieder entfernen, wenn Sie den String 'clear' als dritten Parameter übergeben.
Um Postfächer auf einem IMAP-Server besser verwalten zu können, ist die Klasse Mail_IMAPv2_ManageMB vorgesehen, die in der Datei Mail/IMAPv2/ ManageMB/ManageMB.php definiert ist und eine Erweiterung zu Mail_IMAPv2 darstellt.
Der Konstruktor bekommt den String mit den Informationen für den Verbindungsaufbau direkt übergeben, wobei dieser so aufgebaut ist wie bei Mail_IMAPv2 beschrieben.
Um Nachrichten von einem Ordner in einen anderen zu verschieben, ist die Methode manageMail() definiert. Sie bekommt als ersten Parameter 'copy' oder 'move' übergeben, um eine oder mehrere Nachrichten zu kopieren oder zu verschieben. Als zweiten Parameter übergeben Sie ein Array mit den IDs der E-Mails, die in dem anderen Ordner abgelegt werden sollen, und an letzter Stelle folgt der Name des Ordners, der das Ziel darstellt. Die folgenden Zeilen verschieben die Nachrichten mit den IDs 1 und 3 in den Ordner Junk-E-Mail.
error_reporting(E_ALL ^ E_NOTICE); require_once ('Mail/IMAPv2.php'); require_once ('Mail/IMAPv2/ManageMB/ManageMB.php'); require_once('PEAR.php'); $user=urlencode('user'); $pass=urlencode('passwort'); $imap = new Mail_IMAPv2_ManageMB( "imap://$user:$pass@imap.1und1.com/INBOX"); if (false == $imap) { $err = $imap->error->pop(); die("Fehler: $err[message]"); } $erg=$imap->manageMail('move',array(1,3), 'Junk-E-Mail'); if (false == $erg) { $err = $imap->error->pop(); die("Fehler: $err[message]"); }
Wenn Sie E-Mails verschieben, so beachten Sie bitte, dass diese im Ursprungsordner nicht gelöscht, sondern nur zum Löschen markiert werden.
Hilfreich kann auch die Methode importMail() sein. Möchten Sie beispielsweise von einem POP3- zu einem IMAP-Postfach migrieren, könnte es hilfreich sein, wenn Sie bereits erhaltene E-Mails in das IMAP-Postfach importieren könnten. Genau das kann diese Methode für Sie übernehmen. Als ersten Parameter bekommt die Methode den Namen des Ordners übergeben, in dem die E-Mail bzw. die E-Mails abgelegt werden soll(en). Der zweite Parameter ist ein Array, in dem Sie die zu importierenden E-Mails als Rohdaten übergeben. Das heißt, in dem Array ist für jede E-Mail ein Feld vorzusehen, in dem die komplette E-Mail als Rohdaten inklusive der Header, Zeilenumbrüche und Anhänge zu übergeben ist.
Darüber hinaus ist es auch möglich, mit der Methode manageDB() Ordner zu verwalten. Als ersten Parameter können Sie 'create' übergeben, um einen neuen Ordner anzulegen, 'delete', um einen Ordner zu löschen, und mit 'rename' können Sie einen Ordner umbenennen. Der Name des betreffenden Ordners wird als zweiter Parameter angegeben. Das Umbenennen erfordert noch einen dritten Parameter, nämlich den Namen, den der Ordner erhalten soll. Diese Methode scheint momentan allerdings noch nicht mit jedem Server und jedem E-Mail-Client zu harmonieren.
