interface/modules/zend_modules/library/Zend/Mail/Storage/AbstractStorage.php

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