1: <?php
  2: /**
  3:  * The IMP_Indices class provides functions to handle lists of message
  4:  * indices.
  5:  *
  6:  * Copyright 2010-2012 Horde LLC (http://www.horde.org/)
  7:  *
  8:  * See the enclosed file COPYING for license information (GPL). If you
  9:  * did not receive this file, see http://www.horde.org/licenses/gpl.
 10:  *
 11:  * @author   Michael Slusarz <slusarz@horde.org>
 12:  * @category Horde
 13:  * @license  http://www.horde.org/licenses/gpl GPL
 14:  * @package  IMP
 15:  */
 16: class IMP_Indices implements ArrayAccess, Countable, Iterator
 17: {
 18:     /**
 19:      * Default mailbox name.
 20:      *
 21:      * @var array
 22:      */
 23:     protected $_default = 'INBOX';
 24: 
 25:     /**
 26:      * The indices list.
 27:      *
 28:      * @var array
 29:      */
 30:     protected $_indices = array();
 31: 
 32:     /**
 33:      * Constructor.
 34:      *
 35:      * Parameters are the same as add().
 36:      *
 37:      * @see add()
 38:      */
 39:     public function __construct()
 40:     {
 41:         if (func_num_args()) {
 42:             $args = func_get_args();
 43:             call_user_func_array(array($this, 'add'), $args);
 44:         }
 45:     }
 46: 
 47:     /**
 48:      * Add indices.
 49:      *
 50:      * Input format:
 51:      * <pre>
 52:      * 1 argument:
 53:      * -----------
 54:      * + Array
 55:      *   Either:
 56:      *     KEYS: Mailbox names
 57:      *     VALUES: UIDs -or- Horde_Imap_Client_Ids object
 58:      *  -or-
 59:      *     VALUES: IMAP sequence strings
 60:      * + IMP_Compose object
 61:      * + IMP_Contents object
 62:      * + IMP_Indices object
 63:      * + IMP_Mailbox_List_Track object
 64:      * + String
 65:      *   Format: IMAP sequence string
 66:      *
 67:      * 2 arguments:
 68:      * ------------
 69:      * 1st argument: Mailbox name -or- IMP_Mailbox object
 70:      * 2nd argument: Either a single UID, array of UIDs, or a
 71:      *               Horde_Imap_Client_Ids object.
 72:      * </pre>
 73:      */
 74:     public function add()
 75:     {
 76:         $data = func_get_arg(0);
 77:         $indices = array();
 78: 
 79:         switch (func_num_args()) {
 80:         case 1:
 81:             if (is_array($data)) {
 82:                 foreach ($data as $key => $val) {
 83:                     if (is_array($val)) {
 84:                         $indices[$key] = array_keys(array_flip($val));
 85:                     } elseif ($val instanceof Horde_Imap_Client_Ids) {
 86:                         $this->add($key, $val);
 87:                     } else {
 88:                         $this->add($val);
 89:                     }
 90:                 }
 91:             } elseif (is_string($data)) {
 92:                 $imp_imap = $GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create();
 93:                 $indices = $imp_imap->getUtils()->fromSequenceString($data);
 94:                 if ($imp_imap->pop3) {
 95:                     $indices = array($this->_default => $indices);
 96:                 }
 97:             } elseif ($data instanceof IMP_Compose) {
 98:                 $indices = array(
 99:                     strval($data->getMetadata('mailbox')) => array($data->getMetadata('uid'))
100:                 );
101:             } elseif ($data instanceof IMP_Contents) {
102:                 $indices = array(
103:                     strval($data->getMailbox()) => array($data->getUid())
104:                 );
105:             } elseif ($data instanceof IMP_Indices) {
106:                 $indices = $data->indices();
107:             } elseif ($data instanceof IMP_Mailbox_List_Track) {
108:                 $idx = $data->getIMAPIndex();
109:                 $indices = array(
110:                     strval($idx['mailbox']) => array($idx['uid'])
111:                 );
112:             }
113:             break;
114: 
115:         case 2:
116:             $secondarg = func_get_arg(1);
117:             if (is_array($secondarg)) {
118:                 $secondarg = array_keys(array_flip($secondarg));
119:             } elseif ($secondarg instanceof Horde_Imap_Client_Ids) {
120:                 $secondarg = $secondarg->ids;
121:             } else {
122:                 $secondarg = array($secondarg);
123:             }
124: 
125:             if (!empty($secondarg)) {
126:                 $indices = array(
127:                     strval(func_get_arg(0)) => $secondarg
128:                 );
129:             }
130:             break;
131:         }
132: 
133:         if (!empty($indices)) {
134:             if (empty($this->_indices)) {
135:                 $this->_indices = $indices;
136:             } else {
137:                 /* Can't use array_merge_recursive() here because keys may
138:                  * be numeric mailbox names (e.g. 123), and these keys are
139:                  * treated as numeric (not strings) when merging. */
140:                 foreach (array_keys($indices) as $key) {
141:                     $this->_indices[$key] = isset($this->_indices[$key])
142:                         ? array_merge($this->_indices[$key], $indices[$key])
143:                         : $indices[$key];
144:                 }
145:             }
146:         }
147:     }
148: 
149:     /**
150:      * Returns mailbox/UID information for the first index.
151:      *
152:      * @return boolean $all  If true, returns all UIDs for the first index
153:      *                       in an array. If false, returns the first UID for
154:      *                       the first index as a string.
155:      *
156:      * @return array  A 2-element array with an IMP_Mailbox object and the
157:      *                UID(s).
158:      */
159:     public function getSingle($all = false)
160:     {
161:         $val = reset($this->_indices);
162:         return array(
163:             IMP_Mailbox::get(key($this->_indices)),
164:             $all ? $val : (is_array($val) ? reset($val) : null)
165:         );
166:     }
167: 
168:     /**
169:      * Return a copy of the indices array.
170:      *
171:      * @return array  The indices array (keys are mailbox names, values are
172:      *                arrays of UIDs).
173:      */
174:     public function indices()
175:     {
176:         return $this->_indices;
177:     }
178: 
179:     /**
180:      * Converts an indices object string to a string form representation.
181:      * Needed because null characters (used for various internal non-IMAP
182:      * mailbox representations) will not work in form elements.
183:      *
184:      * @return string  String representation (IMAP sequence string).
185:      */
186:     public function formTo()
187:     {
188:         $converted = array();
189:         foreach ($this->_indices as $key => $val) {
190:             $converted[IMP_Mailbox::formTo($key)] = $val;
191:         }
192: 
193:         return $GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create()->getUtils()->toSequenceString($converted, array('mailbox' => true));
194:     }
195: 
196:     /* ArrayAccess methods. */
197: 
198:     /**
199:      */
200:     public function offsetExists($offset)
201:     {
202:         return isset($this->_indices[$offset]);
203:     }
204: 
205:     /**
206:      */
207:     public function offsetGet($offset)
208:     {
209:         return isset($this->_indices[$offset])
210:             ? $this->_indices[$offset]
211:             : null;
212:     }
213: 
214:     /**
215:      */
216:     public function offsetSet($offset, $value)
217:     {
218:         unset($this->_indices[$offset]);
219:         $this->add($offset, $value);
220:     }
221: 
222:     /**
223:      */
224:     public function offsetUnset($offset)
225:     {
226:         unset($this->_indices[$offset]);
227:     }
228: 
229:     /* Countable methods. */
230: 
231:     /**
232:      * Index count.
233:      *
234:      * @return integer  The number of indices.
235:      */
236:     public function count()
237:     {
238:         $count = 0;
239: 
240:         foreach (array_keys($this->_indices) as $key) {
241:             $count += count($this->_indices[$key]);
242:         }
243: 
244:         return $count;
245:     }
246: 
247:     /* Magic methods. */
248: 
249:     /**
250:      * String representation of the object.
251:      *
252:      * @return string  String representation (IMAP sequence string).
253:      */
254:     public function __toString()
255:     {
256:         return $GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create()->getUtils()->toSequenceString($this->_indices, array('mailbox' => true));
257:     }
258: 
259:     /* Iterator methods. */
260: 
261:     public function current()
262:     {
263:         if (!$this->valid()) {
264:             return null;
265:         }
266: 
267:         $ret = new stdClass;
268:         $ret->mbox = IMP_Mailbox::get($this->key());
269:         $ret->uids = current($this->_indices);
270: 
271:         return $ret;
272:     }
273: 
274:     public function key()
275:     {
276:         return key($this->_indices);
277:     }
278: 
279:     public function next()
280:     {
281:         if ($this->valid()) {
282:             next($this->_indices);
283:         }
284:     }
285: 
286:     public function rewind()
287:     {
288:         reset($this->_indices);
289:     }
290: 
291:     public function valid()
292:     {
293:         return !is_null(key($this->_indices));
294:     }
295: 
296: }
297: