Piszemy klienta poczty e-mail w PHP

Autor: Tomasz Jędrzejewski
Data publikacji: 18.12.2003, 17:52 | Ostatnia modyfikacja: 02.11.2006, 16:57

Artykuł ten demonstruje, jak napisać klienta poczty elektronicznej korzystającego z protokołu IMAP w PHP. Zawiera także wprowadzenie do modułu "imap".

Spis treści

Zapewne wiele razy patrzyłeś z zazdrością na interfejsy WWW do zarządzania kontem pocztowym. Ba - być może nawet marzyłeś o stworzeniu własnego? Tylko jak się do tego zabrać, co jest potrzebne? Otóż do stworzenia takiego czegoś potrzeba PHP, odrobiny inwencji, oraz rozszerzenia IMAP. Tak oto witam w kolejnym artykule z serii "Piszemy cośtam", tym razem biorącym pod ostrzał klienty poczty e-mail...

Jak to będzie wyglądać?

Na początku musimy sobie zadać ważne pytanie: jak to ma wyglądać? Zdecydowałem się na stworzenie klienta, który:

Pozwoli na logowanie się do dowolnej skrzynki na serwerze
Pozwoli zobaczyć statystyki skrzynki
Pozwoli przejrzeć listę wiadomości, oraz zobaczyć treść tych nas interesujących
Zezwoli nam na kasowanie niechcianych wiadomości
Da nam możliwość wysyłania wiadomości, oraz odpowiadania na nie

Wiemy już, że do tego zadania wykorzystamy protokół pocztowy IMAP, oraz moduł PHP pozwalający się poprzez niego komunikować. Mocno zalecam także pobranie jakiegoś serwera poczty e-mail, by móc spokojnie testować omawiany tu kod.

Do góry

Instalacja modułu

W systemach Windows jest ona (jak zwykle :)) bajecznie prosta - wystarczy otworzyć plik php.ini i usunąć średnik sprzed linii

;extension = php_imap.dll

pod Unixem należy zrekompilować PHP z opcjami

--with-imap=sciezka_do_biblioteki_klienckiej

Jak zwykle, w Unixie musimy mieć gdzieś odpowiednią bibliotekę. Tym razem odeślę do manuala PHP, gdzie opisany jest proces kompilacji jednej z nich.

Należy pamiętać, że modułu IMAP w żadnym wypadku nie wolno nam używać razem z modułami Recode i YAZ, gdyż używają one tej samej sygnatury i może to powodować wiele problemów.

Do góry

Instalacja serwera IMAP

Aby nie mieć problemów z prezentowanym w dalszej części artykułu kodem PHP, zalecam pobranie jakiegokolwiek serwera IMAP. Jeśli pracujesz na systemie UNIX/Linux, możesz sprawdzić ten adres: http://www.inter7.com/courierimap.html. Ja jednak piszę to wszystko w oparciu o system Windows, więc znajdzie się tu opis instalacji Windowsowego klienta. Jest nim MercuryMail, którego można pobrać ze strony http://www.pmail.com/. Instalacja jest prosta i właśnie dlatego ją opiszę :).

Uruchom pobrany plik i kliknij przycisk "Setup". Po rozpakowaniu archiwum i uruchomieniu programu instalacyjnego wskaż "New Installation". Zostaniesz zapytany o to, czy chcesz integracji z systemami Novell NetWare. Jak ktoś wie, o co chodzi, to intuicja sama mu podpowie, co wybrać, natomiast reszta powinna kliknąć przycisk "No NetWare support". Kolejnym krokiem jest wskazanie katalogu, do którego ma zostać zainstalowany program. Po kliknięciu na "OK" program zapyta się o... następną ścieżkę instalacyjną :). Jednak podejrzewam, że nie posiadasz programu "Pegasus Mail", a więc nie musisz integrować z nim Mercurego. Kliknij więc na "No Pegasus Mail integration", by powiedzieć o tym instalatorowi. Następnie kolejna ścieżka, na nasze potrzeby wystarczy zaakceptować domyślną. Teraz zostaniesz zaprowadzony do bardzo ważnego okna, a mianowicie do wyboru protokołów i możliwości, które chcesz mieć aktywne. Nam wystarczą "SMTP server module" i "IMAP4rev1 module" (na dole). Będzie trzeba jeszcze wybrać jakieś duperszmity związane z optymalizacją korzystania z SMTP, ale nam to niepotrzebne, więc wybieramy "Install no SMTP client". Potem będziesz musiał wypełnić dane odnośnie sieciowej konfiguracji. Wpisz domenę, w jakiej pracujesz (najprawdopodobniej wystarczy "localhost"). Następnie program poprosi Cię o wskazanie, co ma robić z e-mailami przeznaczonymi dla innych serwerów. Jako, że my raczej nie będziemy ich wysyłać tak daleko, możesz wskazać "None". Potwierdź jeszcze jedną ścieżkę dostępu i wreszcie będzie Ci dane ujrzeć przycisk "Install Mercury/32" :). Chyba wiesz, co należy już zrobić?

Do góry

Konfiguracja serwera Mercury

Jako że chcemy porządnie "pobawić" się protokołem IMAP, dodamy sobie parę skrzynek pocztowych. Uruchom Mercurego (plik mercury.exe), po czym wybierz z menu pozycję "Configuration". Na dole jest opcja "Manage local users". Po kliknięciu na nią ukaże się okienko, które pozwoli Ci na utworzenie i zarządzanie skrzynkami pocztowymi userów. Resztę opcji możesz zostawić w spokoju, gdyż powinna automatycznie dopasować się do ustawień twego komputera.

Do góry

Zaczynamy programować

A więc przystąpmy do programowania. Z serwerem IMAP (który musi być włączony w trakcie testów) łączymy się podobnie, jak z bazą. Musimy najpierw otworzyć połączenie, a na końcu je zamknąć. Napisałem wyżej, że nasz skrypt umożliwi logowanie się do rozmaitych skrzynek pocztowych na serwerze, więc podobna praktyka, jak przy łączeniu się ze zwykłą bazą danych (że nazwę użytkownika i hasło wbudowujemy w skrypt) odpada. Musimy napisać stosowny mechanizm. Będzie on umieszczony w katalogu "includes" w pliku "polacz.php":

<?php
   define('CZAS_SESJI', 3600);
 
   function polacz($user, $haslo){
      $r = @imap_open('{eniac.blok22}', $user, $haslo) or $r = imap_last_error();
      return $r;
   }
 
   if($_GET['co']   == 'wyloguj'){
      unset($_COOKIE['user']);
      unset($_COOKIE['pass']);
      setcookie('user', '', 0);
      setcookie('pass', '', 0);
   }
 
   if(!isset($_COOKIE['user']) || !isset($_COOKIE['pass'])){
      if(isset($_POST['user']) && isset($_POST['pass'])){
         $imap = polacz($_POST['user'], $_POST['pass']);
         if(is_string($imap)){
            // Blad
            blad($imap);
            loguj();
            stopka();
            die();
         }elseif(is_resource($imap)){
            setcookie('user', $_POST['user'], time()+CZAS_SESJI);
            setcookie('pass', $_POST['pass'], time()+CZAS_SESJI);
         }
      }else{
         loguj();
         stopka();
         die();
      }
   }else{
      if(isset($_COOKIE['user']) && isset($_COOKIE['pass'])){
         $imap = polacz($_COOKIE['user'], $_COOKIE['pass']);
         if(is_string($imap)){
            // Blad
            blad($imap);
            loguj();
            stopka();
            die();
         }elseif(is_resource($imap)){
            setcookie('user', $_COOKIE['user'], time()+CZAS_SESJI);
            setcookie('pass', $_COOKIE['pass'], time()+CZAS_SESJI);
         }
      }
   }
?>

Za połączenie się odpowiada funkcja "polacz" zawierająca odwołanie do pierwszej poznanej przez nas funkcji obsługi IMAP'a - imap_open(). Jako parametry musimy podać nazwę hosta, pod jakim dostępny jest serwer IMAP (koniecznie w nawiasach klamrowych). Następnie wskazujesz użytkownika, który posiada na serwerze skrzynkę, oraz jego hasło. Funkcja imap_last_error() pozwala zwrócić ewentualny komunikat błędu.

Dalszy kod sprawdza, czy ktoś jest zalogowany, czy też nie i w zależności od tego podejmuje stosowną akcję. Nazwa użytkownika i hasło przesyłane są poprzez ciastko. Jeśli nie jesteś wybredny/nie masz jeszcze zbyt dużych zdolności, możesz kodu tego używać jako logowania do twego serwisu (aczkolwiek bezpieczny to on nie jest...).

W powyższym przykładzie znajdują się odwołania do funkcji typu "loguj", "stopka", "blad". Są to funkcje generujące kod HTML dla naszego klienta i wysyłające go do przeglądarki. Umieszczone są one w pliku "layout.php" w katalogu "includes", a plik ten prezentuje się następująco (listing jest baaaaaaaardzo długi, ale jakoś musimy przez niego przebrnąć...):

Aby zaoszczedzić miejsce: Pobierz kod listingu.

Zauważ, że połączenie z serwerem IMAP zamyka funkcja stopka(). Używa do tego celu funkcji "imap_close()" pobierającej identyfikator połączenia. Teraz możemy już przystąpić do napisania właściwych i działających już plików. Najpierw stworzymy plik "index.php" (wszystkie następne pliki umieszczaj w katalogu głównym skryptu) z taką zawartością:

<?php
 
   require('./includes/layout.php');
   naglowek('Statystyki skrzynki');
 
   require('./includes/polacz.php');
 
   pasek_narzedzi();
 
   $skrzynka = imap_mailboxmsginfo($imap);
   if(is_object($skrzynka)){
      statystyki(
         $skrzynka->Date,
         $skrzynka->Driver,
         preg_replace('/\{(.*?):([0-9]*)\/imap\/user="(.*?)"}INBOX/', '\\3@\\1', $skrzynka->Mailbox),
         $skrzynka->Nmsgs,
         $skrzynka->Recent,
         $skrzynka->Unread,
         $skrzynka->Deleted,
         $skrzynka->Size
      );
   }else{
      blad('Nie można pobrać statystyk skrzynki!');
   }
 
   stopka();
 
?>

Plik ten będzie wyświetlać statystyki naszej skrzynki. Możemy pobrać je funkcją "imap_mailboxmsginfo()". Za parametr pobiera tylko identyfikator połączenia, a w zamian zwraca obiekt z interesującymi nas danymi. Mamy więc datę, ilość nowych wiadomości, ilość usuniętych, ilość nieczytanych itp. Zwróć uwagę, że pole "Mailbox" potraktowałem dodatkowo funkcją preg_replace. Po co? Ponieważ normalnie dostajemy różne głupoty w stylu "{localhost:port/imap/user=zyx}INBOX", lecz są one lekko niezrozumiałe. Dlaczegóż więc nie przerobić ich na czytelniejszą postać "zyx@localhost"?

Tu dam jeszcze małą poradę: jeśli zależy Ci na wydajności i nie masz nic przeciwko lekkiemu uszczupleniu ilości danych prezentowanych w statystykach, użyj do pobrania danych funkcji imap_status(). W manualu znaduje się komentarz dodany przez jednego z programistów PHP, który pokazuje różnicę wydajności. Pobranie danych ze skrzynki z 3987 wiadomościami przy użyciu imap_mailboxmsginfo() - 6 minut i 5 sekund; przy użyciu imap_status() - 11,05 sekundy. Wynik przemawia sam za siebie.

Do góry

Wysyłanie wiadomości

Mimo iż funkcja wysyłająca wiadomości e-mail ma w nazwie "imap", to używa do tego celu protokołu SMTP i właściwie można uznać ją za synonim funkcji mail(). Korzystają one z tych samych ustawień w php.ini, dlatego wejdź tam i odszukaj blok (uwaga: wyciąłem komentarze, by nie marnować miejsca):

[mail function]
SMTP = localhost

sendmail_from = zyx@localhost

;sendmail_path =

;mail.force_extra_paramaters =

Wszyscy powinni w dyrektywie SMTP wpisać nazwę serwera SMTP. Jako że my zainstalowaliśmy Mercurego z obsługą tego protokołu, możesz tam śmiało wpisać "localhost". Dyrektywę "sendmail_from" wypełniają użytkownicy Windowsa, natomiast dwie następne użytkownicy systemów unixowych.

A oto kod pliku "wiadomosc.php" wyświetlającego odpowiedni formularz, a następnie "wyslij.php" wysyłającego e-maila:

<?php
 
   require('./includes/layout.php');   
   naglowek('Edytor wiadomosci');
 
   require('./includes/polacz.php');
 
   pasek_narzedzi();
 
   if(isset($_GET['odp'])){
      $naglowki = imap_header($imap, $_GET['odp']);
 
      if($naglowki -> Subject == ''){
         $temat = 'Brak tematu';
      }else{
         $temat = $naglowki -> Subject;
      }
 
      form_wiad($temat, $naglowki -> fromaddress);
   }else{
      form_wiad();
   }
   
   stopka();
 
?>

Zapewne dostrzegłeś tu nieznaną funkcję "imap_header()". Jej znaczenie poznamy dalej. Tu jest ona potrzebna, by móc prawidłowo obsłużyć odpowiadanie na wiadomości. Oto kod pliku "wyslij.php":

<?php
 
   require('./includes/layout.php');
   naglowek('Wysylanie');
 
   require('./includes/polacz.php');
 
   pasek_narzedzi();
 
   if(imap_mail($_POST['to'], $_POST['temat'], $_POST['tresc'], 'Content-type: text/plain')){
      komunikat('Wiadomość została wysłana.');
   }else{
      blad(imap_last_error());
   }
 
   stopka();
 
?>

Tak więc naszą funkcją wysyłającą wiadomości był "imap_mail()". W swej podstawowej formie używa jej się tak samo, jak "mail()" i możliwe, że składnia wydaje się znajoma.

Do góry

Wyświetlanie listy wiadomości

Lista wiadomości będzie wyświetlana poprzez plik "skrzynka.php". Oto jego kod:

<?php
 
   require('./includes/layout.php');
   naglowek('Twoja skrzynka');
 
   require('./includes/polacz.php');
 
   pasek_narzedzi();
 
   if(isset($_POST['usun'])){
 
      if(count($_POST['dmsg']) > 0){
         foreach($_POST['dmsg'] as $wiad_num){
            imap_delete($imap, $wiad_num);
         }
         imap_expunge($imap);
      }
   }
 
   $ilosc = imap_num_msg($imap);
 
   if($ilosc > 0){
      list_wiadomosci();
 
      for($i = $ilosc; $i > 0; $i--){
         $naglowki = imap_header($imap, $i);
         $struktura = imap_fetchstructure($imap, $i);
 
         if($naglowki -> Subject == ''){
            $temat = 'Brak tematu';
         }else{
            $temat = $naglowki -> Subject;
         }
 
         wiadomosc($i, substr($naglowki->Date, 0, 22), htmlspecialchars($naglowki->fromaddress), $temat, ceil(($structure->bytes/1024)).' KB');
      }
 
      list_wiadomosci_koniec();
 
   }else{
      komunikat('Brak wiadomości w skrzynce');
   }
 
   stopka();
 
?>

Każda wiadomość w protokole IMAP ma przypisany specjalny identyfikator, czyli numer wiadomości. Działa on jednak trochę inaczej od identyfikatorów w bazach danych, co pozwala nam na pobranie wiadomości zwykłą pętlą for. Na początku ustalamy ilość e-maili funkcją imap_num_msg(), a później uruchamiamy pętlę. Za każdym przebiegiem dane o pojedynczym liście otrzymujemy wywołując funkcje imap_header() i imap_fetchstructure(). Pierwsza z nich pozwala nam pobrać takie duperszmity, jak temat, adresat, nadawca, flaga. Z kolei druga daje nam dostęp do danych technicznych e-maila: typu (np. text/plain), rozmiaru, kodowania. Nas interesuje tylko rozmiar, który potem odpowiednio przetwarzamy. Wszystko wprowadzamy do funkcji wiadomosc(), która generuje kod HTML dla pojedynczego wiersza z danymi wiadomości. Dodaje także tam pole checkbox pozwalające nam na wybranie wiadomości do usunięcia. Możesz teraz skoczyć do pliku "layout.php", by podpatrzeć jego nazwę. Pole to zwie się "dmsg[]". Widzisz te nawiasy klamrowe? Dzięki temu do PHP (po kliknięciu na "Usuń zaznaczone") przejdzie tablica z numerami wszystkich e-maili do skasowania, a nie numer ostatniej zaznaczonej pozycji. Kod obsługujący usuwanie znajduje się tuż nad kodem wyświetlającym. Każdą wiadomość najpierw oznaczam flagą "Usunięty" używając do tego funkcji "imap_delete()". Jednak nie oznacza to fizycznego usunięcia listu z serwera. Do tego potrzebne jest jeszcze wywołanie funkcji imap_expunge(). Dlaczego jest to tak udziwnione? Zobacz: dzięki temu możesz stworzyć coś w stylu "Elementów usuniętych". Wspomniałem wcześniej, że funkcja imap_header() zwraca m.in flagę listu. Jedną z możliwych flag jest "Usunięty". Oznacza to, że w skrzynce odbiorczej możesz wyświetlać wszystkie listy, które tej flagi ustawionej nie mają (można do tego użyć zwykłej instrukcji IF). W "Elementach usuniętych" przeciwnie - flaga ta musi być ustawiona, by listy tam się znalazły. Dalsza przeróbka: w skrzynce odbiorczej przy usuwaniu nie wywołujesz imap_expunge(); jej wywołanie przenosisz do pliku odpowiedzialnego za elementy usunięte - tam jest ona aktywowana po kliknięciu na "Opróżnij elementy usunięte".

Do góry

Wyświetlanie pojedynczej wiadomości

Samo pokazanie listy wiadomości nie wystarczy, jeśli użytkownik nie może ich przeczytać. Dlatego też stworzymy teraz plik "zobacz.php" pokazujący treść wiadomości. Wykorzystałem w nim kod zaprezentowany w komentarzach do dokumentacji PHP. Daje on nam pewność, że treść zostanie porządnie zdekodowana i złożona do kupy. "Suche" wywołanie funkcji do pobierania tekstu z listu jest MOCNO niezalecane.

<?php
 
   function pobierz_mime(&$structure){
      $primary_mime_type = array('TEXT', 'MULTIPART', 'MESSAGE', 'APPLICATION', 'AUDIO', 'IMAGE', 'VIDEO', 'OTHER');
      if($structure->subtype){
         return $primary_mime_type[(int) $structure->type] . '/' . $structure->subtype;
      }
      return 'TEXT/PLAIN';
   }
 
   function pobierz_czesc($stream, $msg_number, $mime_type, $structure = 0, $part_number = 0){
      if(!$structure){
         $structure = imap_fetchstructure($stream, $msg_number);
      }
 
      if($mime_type == pobierz_mime($structure)){
         if(!$part_number){
            $part_number = '1';
         }
         $text = imap_fetchbody($stream, $msg_number, $part_number);
         if($structure->encoding == 3){
            return imap_base64($text);
         }elseif($structure->encoding == 4){
            return imap_qprint($text);
         }else{
            return $text;
         }
      }
      if($structure->type == 1){
         while(list($index, $sub_structure) = each($structure->parts)){
            if($part_number){
               $prefix = $part_number . '.';
            }
            $data = pobierz_czesc($stream, $msg_number, $mime_type, $sub_structure, $prefix . ($index + 1));
            if($data){
               return $data;
            }
         }
      }
 
      return 0;
   }
 
   require('./includes/layout.php');
   naglowek('Edytor wiadomosci');
 
   require('./includes/polacz.php');
 
   pasek_narzedzi();
 
   if($_GET['num'] > 0){
      $naglowki = imap_header($imap, $_GET['num']);
 
      pokaz($_GET['num'], $naglowki->fromaddress, $naglowki -> Subject, nl2br(pobierz_czesc($imap, $_GET['num'], 'TEXT/PLAIN')));
 
   }
 
   stopka();
 
?>

Treść listu pobierana jest funkcją imap_fetchbody(). Podajemy do niej: identyfikator połączenia, numer wiadomości, oraz numer części do pobrania. Posługując się funkcją imap_fetchstructure() pobieramy dane techniczne wiadomości, które pozwolą nam ją rozkodować. Jeśli została ona podzielona na kilka części, używany jest mechanizm rekurencji do pobrania całości.

Generowany kod HTML zawiera dwa odnośniki: "Odpowiedz" kierujący nas do pliku "wiadomosc.php"; "Usuń" dający nam możliwość skasowania wiadomości. Do tego potrzebny jest jednak plik "usun.php", a oto jego kod:

<?php
 
   require('./includes/layout.php');
   naglowek('Wysylanie');
 
   require('./includes/polacz.php');
 
   pasek_narzedzi();
 
   if(isset($_GET['num'])){
      imap_delete($imap, $_GET['num']);
      imap_expunge($imap);
      komunikat('Wiadomosc zostala usunięta');
   }else{
      blad('Nie wybrano wiadomości!');
   }
 
   stopka();
 
?>

Krótko i przejrzyście :). Możesz teraz przetestować cały skrypt.

Do góry

Zakończenie

Tak oto artykuł ten dobiega powoli końca. Pozostaje mi tylko wyrażać nadzieję, że zainteresowałem Cię tym tematem i że będziesz dalej eksperymentował z przedstawionym tu kodem. Oto, co mógłbyś wykonać dla przećwiczenia praktycznego poznanych informacji: