1<?php
2
3namespace Doctrine\Common\Cache;
4
5/**
6 * Interface for cache drivers.
7 *
8 * @link   www.doctrine-project.org
9 */
10interface Cache
11{
12    public const STATS_HITS             = 'hits';
13    public const STATS_MISSES           = 'misses';
14    public const STATS_UPTIME           = 'uptime';
15    public const STATS_MEMORY_USAGE     = 'memory_usage';
16    public const STATS_MEMORY_AVAILABLE = 'memory_available';
17    /**
18     * Only for backward compatibility (may be removed in next major release)
19     *
20     * @deprecated
21     */
22    public const STATS_MEMORY_AVAILIABLE = 'memory_available';
23
24    /**
25     * Fetches an entry from the cache.
26     *
27     * @param string $id The id of the cache entry to fetch.
28     *
29     * @return mixed The cached data or FALSE, if no cache entry exists for the given id.
30     */
31    public function fetch($id);
32
33    /**
34     * Tests if an entry exists in the cache.
35     *
36     * @param string $id The cache id of the entry to check for.
37     *
38     * @return bool TRUE if a cache entry exists for the given cache id, FALSE otherwise.
39     */
40    public function contains($id);
41
42    /**
43     * Puts data into the cache.
44     *
45     * If a cache entry with the given id already exists, its data will be replaced.
46     *
47     * @param string $id       The cache id.
48     * @param mixed  $data     The cache entry/data.
49     * @param int    $lifeTime The lifetime in number of seconds for this cache entry.
50     *                         If zero (the default), the entry never expires (although it may be deleted from the cache
51     *                         to make place for other entries).
52     *
53     * @return bool TRUE if the entry was successfully stored in the cache, FALSE otherwise.
54     */
55    public function save($id, $data, $lifeTime = 0);
56
57    /**
58     * Deletes a cache entry.
59     *
60     * @param string $id The cache id.
61     *
62     * @return bool TRUE if the cache entry was successfully deleted, FALSE otherwise.
63     *              Deleting a non-existing entry is considered successful.
64     */
65    public function delete($id);
66
67    /**
68     * Retrieves cached information from the data store.
69     *
70     * The server's statistics array has the following values:
71     *
72     * - <b>hits</b>
73     * Number of keys that have been requested and found present.
74     *
75     * - <b>misses</b>
76     * Number of items that have been requested and not found.
77     *
78     * - <b>uptime</b>
79     * Time that the server is running.
80     *
81     * - <b>memory_usage</b>
82     * Memory used by this server to store items.
83     *
84     * - <b>memory_available</b>
85     * Memory allowed to use for storage.
86     *
87     * @return array|null An associative array with server's statistics if available, NULL otherwise.
88     */
89    public function getStats();
90}
91