1<?php
2
3/**
4 * Abstract class representing Definition cache managers that implements
5 * useful common methods and is a factory.
6 * @todo Create a separate maintenance file advanced users can use to
7 *       cache their custom HTMLDefinition, which can be loaded
8 *       via a configuration directive
9 * @todo Implement memcached
10 */
11abstract class HTMLPurifier_DefinitionCache
12{
13    /**
14     * @type string
15     */
16    public $type;
17
18    /**
19     * @param string $type Type of definition objects this instance of the
20     *      cache will handle.
21     */
22    public function __construct($type)
23    {
24        $this->type = $type;
25    }
26
27    /**
28     * Generates a unique identifier for a particular configuration
29     * @param HTMLPurifier_Config $config Instance of HTMLPurifier_Config
30     * @return string
31     */
32    public function generateKey($config)
33    {
34        return $config->version . ',' . // possibly replace with function calls
35               $config->getBatchSerial($this->type) . ',' .
36               $config->get($this->type . '.DefinitionRev');
37    }
38
39    /**
40     * Tests whether or not a key is old with respect to the configuration's
41     * version and revision number.
42     * @param string $key Key to test
43     * @param HTMLPurifier_Config $config Instance of HTMLPurifier_Config to test against
44     * @return bool
45     */
46    public function isOld($key, $config)
47    {
48        if (substr_count($key, ',') < 2) {
49            return true;
50        }
51        list($version, $hash, $revision) = explode(',', $key, 3);
52        $compare = version_compare($version, $config->version);
53        // version mismatch, is always old
54        if ($compare != 0) {
55            return true;
56        }
57        // versions match, ids match, check revision number
58        if ($hash == $config->getBatchSerial($this->type) &&
59            $revision < $config->get($this->type . '.DefinitionRev')) {
60            return true;
61        }
62        return false;
63    }
64
65    /**
66     * Checks if a definition's type jives with the cache's type
67     * @note Throws an error on failure
68     * @param HTMLPurifier_Definition $def Definition object to check
69     * @return bool true if good, false if not
70     */
71    public function checkDefType($def)
72    {
73        if ($def->type !== $this->type) {
74            trigger_error("Cannot use definition of type {$def->type} in cache for {$this->type}");
75            return false;
76        }
77        return true;
78    }
79
80    /**
81     * Adds a definition object to the cache
82     * @param HTMLPurifier_Definition $def
83     * @param HTMLPurifier_Config $config
84     */
85    abstract public function add($def, $config);
86
87    /**
88     * Unconditionally saves a definition object to the cache
89     * @param HTMLPurifier_Definition $def
90     * @param HTMLPurifier_Config $config
91     */
92    abstract public function set($def, $config);
93
94    /**
95     * Replace an object in the cache
96     * @param HTMLPurifier_Definition $def
97     * @param HTMLPurifier_Config $config
98     */
99    abstract public function replace($def, $config);
100
101    /**
102     * Retrieves a definition object from the cache
103     * @param HTMLPurifier_Config $config
104     */
105    abstract public function get($config);
106
107    /**
108     * Removes a definition object to the cache
109     * @param HTMLPurifier_Config $config
110     */
111    abstract public function remove($config);
112
113    /**
114     * Clears all objects from cache
115     * @param HTMLPurifier_Config $config
116     */
117    abstract public function flush($config);
118
119    /**
120     * Clears all expired (older version or revision) objects from cache
121     * @note Be careful implementing this method as flush. Flush must
122     *       not interfere with other Definition types, and cleanup()
123     *       should not be repeatedly called by userland code.
124     * @param HTMLPurifier_Config $config
125     */
126    abstract public function cleanup($config);
127}
128
129// vim: et sw=4 sts=4
130