vendor/zendframework/zend-mail/src/Storage/AbstractStorage.php

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