xref: /dokuwiki/inc/cache.php (revision 93691af57f65173963a122e19915917814a32b71) 
1<?php
2/**
3 * Generic class to handle caching
4 *
5 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
6 * @author     Chris Smith <chris@jalakai.co.uk>
7 */
8
9if(!defined('DOKU_INC')) die('meh.');
10
11/**
12 * Generic handling of caching
13 */
14class cache {
15    public $key = '';          // primary identifier for this item
16    public $ext = '';          // file ext for cache data, secondary identifier for this item
17    public $cache = '';        // cache file name
18    public $depends = array(); // array containing cache dependency information,
19                               //   used by _useCache to determine cache validity
20
21    var $_event = '';       // event to be triggered during useCache
22    var $_time;
23    var $_nocache = false;  // if set to true, cache will not be used or stored
24
25    /**
26     * @param string $key primary identifier
27     * @param string $ext file extension
28     */
29    public function cache($key,$ext) {
30        $this->key = $key;
31        $this->ext = $ext;
32        $this->cache = getCacheName($key,$ext);
33    }
34
35    /**
36     * public method to determine whether the cache can be used
37     *
38     * to assist in centralisation of event triggering and calculation of cache statistics,
39     * don't override this function override _useCache()
40     *
41     * @param  array   $depends   array of cache dependencies, support dependecies:
42     *                            'age'   => max age of the cache in seconds
43     *                            'files' => cache must be younger than mtime of each file
44     *                                       (nb. dependency passes if file doesn't exist)
45     *
46     * @return bool    true if cache can be used, false otherwise
47     */
48    public function useCache($depends=array()) {
49        $this->depends = $depends;
50        $this->_addDependencies();
51
52        if ($this->_event) {
53            return $this->_stats(trigger_event($this->_event,$this,array($this,'_useCache')));
54        } else {
55            return $this->_stats($this->_useCache());
56        }
57    }
58
59    /**
60     * private method containing cache use decision logic
61     *
62     * this function processes the following keys in the depends array
63     *   purge - force a purge on any non empty value
64     *   age   - expire cache if older than age (seconds)
65     *   files - expire cache if any file in this array was updated more recently than the cache
66     *
67     * Note that this function needs to be public as it is used as callback for the event handler
68     *
69     * can be overridden
70     *
71     * @return bool               see useCache()
72     */
73    public function _useCache() {
74
75        if ($this->_nocache) return false;                              // caching turned off
76        if (!empty($this->depends['purge'])) return false;              // purge requested?
77        if (!($this->_time = @filemtime($this->cache))) return false;   // cache exists?
78
79        // cache too old?
80        if (!empty($this->depends['age']) && ((time() - $this->_time) > $this->depends['age'])) return false;
81
82        if (!empty($this->depends['files'])) {
83            foreach ($this->depends['files'] as $file) {
84                if ($this->_time <= @filemtime($file)) return false;         // cache older than files it depends on?
85            }
86        }
87
88        return true;
89    }
90
91    /**
92     * add dependencies to the depends array
93     *
94     * this method should only add dependencies,
95     * it should not remove any existing dependencies and
96     * it should only overwrite a dependency when the new value is more stringent than the old
97     */
98    protected function _addDependencies() {
99        global $INPUT;
100        if ($INPUT->has('purge')) $this->depends['purge'] = true;   // purge requested
101    }
102
103    /**
104     * retrieve the cached data
105     *
106     * @param   bool   $clean   true to clean line endings, false to leave line endings alone
107     * @return  string          cache contents
108     */
109    public function retrieveCache($clean=true) {
110        return io_readFile($this->cache, $clean);
111    }
112
113    /**
114     * cache $data
115     *
116     * @param   string $data   the data to be cached
117     * @return  bool           true on success, false otherwise
118     */
119    public function storeCache($data) {
120        if ($this->_nocache) return false;
121
122        return io_savefile($this->cache, $data);
123    }
124
125    /**
126     * remove any cached data associated with this cache instance
127     */
128    public function removeCache() {
129        @unlink($this->cache);
130    }
131
132    /**
133     * Record cache hits statistics.
134     * (Only when debugging allowed, to reduce overhead.)
135     *
136     * @param    bool   $success   result of this cache use attempt
137     * @return   bool              pass-thru $success value
138     */
139    protected function _stats($success) {
140        global $conf;
141        static $stats = null;
142        static $file;
143
144        if (!$conf['allowdebug']) { return $success; }
145
146        if (is_null($stats)) {
147            $file = $conf['cachedir'].'/cache_stats.txt';
148            $lines = explode("\n",io_readFile($file));
149
150            foreach ($lines as $line) {
151                $i = strpos($line,',');
152                $stats[substr($line,0,$i)] = $line;
153            }
154        }
155
156        if (isset($stats[$this->ext])) {
157            list($ext,$count,$hits) = explode(',',$stats[$this->ext]);
158        } else {
159            $ext = $this->ext;
160            $count = 0;
161            $hits = 0;
162        }
163
164        $count++;
165        if ($success) $hits++;
166        $stats[$this->ext] = "$ext,$count,$hits";
167
168        io_saveFile($file,join("\n",$stats));
169
170        return $success;
171    }
172}
173
174/**
175 * Parser caching
176 */
177class cache_parser extends cache {
178
179    public $file = '';       // source file for cache
180    public $mode = '';       // input mode (represents the processing the input file will undergo)
181
182    var $_event = 'PARSER_CACHE_USE';
183
184    /**
185     *
186     * @param string $id page id
187     * @param string $file source file for cache
188     * @param string $mode input mode
189     */
190    public function cache_parser($id, $file, $mode) {
191        if ($id) $this->page = $id;
192        $this->file = $file;
193        $this->mode = $mode;
194
195        parent::cache($file.$_SERVER['HTTP_HOST'].$_SERVER['SERVER_PORT'],'.'.$mode);
196    }
197
198    /**
199     * method contains cache use decision logic
200     *
201     * @return bool               see useCache()
202     */
203    public function _useCache() {
204
205        if (!@file_exists($this->file)) return false;                   // source exists?
206        return parent::_useCache();
207    }
208
209    protected function _addDependencies() {
210
211        // parser cache file dependencies ...
212        $files = array($this->file,                              // ... source
213                DOKU_INC.'inc/parser/parser.php',                // ... parser
214                DOKU_INC.'inc/parser/handler.php',               // ... handler
215                );
216        $files = array_merge($files, getConfigFiles('main'));    // ... wiki settings
217
218        $this->depends['files'] = !empty($this->depends['files']) ? array_merge($files, $this->depends['files']) : $files;
219        parent::_addDependencies();
220    }
221
222}
223
224/**
225 * Caching of data of renderer
226 */
227class cache_renderer extends cache_parser {
228
229    /**
230     * method contains cache use decision logic
231     *
232     * @return bool               see useCache()
233     */
234    public function _useCache() {
235        global $conf;
236
237        if (!parent::_useCache()) return false;
238
239        if (!isset($this->page)) {
240            return true;
241        }
242
243        if ($this->_time < @filemtime(metaFN($this->page,'.meta'))) return false;         // meta cache older than file it depends on?
244
245        // check current link existence is consistent with cache version
246        // first check the purgefile
247        // - if the cache is more recent than the purgefile we know no links can have been updated
248        if ($this->_time >= @filemtime($conf['cachedir'].'/purgefile')) {
249            return true;
250        }
251
252        // for wiki pages, check metadata dependencies
253        $metadata = p_get_metadata($this->page);
254
255        if (!isset($metadata['relation']['references']) ||
256                empty($metadata['relation']['references'])) {
257            return true;
258        }
259
260        foreach ($metadata['relation']['references'] as $id => $exists) {
261            if ($exists != page_exists($id,'',false)) return false;
262        }
263
264        return true;
265    }
266
267    protected function _addDependencies() {
268        global $conf;
269
270        // default renderer cache file 'age' is dependent on 'cachetime' setting, two special values:
271        //    -1 : do not cache (should not be overridden)
272        //    0  : cache never expires (can be overridden) - no need to set depends['age']
273        if ($conf['cachetime'] == -1) {
274            $this->_nocache = true;
275            return;
276        } elseif ($conf['cachetime'] > 0) {
277            $this->depends['age'] = isset($this->depends['age']) ?
278                min($this->depends['age'],$conf['cachetime']) : $conf['cachetime'];
279        }
280
281        // renderer cache file dependencies ...
282        $files = array(
283                DOKU_INC.'inc/parser/'.$this->mode.'.php',       // ... the renderer
284                );
285
286        // page implies metadata and possibly some other dependencies
287        if (isset($this->page)) {
288
289            $valid = p_get_metadata($this->page, 'date valid');         // for xhtml this will render the metadata if needed
290            if (!empty($valid['age'])) {
291                $this->depends['age'] = isset($this->depends['age']) ?
292                    min($this->depends['age'],$valid['age']) : $valid['age'];
293            }
294        }
295
296        $this->depends['files'] = !empty($this->depends['files']) ? array_merge($files, $this->depends['files']) : $files;
297        parent::_addDependencies();
298    }
299}
300
301/**
302 * Caching of parser instructions
303 */
304class cache_instructions extends cache_parser {
305
306    /**
307     * @param string $id page id
308     * @param string $file source file for cache
309     */
310    public function cache_instructions($id, $file) {
311        parent::cache_parser($id, $file, 'i');
312    }
313
314    /**
315     * retrieve the cached data
316     *
317     * @param   bool   $clean   true to clean line endings, false to leave line endings alone
318     * @return  string          cache contents
319     */
320    public function retrieveCache($clean=true) {
321        $contents = io_readFile($this->cache, false);
322        return !empty($contents) ? unserialize($contents) : array();
323    }
324
325    /**
326     * cache $instructions
327     *
328     * @param   string $instructions  the instruction to be cached
329     * @return  bool                  true on success, false otherwise
330     */
331    public function storeCache($instructions) {
332        if ($this->_nocache) return false;
333
334        return io_savefile($this->cache,serialize($instructions));
335    }
336}
337