[Summary view]

   1  <?php
   2  /**
   3   * Copyright 2005-2017 Horde LLC (http://www.horde.org/)
   4   *
   5   * See the enclosed file LICENSE for license information (LGPL). If you
   6   * did not receive this file, see http://www.horde.org/licenses/lgpl21.
   7   *
   8   * @category  Horde
   9   * @copyright 2005-2017 Horde LLC
  10   * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
  11   * @package   Imap_Client
  12   */
  13  
  14  /**
  15   * An interface to cache data retrieved from the IMAP server.
  16   *
  17   * @author    Michael Slusarz <slusarz@horde.org>
  18   * @category  Horde
  19   * @copyright 2005-2017 Horde LLC
  20   * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
  21   * @package   Imap_Client
  22   */
  23  class Horde_Imap_Client_Cache
  24  {
  25      /**
  26       * Base client object.
  27       *
  28       * @var Horde_Imap_Client_Base
  29       */
  30      protected $_baseob;
  31  
  32      /**
  33       * Storage backend.
  34       *
  35       * @var Horde_Imap_Client_Cache_Backend
  36       */
  37      protected $_backend;
  38  
  39      /**
  40       * Debug output.
  41       *
  42       * @var Horde_Imap_Client_Base_Debug
  43       */
  44      protected $_debug = false;
  45  
  46      /**
  47       * The configuration params.
  48       *
  49       * @var array
  50       */
  51      protected $_params = array();
  52  
  53      /**
  54       * Constructor.
  55       *
  56       * @param array $params  Configuration parameters:
  57       * <pre>
  58       *   - REQUIRED Parameters:
  59       *     - backend: (Horde_Imap_Client_Cache_Backend) The cache backend.
  60       *     - baseob: (Horde_Imap_Client_Base) The base client object.
  61       *
  62       *   - Optional Parameters:
  63       *     - debug: (Horde_Imap_Client_Base_Debug) Debug object.
  64       *              DEFAULT: No debug output
  65       * </pre>
  66       */
  67      public function __construct(array $params = array())
  68      {
  69          $this->_backend = $params['backend'];
  70          $this->_baseob = $params['baseob'];
  71  
  72          $this->_backend->setParams(array(
  73              'hostspec' => $this->_baseob->getParam('hostspec'),
  74              'port' => $this->_baseob->getParam('port'),
  75              'username' => $this->_baseob->getParam('username')
  76          ));
  77  
  78          if (isset($params['debug']) &&
  79              ($params['debug'] instanceof Horde_Imap_Client_Base_Debug)) {
  80              $this->_debug = $params['debug'];
  81              $this->_debug->info(sprintf(
  82                  'CACHE: Using the %s storage driver.',
  83                  get_class($this->_backend)
  84              ));
  85          }
  86      }
  87  
  88      /**
  89       * Get information from the cache.
  90       *
  91       * @param string $mailbox    An IMAP mailbox string.
  92       * @param array $uids        The list of message UIDs to retrieve
  93       *                           information for. If empty, returns the list
  94       *                           of cached UIDs.
  95       * @param array $fields      An array of fields to retrieve. If empty,
  96       *                           returns all cached fields.
  97       * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
  98       *
  99       * @return array  An array of arrays with the UID of the message as the
 100       *                key (if found) and the fields as values (will be
 101       *                undefined if not found). If $uids is empty, returns the
 102       *                full (unsorted) list of cached UIDs.
 103       */
 104      public function get($mailbox, array $uids = array(), $fields = array(),
 105                          $uidvalid = null)
 106      {
 107          $mailbox = strval($mailbox);
 108  
 109          if (empty($uids)) {
 110              $ret = $this->_backend->getCachedUids($mailbox, $uidvalid);
 111          } else {
 112              $ret = $this->_backend->get($mailbox, $uids, $fields, $uidvalid);
 113  
 114              if ($this->_debug && !empty($ret)) {
 115                  $this->_debug->info(sprintf(
 116                      'CACHE: Retrieved messages (%s [%s; %s])',
 117                      empty($fields) ? 'ALL' : implode(',', $fields),
 118                      $mailbox,
 119                      $this->_baseob->getIdsOb(array_keys($ret))->tostring_sort
 120                  ));
 121              }
 122          }
 123  
 124          return $ret;
 125      }
 126  
 127      /**
 128       * Store information in cache.
 129       *
 130       * @param string $mailbox    An IMAP mailbox string.
 131       * @param array $data        The list of data to save. The keys are the
 132       *                           UIDs, the values are an array of information
 133       *                           to save. If empty, do a check to make sure
 134       *                           the uidvalidity is still valid.
 135       * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
 136       */
 137      public function set($mailbox, $data, $uidvalid)
 138      {
 139          $mailbox = strval($mailbox);
 140  
 141          if (empty($data)) {
 142              $this->_backend->getMetaData($mailbox, $uidvalid, array('uidvalid'));
 143          } else {
 144              $this->_backend->set($mailbox, $data, $uidvalid);
 145  
 146              if ($this->_debug) {
 147                  $this->_debug->info(sprintf(
 148                      'CACHE: Stored messages [%s; %s]',
 149                      $mailbox,
 150                      $this->_baseob->getIdsOb(array_keys($data))->tostring_sort
 151                  ));
 152              }
 153          }
 154      }
 155  
 156      /**
 157       * Get metadata information for a mailbox.
 158       *
 159       * @param string $mailbox    An IMAP mailbox string.
 160       * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
 161       * @param array $entries     An array of entries to return. If empty,
 162       *                           returns all metadata.
 163       *
 164       * @return array  The requested metadata. Requested entries that do not
 165       *                exist will be undefined. The following entries are
 166       *                defaults and always present:
 167       *   - uidvalid: (integer) The UIDVALIDITY of the mailbox.
 168       */
 169      public function getMetaData($mailbox, $uidvalid = null,
 170                                  array $entries = array())
 171      {
 172          return $this->_backend->getMetaData(strval($mailbox), $uidvalid, $entries);
 173      }
 174  
 175      /**
 176       * Set metadata information for a mailbox.
 177       *
 178       * @param string $mailbox    An IMAP mailbox string.
 179       * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
 180       * @param array $data        The list of data to save. The keys are the
 181       *                           metadata IDs, the values are the associated
 182       *                           data. The following labels are reserved:
 183       *                           'uidvalid'.
 184       */
 185      public function setMetaData($mailbox, $uidvalid, array $data = array())
 186      {
 187          unset($data['uidvalid']);
 188  
 189          if (!empty($data)) {
 190              if (!empty($uidvalid)) {
 191                  $data['uidvalid'] = $uidvalid;
 192              }
 193              $mailbox = strval($mailbox);
 194  
 195              $this->_backend->setMetaData($mailbox, $data);
 196  
 197              if ($this->_debug) {
 198                  $this->_debug->info(sprintf(
 199                      'CACHE: Stored metadata (%s [%s])',
 200                      implode(',', array_keys($data)),
 201                      $mailbox
 202                  ));
 203              }
 204          }
 205      }
 206  
 207      /**
 208       * Delete messages in the cache.
 209       *
 210       * @param string $mailbox  An IMAP mailbox string.
 211       * @param array $uids      The list of message UIDs to delete.
 212       */
 213      public function deleteMsgs($mailbox, $uids)
 214      {
 215          if (empty($uids)) {
 216              return;
 217          }
 218  
 219          $mailbox = strval($mailbox);
 220  
 221          $this->_backend->deleteMsgs($mailbox, $uids);
 222  
 223          if ($this->_debug) {
 224              $this->_debug->info(sprintf(
 225                  'CACHE: Deleted messages [%s; %s]',
 226                  $mailbox,
 227                  $this->_baseob->getIdsOb($uids)->tostring_sort
 228              ));
 229          }
 230      }
 231  
 232      /**
 233       * Delete a mailbox from the cache.
 234       *
 235       * @param string $mbox  The mailbox to delete.
 236       */
 237      public function deleteMailbox($mbox)
 238      {
 239          $mbox = strval($mbox);
 240          $this->_backend->deleteMailbox($mbox);
 241  
 242          if ($this->_debug) {
 243              $this->_debug->info(sprintf(
 244                  'CACHE: Deleted mailbox [%s]',
 245                  $mbox
 246              ));
 247          }
 248      }
 249  
 250      /**
 251       * Clear the cache.
 252       *
 253       * @since 2.9.0
 254       *
 255       * @param integer $lifetime  Only delete entries older than this (in
 256       *                           seconds). If null, deletes all entries.
 257       */
 258      public function clear($lifetime = null)
 259      {
 260          $this->_backend->clear($lifetime);
 261      }
 262  
 263  }