/zf/library/Zend/Mail/Storage/Pop3.php

  1<?php
  2/**
  3 * Zend Framework
  4 *
  5 * LICENSE
  6 *
  7 * This source file is subject to the new BSD license that is bundled
  8 * with this package in the file LICENSE.txt.
  9 * It is also available through the world-wide-web at this URL:
 10 * http://framework.zend.com/license/new-bsd
 11 * If you did not receive a copy of the license and are unable to
 12 * obtain it through the world-wide-web, please send an email
 13 * to license@zend.com so we can send you a copy immediately.
 14 *
 15 * @category   Zend
 16 * @package    Zend_Mail
 17 * @subpackage Storage
 18 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 19 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 20 * @version    $Id: Pop3.php 23775 2011-03-01 17:25:24Z ralph $
 21 */
 22
 23
 24/**
 25 * @see Zend_Mail_Storage_Abstract
 26 */
 27require_once 'Zend/Mail/Storage/Abstract.php';
 28
 29/**
 30 * @see Zend_Mail_Protocol_Pop3
 31 */
 32require_once 'Zend/Mail/Protocol/Pop3.php';
 33
 34/**
 35 * @see Zend_Mail_Message
 36 */
 37require_once 'Zend/Mail/Message.php';
 38
 39
 40/**
 41 * @category   Zend
 42 * @package    Zend_Mail
 43 * @subpackage Storage
 44 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 45 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 46 */
 47class Zend_Mail_Storage_Pop3 extends Zend_Mail_Storage_Abstract
 48{
 49    /**
 50     * protocol handler
 51     * @var null|Zend_Mail_Protocol_Pop3
 52     */
 53    protected $_protocol;
 54
 55
 56    /**
 57     * Count messages all messages in current box
 58     *
 59     * @return int number of messages
 60     * @throws Zend_Mail_Storage_Exception
 61     * @throws Zend_Mail_Protocol_Exception
 62     */
 63    public function countMessages()
 64    {
 65        $this->_protocol->status($count, $null);
 66        return (int)$count;
 67    }
 68
 69    /**
 70     * get a list of messages with number and size
 71     *
 72     * @param int $id number of message
 73     * @return int|array size of given message of list with all messages as array(num => size)
 74     * @throws Zend_Mail_Protocol_Exception
 75     */
 76    public function getSize($id = 0)
 77    {
 78        $id = $id ? $id : null;
 79        return $this->_protocol->getList($id);
 80    }
 81
 82    /**
 83     * Fetch a message
 84     *
 85     * @param int $id number of message
 86     * @return Zend_Mail_Message
 87     * @throws Zend_Mail_Protocol_Exception
 88     */
 89    public function getMessage($id)
 90    {
 91        $bodyLines = 0;
 92        $message = $this->_protocol->top($id, $bodyLines, true);
 93
 94        return new $this->_messageClass(array('handler' => $this, 'id' => $id, 'headers' => $message,
 95                                              'noToplines' => $bodyLines < 1));
 96    }
 97
 98    /*
 99     * Get raw header of message or part
100     *
101     * @param  int               $id       number of message
102     * @param  null|array|string $part     path to part or null for messsage header
103     * @param  int               $topLines include this many lines with header (after an empty line)
104     * @return string raw header
105     * @throws Zend_Mail_Protocol_Exception
106     * @throws Zend_Mail_Storage_Exception
107     */
108    public function getRawHeader($id, $part = null, $topLines = 0)
109    {
110        if ($part !== null) {
111            // TODO: implement
112            /**
113             * @see Zend_Mail_Storage_Exception
114             */
115            require_once 'Zend/Mail/Storage/Exception.php';
116            throw new Zend_Mail_Storage_Exception('not implemented');
117        }
118
119        return $this->_protocol->top($id, 0, true);
120    }
121
122    /*
123     * Get raw content of message or part
124     *
125     * @param  int               $id   number of message
126     * @param  null|array|string $part path to part or null for messsage content
127     * @return string raw content
128     * @throws Zend_Mail_Protocol_Exception
129     * @throws Zend_Mail_Storage_Exception
130     */
131    public function getRawContent($id, $part = null)
132    {
133        if ($part !== null) {
134            // TODO: implement
135            /**
136             * @see Zend_Mail_Storage_Exception
137             */
138            require_once 'Zend/Mail/Storage/Exception.php';
139            throw new Zend_Mail_Storage_Exception('not implemented');
140        }
141
142        $content = $this->_protocol->retrieve($id);
143        // TODO: find a way to avoid decoding the headers
144        Zend_Mime_Decode::splitMessage($content, $null, $body);
145        return $body;
146    }
147
148    /**
149     * create instance with parameters
150     * Supported paramters are
151     *   - host hostname or ip address of POP3 server
152     *   - user username
153     *   - password password for user 'username' [optional, default = '']
154     *   - port port for POP3 server [optional, default = 110]
155     *   - ssl 'SSL' or 'TLS' for secure sockets
156     *
157     * @param array $params mail reader specific parameters
158     * @throws Zend_Mail_Storage_Exception
159     * @throws Zend_Mail_Protocol_Exception
160     */
161    public function __construct($params)
162    {
163        if (is_array($params)) {
164            $params = (object)$params;
165        }
166
167        $this->_has['fetchPart'] = false;
168        $this->_has['top']       = null;
169        $this->_has['uniqueid']  = null;
170
171        if ($params instanceof Zend_Mail_Protocol_Pop3) {
172            $this->_protocol = $params;
173            return;
174        }
175
176        if (!isset($params->user)) {
177            /**
178             * @see Zend_Mail_Storage_Exception
179             */
180            require_once 'Zend/Mail/Storage/Exception.php';
181            throw new Zend_Mail_Storage_Exception('need at least user in params');
182        }
183
184        $host     = isset($params->host)     ? $params->host     : 'localhost';
185        $password = isset($params->password) ? $params->password : '';
186        $port     = isset($params->port)     ? $params->port     : null;
187        $ssl      = isset($params->ssl)      ? $params->ssl      : false;
188
189        $this->_protocol = new Zend_Mail_Protocol_Pop3();
190        $this->_protocol->connect($host, $port, $ssl);
191        $this->_protocol->login($params->user, $password);
192    }
193
194    /**
195     * Close resource for mail lib. If you need to control, when the resource
196     * is closed. Otherwise the destructor would call this.
197     *
198     * @return null
199     */
200    public function close()
201    {
202        $this->_protocol->logout();
203    }
204
205    /**
206     * Keep the server busy.
207     *
208     * @return null
209     * @throws Zend_Mail_Protocol_Exception
210     */
211    public function noop()
212    {
213        return $this->_protocol->noop();
214    }
215
216    /**
217     * Remove a message from server. If you're doing that from a web enviroment
218     * you should be careful and use a uniqueid as parameter if possible to
219     * identify the message.
220     *
221     * @param  int $id number of message
222     * @return null
223     * @throws Zend_Mail_Protocol_Exception
224     */
225    public function removeMessage($id)
226    {
227        $this->_protocol->delete($id);
228    }
229
230    /**
231     * get unique id for one or all messages
232     *
233     * if storage does not support unique ids it's the same as the message number
234     *
235     * @param int|null $id message number
236     * @return array|string message number for given message or all messages as array
237     * @throws Zend_Mail_Storage_Exception
238     */
239    public function getUniqueId($id = null)
240    {
241        if (!$this->hasUniqueid) {
242            if ($id) {
243                return $id;
244            }
245            $count = $this->countMessages();
246            if ($count < 1) {
247                return array();
248            }
249            $range = range(1, $count);
250            return array_combine($range, $range);
251        }
252
253        return $this->_protocol->uniqueid($id);
254    }
255
256    /**
257     * get a message number from a unique id
258     *
259     * I.e. if you have a webmailer that supports deleting messages you should use unique ids
260     * as parameter and use this method to translate it to message number right before calling removeMessage()
261     *
262     * @param string $id unique id
263     * @return int message number
264     * @throws Zend_Mail_Storage_Exception
265     */
266    public function getNumberByUniqueId($id)
267    {
268        if (!$this->hasUniqueid) {
269            return $id;
270        }
271
272        $ids = $this->getUniqueId();
273        foreach ($ids as $k => $v) {
274            if ($v == $id) {
275                return $k;
276            }
277        }
278
279        /**
280         * @see Zend_Mail_Storage_Exception
281         */
282        require_once 'Zend/Mail/Storage/Exception.php';
283        throw new Zend_Mail_Storage_Exception('unique id not found');
284    }
285
286    /**
287     * Special handling for hasTop and hasUniqueid. The headers of the first message is
288     * retrieved if Top wasn't needed/tried yet.
289     *
290     * @see Zend_Mail_Storage_Abstract:__get()
291     * @param  string $var
292     * @return string
293     * @throws Zend_Mail_Storage_Exception
294     */
295    public function __get($var)
296    {
297        $result = parent::__get($var);
298        if ($result !== null) {
299            return $result;
300        }
301
302        if (strtolower($var) == 'hastop') {
303            if ($this->_protocol->hasTop === null) {
304                // need to make a real call, because not all server are honest in their capas
305                try {
306                    $this->_protocol->top(1, 0, false);
307                } catch(Zend_Mail_Exception $e) {
308                    // ignoring error
309                }
310            }
311            $this->_has['top'] = $this->_protocol->hasTop;
312            return $this->_protocol->hasTop;
313        }
314
315        if (strtolower($var) == 'hasuniqueid') {
316            $id = null;
317            try {
318                $id = $this->_protocol->uniqueid(1);
319            } catch(Zend_Mail_Exception $e) {
320                // ignoring error
321            }
322            $this->_has['uniqueid'] = $id ? true : false;
323            return $this->_has['uniqueid'];
324        }
325
326        return $result;
327    }
328}