1<?php
2/**
3 * Copyright 2013-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 2013-2017 Horde LLC
10 * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
11 * @package   Imap_Client
12 */
13
14/**
15 * The abstract backend class for storing IMAP cached data.
16 *
17 * @author    Michael Slusarz <slusarz@horde.org>
18 * @category  Horde
19 * @copyright 2013-2017 Horde LLC
20 * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
21 * @package   Imap_Client
22 */
23abstract class Horde_Imap_Client_Cache_Backend implements Serializable
24{
25    /**
26     * Configuration paramters.
27     * Values set by the base Cache object: hostspec, port, username
28     *
29     * @var array
30     */
31    protected $_params = array();
32
33    /**
34     * Constructor.
35     *
36     * @param array $params  Configuration parameters.
37     */
38    public function __construct(array $params = array())
39    {
40        $this->setParams($params);
41        $this->_initOb();
42    }
43
44    /**
45     * Initialization tasks.
46     */
47    protected function _initOb()
48    {
49    }
50
51    /**
52     * Add configuration parameters.
53     *
54     * @param array $params  Configuration parameters.
55     */
56    public function setParams(array $params = array())
57    {
58        $this->_params = array_merge($this->_params, $params);
59    }
60
61    /**
62     * Get information from the cache for a set of UIDs.
63     *
64     * @param string $mailbox    An IMAP mailbox string.
65     * @param array $uids        The list of message UIDs to retrieve
66     *                           information for.
67     * @param array $fields      An array of fields to retrieve. If empty,
68     *                           returns all cached fields.
69     * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
70     *
71     * @return array  An array of arrays with the UID of the message as the
72     *                key (if found) and the fields as values (will be
73     *                undefined if not found).
74     */
75    abstract public function get($mailbox, $uids, $fields, $uidvalid);
76
77    /**
78     * Get the list of cached UIDs.
79     *
80     * @param string $mailbox    An IMAP mailbox string.
81     * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
82     *
83     * @return array  The (unsorted) list of cached UIDs.
84     */
85    abstract public function getCachedUids($mailbox, $uidvalid);
86
87    /**
88     * Store data in cache.
89     *
90     * @param string $mailbox    An IMAP mailbox string.
91     * @param array $data        The list of data to save. The keys are the
92     *                           UIDs, the values are an array of information
93     *                           to save.
94     * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
95     */
96    abstract public function set($mailbox, $data, $uidvalid);
97
98    /**
99     * Get metadata information for a mailbox.
100     *
101     * @param string $mailbox    An IMAP mailbox string.
102     * @param integer $uidvalid  The IMAP uidvalidity value of the mailbox.
103     * @param array $entries     An array of entries to return. If empty,
104     *                           returns all metadata.
105     *
106     * @return array  The requested metadata. Requested entries that do not
107     *                exist will be undefined. The following entries are
108     *                defaults and always present:
109     *   - uidvalid: (integer) The UIDVALIDITY of the mailbox.
110     */
111    abstract public function getMetaData($mailbox, $uidvalid, $entries);
112
113    /**
114     * Set metadata information for a mailbox.
115     *
116     * @param string $mailbox    An IMAP mailbox string.
117     * @param array $data        The list of data to save. The keys are the
118     *                           metadata IDs, the values are the associated
119     *                           data. (If present, uidvalidity appears as
120     *                           the 'uidvalid' key in $data.)
121     */
122    abstract public function setMetaData($mailbox, $data);
123
124    /**
125     * Delete messages in the cache.
126     *
127     * @param string $mailbox  An IMAP mailbox string.
128     * @param array $uids      The list of message UIDs to delete.
129     */
130    abstract public function deleteMsgs($mailbox, $uids);
131
132    /**
133     * Delete a mailbox from the cache.
134     *
135     * @param string $mailbox  The mailbox to delete.
136     */
137    abstract public function deleteMailbox($mailbox);
138
139    /**
140     * Clear the cache.
141     *
142     * @param integer $lifetime  Only delete entries older than this (in
143     *                           seconds). If null, deletes all entries.
144     */
145    abstract public function clear($lifetime);
146
147
148    /* Serializable methods. */
149
150    /**
151     */
152    public function serialize()
153    {
154        return serialize($this->_params);
155    }
156
157    /**
158     */
159    public function unserialize($data)
160    {
161        $this->_params = unserialize($data);
162        $this->_initOb();
163    }
164
165}
166