/framework/vendor/zend/Zend/Mail/Storage/Abstract.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-2010 Zend Technologies USA Inc. (http://www.zend.com)
 19 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 20 * @version    $Id: Abstract.php 20096 2010-01-06 02:05:09Z bkarwin $
 21 */
 22
 23
 24/**
 25 * @category   Zend
 26 * @package    Zend_Mail
 27 * @subpackage Storage
 28 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 29 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 30 */
 31abstract class Zend_Mail_Storage_Abstract implements Countable, ArrayAccess, SeekableIterator
 32{
 33    /**
 34     * class capabilities with default values
 35     * @var array
 36     */
 37    protected $_has = array('uniqueid'  => true,
 38                            'delete'    => false,
 39                            'create'    => false,
 40                            'top'       => false,
 41                            'fetchPart' => true,
 42                            'flags'     => false);
 43
 44    /**
 45     * current iteration position
 46     * @var int
 47     */
 48    protected $_iterationPos = 0;
 49
 50    /**
 51     * maximum iteration position (= message count)
 52     * @var null|int
 53     */
 54    protected $_iterationMax = null;
 55
 56    /**
 57     * used message class, change it in an extened class to extend the returned message class
 58     * @var string
 59     */
 60    protected $_messageClass = 'Zend_Mail_Message';
 61
 62    /**
 63     * Getter for has-properties. The standard has properties
 64     * are: hasFolder, hasUniqueid, hasDelete, hasCreate, hasTop
 65     *
 66     * The valid values for the has-properties are:
 67     *   - true if a feature is supported
 68     *   - false if a feature is not supported
 69     *   - null is it's not yet known or it can't be know if a feature is supported
 70     *
 71     * @param  string $var  property name
 72     * @return bool         supported or not
 73     * @throws Zend_Mail_Storage_Exception
 74     */
 75    public function __get($var)
 76    {
 77        if (strpos($var, 'has') === 0) {
 78            $var = strtolower(substr($var, 3));
 79            return isset($this->_has[$var]) ? $this->_has[$var] : null;
 80        }
 81
 82        /**
 83         * @see Zend_Mail_Storage_Exception
 84         */
 85        require_once 'Zend/Mail/Storage/Exception.php';
 86        throw new Zend_Mail_Storage_Exception($var . ' not found');
 87    }
 88
 89
 90    /**
 91     * Get a full list of features supported by the specific mail lib and the server
 92     *
 93     * @return array list of features as array(featurename => true|false[|null])
 94     */
 95    public function getCapabilities()
 96    {
 97        return $this->_has;
 98    }
 99
100
101    /**
102     * Count messages messages in current box/folder
103     *
104     * @return int number of messages
105     * @throws Zend_Mail_Storage_Exception
106     */
107    abstract public function countMessages();
108
109
110    /**
111     * Get a list of messages with number and size
112     *
113     * @param  int $id  number of message
114     * @return int|array size of given message of list with all messages as array(num => size)
115     */
116    abstract public function getSize($id = 0);
117
118
119    /**
120     * Get a message with headers and body
121     *
122     * @param  $id int number of message
123     * @return Zend_Mail_Message
124     */
125    abstract public function getMessage($id);
126
127
128    /**
129     * Get raw header of message or part
130     *
131     * @param  int               $id       number of message
132     * @param  null|array|string $part     path to part or null for messsage header
133     * @param  int               $topLines include this many lines with header (after an empty line)
134     * @return string raw header
135     */
136    abstract public function getRawHeader($id, $part = null, $topLines = 0);
137
138    /**
139     * Get raw content of message or part
140     *
141     * @param  int               $id   number of message
142     * @param  null|array|string $part path to part or null for messsage content
143     * @return string raw content
144     */
145    abstract public function getRawContent($id, $part = null);
146
147    /**
148     * Create instance with parameters
149     *
150     * @param  array $params mail reader specific parameters
151     * @throws Zend_Mail_Storage_Exception
152     */
153    abstract public function __construct($params);
154
155
156    /**
157     * Destructor calls close() and therefore closes the resource.
158     */
159    public function __destruct()
160    {
161        $this->close();
162    }
163
164
165    /**
166     * Close resource for mail lib. If you need to control, when the resource
167     * is closed. Otherwise the destructor would call this.
168     *
169     * @return null
170     */
171    abstract public function close();
172
173
174    /**
175     * Keep the resource alive.
176     *
177     * @return null
178     */
179    abstract public function noop();
180
181    /**
182     * delete a message from current box/folder
183     *
184     * @return null
185     */
186    abstract public function removeMessage($id);
187
188    /**
189     * get unique id for one or all messages
190     *
191     * if storage does not support unique ids it's the same as the message number
192     *
193     * @param int|null $id message number
194     * @return array|string message number for given message or all messages as array
195     * @throws Zend_Mail_Storage_Exception
196     */
197    abstract public function getUniqueId($id = null);
198
199    /**
200     * get a message number from a unique id
201     *
202     * I.e. if you have a webmailer that supports deleting messages you should use unique ids
203     * as parameter and use this method to translate it to message number right before calling removeMessage()
204     *
205     * @param string $id unique id
206     * @return int message number
207     * @throws Zend_Mail_Storage_Exception
208     */
209    abstract public function getNumberByUniqueId($id);
210
211    // interface implementations follows
212
213    /**
214     * Countable::count()
215     *
216     * @return   int
217     */
218     public function count()
219     {
220        return $this->countMessages();
221     }
222
223
224     /**
225      * ArrayAccess::offsetExists()
226      *
227      * @param    int     $id
228      * @return   boolean
229      */
230     public function offsetExists($id)
231     {
232        try {
233            if ($this->getMessage($id)) {
234                return true;
235            }
236        } catch(Zend_Mail_Storage_Exception $e) {}
237
238        return false;
239     }
240
241
242     /**
243      * ArrayAccess::offsetGet()
244      *
245      * @param    int $id
246      * @return   Zend_Mail_Message message object
247      */
248     public function offsetGet($id)
249     {
250        return $this->getMessage($id);
251     }
252
253
254     /**
255      * ArrayAccess::offsetSet()
256      *
257      * @param    id     $id
258      * @param    mixed  $value
259      * @throws   Zend_Mail_Storage_Exception
260      * @return   void
261      */
262     public function offsetSet($id, $value)
263     {
264        /**
265         * @see Zend_Mail_Storage_Exception
266         */
267        require_once 'Zend/Mail/Storage/Exception.php';
268        throw new Zend_Mail_Storage_Exception('cannot write mail messages via array access');
269     }
270
271
272     /**
273      * ArrayAccess::offsetUnset()
274      *
275      * @param    int   $id
276      * @return   boolean success
277      */
278     public function offsetUnset($id)
279     {
280        return $this->removeMessage($id);
281     }
282
283
284     /**
285      * Iterator::rewind()
286      *
287      * Rewind always gets the new count from the storage. Thus if you use
288      * the interfaces and your scripts take long you should use reset()
289      * from time to time.
290      *
291      * @return   void
292      */
293     public function rewind()
294     {
295        $this->_iterationMax = $this->countMessages();
296        $this->_iterationPos = 1;
297     }
298
299
300     /**
301      * Iterator::current()
302      *
303      * @return   Zend_Mail_Message current message
304      */
305     public function current()
306     {
307        return $this->getMessage($this->_iterationPos);
308     }
309
310
311     /**
312      * Iterator::key()
313      *
314      * @return   int id of current position
315      */
316     public function key()
317     {
318        return $this->_iterationPos;
319     }
320
321
322     /**
323      * Iterator::next()
324      *
325      * @return   void
326      */
327     public function next()
328     {
329        ++$this->_iterationPos;
330     }
331
332
333     /**
334      * Iterator::valid()
335      *
336      * @return   boolean
337      */
338     public function valid()
339     {
340        if ($this->_iterationMax === null) {
341          $this->_iterationMax = $this->countMessages();
342        }
343        return $this->_iterationPos && $this->_iterationPos <= $this->_iterationMax;
344     }
345
346
347     /**
348      * SeekableIterator::seek()
349      *
350      * @param  int $pos
351      * @return void
352      * @throws OutOfBoundsException
353      */
354     public function seek($pos)
355     {
356        if ($this->_iterationMax === null) {
357          $this->_iterationMax = $this->countMessages();
358        }
359
360        if ($pos > $this->_iterationMax) {
361            throw new OutOfBoundsException('this position does not exist');
362        }
363        $this->_iterationPos = $pos;
364     }
365
366}