[TASK] Deprecation message should be on a single line
[Packages/TYPO3.CMS.git] / t3lib / cache / backend / class.t3lib_cache_backend_dbbackend.php
1 <?php
2 /***************************************************************
3 * Copyright notice
4 *
5 * (c) 2008-2011 Ingo Renner <ingo@typo3.org>
6 * All rights reserved
7 *
8 * This script is part of the TYPO3 project. The TYPO3 project is
9 * free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
13 *
14 * The GNU General Public License can be found at
15 * http://www.gnu.org/copyleft/gpl.html.
16 *
17 * This script is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU General Public License for more details.
21 *
22 * This copyright notice MUST APPEAR in all copies of the script!
23 ***************************************************************/
24
25 /**
26 * A caching backend which stores cache entries in database tables
27 *
28 * @package TYPO3
29 * @subpackage t3lib_cache
30 * @author Christian Kuhn <lolli@schwarzbu.ch>
31 * @author Ingo Renner <ingo@typo3.org>
32 * @api
33 * @scope prototype
34 */
35 class t3lib_cache_backend_DbBackend extends t3lib_cache_backend_AbstractBackend {
36
37 /**
38 * @var integer Timestamp of 2038-01-01)
39 */
40 const FAKED_UNLIMITED_EXPIRE = 2145909600;
41
42 /**
43 * @var string Name of the cache data table
44 */
45 protected $cacheTable;
46
47 /**
48 * @var string Name of the cache tags table
49 */
50 protected $tagsTable;
51
52 /**
53 * @var boolean Indicates wether data is compressed or not (requires php zlib)
54 */
55 protected $compression = FALSE;
56
57 /**
58 * @var integer -1 to 9, indicates zlib compression level: -1 = default level 6, 0 = no compression, 9 maximum compression
59 */
60 protected $compressionLevel = -1;
61
62 /**
63 * @var string Name of the identifier field, 'table_name.identifier'
64 */
65 protected $identifierField;
66
67 /**
68 * @var string Name of the expire field, 'table_name.expires'
69 */
70 protected $expiresField;
71
72 /**
73 * @var integer Maximum lifetime to stay with expire field below FAKED_UNLIMITED_LIFETIME
74 */
75 protected $maximumLifetime;
76
77 /**
78 * @var string SQL where for a not expired entry
79 */
80 protected $notExpiredStatement;
81
82 /**
83 * @var string Opposite of notExpiredStatement
84 */
85 protected $expiredStatement;
86
87 /**
88 * @var string Data and tags table name comma separated
89 */
90 protected $tableList;
91
92 /**
93 * @var string Join condition for data and tags table
94 */
95 protected $tableJoin;
96
97 /**
98 * Set cache frontend instance and calculate data and tags table name
99 *
100 * @param t3lib_cache_frontend_Frontend $cache The frontend for this backend
101 * @return void
102 * @api
103 */
104 public function setCache(t3lib_cache_frontend_Frontend $cache) {
105 parent::setCache($cache);
106
107 $this->cacheTable = 'cachingframework_' . $this->cacheIdentifier;
108 $this->tagsTable = 'cachingframework_' . $this->cacheIdentifier . '_tags';
109 $this->initializeCommonReferences();
110 }
111
112 /**
113 * Initializes common references used in this backend.
114 *
115 * @return void
116 */
117 protected function initializeCommonReferences() {
118 $this->identifierField = $this->cacheTable . '.identifier';
119 $this->expiresField = $this->cacheTable . '.expires';
120 $this->maximumLifetime = self::FAKED_UNLIMITED_EXPIRE - $GLOBALS['EXEC_TIME'];
121 $this->tableList = $this->cacheTable . ', ' . $this->tagsTable;
122 $this->tableJoin = $this->identifierField . ' = ' . $this->tagsTable . '.identifier';
123 $this->expiredStatement = $this->expiresField . ' < ' . $GLOBALS['EXEC_TIME'];
124 $this->notExpiredStatement = $this->expiresField . ' >= ' . $GLOBALS['EXEC_TIME'];
125 }
126
127 /**
128 * Saves data in a cache file.
129 *
130 * @param string An identifier for this specific cache entry
131 * @param string The data to be stored
132 * @param array Tags to associate with this cache entry
133 * @param integer Lifetime of this cache entry in seconds. If NULL is specified, the default lifetime is used. "0" means unlimited liftime.
134 * @return void
135 * @throws t3lib_cache_Exception if no cache frontend has been set.
136 * @throws t3lib_cache_exception_InvalidData if the data to be stored is not a string.
137 */
138 public function set($entryIdentifier, $data, array $tags = array(), $lifetime = NULL) {
139 $this->throwExceptionIfFrontendDoesNotExist();
140
141 if (!is_string($data)) {
142 throw new t3lib_cache_exception_InvalidData(
143 'The specified data is of type "' . gettype($data) . '" but a string is expected.',
144 1236518298
145 );
146 }
147
148 if (is_null($lifetime)) {
149 $lifetime = $this->defaultLifetime;
150 }
151 if ($lifetime === 0 || $lifetime > $this->maximumLifetime) {
152 $lifetime = $this->maximumLifetime;
153 }
154 $expires = $GLOBALS['EXEC_TIME'] + $lifetime;
155
156 $this->remove($entryIdentifier);
157
158 if ($this->compression) {
159 $data = gzcompress($data, $this->compressionLevel);
160 }
161
162 $GLOBALS['TYPO3_DB']->exec_INSERTquery(
163 $this->cacheTable,
164 array(
165 'identifier' => $entryIdentifier,
166 'expires' => $expires,
167 'content' => $data,
168 )
169 );
170
171 if (count($tags)) {
172 $fields = array();
173 $fields[] = 'identifier';
174 $fields[] = 'tag';
175
176 $tagRows = array();
177 foreach ($tags as $tag) {
178 $tagRow = array();
179 $tagRow[] = $entryIdentifier;
180 $tagRow[] = $tag;
181 $tagRows[] = $tagRow;
182 }
183
184 $GLOBALS['TYPO3_DB']->exec_INSERTmultipleRows(
185 $this->tagsTable,
186 $fields,
187 $tagRows
188 );
189 }
190 }
191
192 /**
193 * Loads data from a cache file.
194 *
195 * @param string An identifier which describes the cache entry to load
196 * @return mixed The cache entry's data as a string or FALSE if the cache entry could not be loaded
197 */
198 public function get($entryIdentifier) {
199 $this->throwExceptionIfFrontendDoesNotExist();
200
201 $cacheEntry = FALSE;
202
203 $cacheEntry = $GLOBALS['TYPO3_DB']->exec_SELECTgetSingleRow(
204 'content',
205 $this->cacheTable,
206 'identifier = ' . $GLOBALS['TYPO3_DB']->fullQuoteStr($entryIdentifier, $this->cacheTable) .
207 ' AND ' . $this->notExpiredStatement
208 );
209
210 if (strlen($GLOBALS['TYPO3_DB']->sql_error()) > 0) {
211 $this->flush();
212 }
213
214 if (is_array($cacheEntry)) {
215 $cacheEntry = $cacheEntry['content'];
216 }
217
218 if ($this->compression && strlen($cacheEntry)) {
219 $cacheEntry = gzuncompress($cacheEntry);
220 }
221
222 return $cacheEntry;
223 }
224
225 /**
226 * Checks if a cache entry with the specified identifier exists.
227 *
228 * @param string Specifies the identifier to check for existence
229 * @return boolean TRUE if such an entry exists, FALSE if not
230 */
231 public function has($entryIdentifier) {
232 $this->throwExceptionIfFrontendDoesNotExist();
233
234 $hasEntry = FALSE;
235
236 $cacheEntries = $GLOBALS['TYPO3_DB']->exec_SELECTcountRows(
237 '*',
238 $this->cacheTable,
239 'identifier = ' . $GLOBALS['TYPO3_DB']->fullQuoteStr($entryIdentifier, $this->cacheTable) .
240 ' AND ' . $this->notExpiredStatement
241 );
242 if ($cacheEntries >= 1) {
243 $hasEntry = TRUE;
244 }
245
246 return $hasEntry;
247 }
248
249 /**
250 * Removes all cache entries matching the specified identifier.
251 * Usually this only affects one entry.
252 *
253 * @param string Specifies the cache entry to remove
254 * @return boolean TRUE if (at least) an entry could be removed or FALSE if no entry was found
255 */
256 public function remove($entryIdentifier) {
257 $this->throwExceptionIfFrontendDoesNotExist();
258
259 $entryRemoved = FALSE;
260
261 $res = $GLOBALS['TYPO3_DB']->exec_DELETEquery(
262 $this->cacheTable,
263 'identifier = ' . $GLOBALS['TYPO3_DB']->fullQuoteStr($entryIdentifier, $this->cacheTable)
264 );
265
266 $GLOBALS['TYPO3_DB']->exec_DELETEquery(
267 $this->tagsTable,
268 'identifier = ' . $GLOBALS['TYPO3_DB']->fullQuoteStr($entryIdentifier, $this->tagsTable)
269 );
270
271 if ($GLOBALS['TYPO3_DB']->sql_affected_rows($res) == 1) {
272 $entryRemoved = TRUE;
273 }
274
275 return $entryRemoved;
276 }
277
278 /**
279 * Finds and returns all cache entries which are tagged by the specified tag.
280 *
281 * @param string The tag to search for
282 * @return array An array with identifiers of all matching entries. An empty array if no entries matched
283 */
284 public function findIdentifiersByTag($tag) {
285 $this->throwExceptionIfFrontendDoesNotExist();
286
287 $cacheEntryIdentifiers = array();
288
289 $cacheEntryIdentifierRows = $GLOBALS['TYPO3_DB']->exec_SELECTgetRows(
290 $this->identifierField,
291 $this->tableList,
292 $this->tagsTable . '.tag = ' . $GLOBALS['TYPO3_DB']->fullQuoteStr($tag, $this->tagsTable) .
293 ' AND ' . $this->tableJoin .
294 ' AND ' . $this->notExpiredStatement,
295 $this->identifierField
296 );
297
298 foreach ($cacheEntryIdentifierRows as $cacheEntryIdentifierRow) {
299 $cacheEntryIdentifiers[$cacheEntryIdentifierRow['identifier']] = $cacheEntryIdentifierRow['identifier'];
300 }
301
302 return $cacheEntryIdentifiers;
303 }
304
305 /**
306 * Removes all cache entries of this cache.
307 *
308 * @return void
309 */
310 public function flush() {
311 $this->throwExceptionIfFrontendDoesNotExist();
312
313 $GLOBALS['TYPO3_DB']->exec_TRUNCATEquery($this->cacheTable);
314 $GLOBALS['TYPO3_DB']->exec_TRUNCATEquery($this->tagsTable);
315 $GLOBALS['TYPO3_DB']->admin_query('DROP TABLE IF EXISTS ' . $this->cacheTable);
316 $GLOBALS['TYPO3_DB']->admin_query('DROP TABLE IF EXISTS ' . $this->tagsTable);
317 $this->createCacheTable();
318 $this->createTagsTable();
319 }
320
321 /**
322 * Removes all cache entries of this cache which are tagged by the specified tag.
323 *
324 * @param string The tag the entries must have
325 * @return void
326 */
327 public function flushByTag($tag) {
328 $this->throwExceptionIfFrontendDoesNotExist();
329
330 $tagsTableWhereClause = $this->tagsTable . '.tag = ' . $GLOBALS['TYPO3_DB']->fullQuoteStr($tag, $this->tagsTable);
331
332 $this->deleteCacheTableRowsByTagsTableWhereClause($tagsTableWhereClause);
333
334 $GLOBALS['TYPO3_DB']->exec_DELETEquery(
335 $this->tagsTable,
336 $tagsTableWhereClause
337 );
338 }
339
340 /**
341 * Does garbage collection
342 *
343 * @return void
344 */
345 public function collectGarbage() {
346 $this->throwExceptionIfFrontendDoesNotExist();
347
348 // Get identifiers of expired cache entries
349 $tagsEntryIdentifierRowsResource = $GLOBALS['TYPO3_DB']->exec_SELECTquery(
350 'identifier',
351 $this->cacheTable,
352 $this->expiredStatement
353 );
354
355 $tagsEntryIdentifiers = array();
356 while ($tagsEntryIdentifierRow = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($tagsEntryIdentifierRowsResource)) {
357 $tagsEntryIdentifiers[] = $GLOBALS['TYPO3_DB']->fullQuoteStr(
358 $tagsEntryIdentifierRow['identifier'],
359 $this->tagsTable
360 );
361 }
362 $GLOBALS['TYPO3_DB']->sql_free_result($tagsEntryIdentifierRowsResource);
363
364 // Delete tag rows connected to expired cache entries
365 if (count($tagsEntryIdentifiers)) {
366 $GLOBALS['TYPO3_DB']->exec_DELETEquery(
367 $this->tagsTable,
368 'identifier IN (' . implode(', ', $tagsEntryIdentifiers) . ')'
369 );
370 }
371
372 // Delete expired cache rows
373 $GLOBALS['TYPO3_DB']->exec_DELETEquery(
374 $this->cacheTable,
375 $this->expiredStatement
376 );
377 }
378
379 /**
380 * Sets the table where the cache entries are stored.
381 *
382 * @deprecated since TYPO3 4.6: The backend calculates the table name internally, this method does nothing anymore
383 * @param string $cacheTable Table name
384 * @return void
385 */
386 public function setCacheTable($cacheTable) {
387 t3lib_div::logDeprecatedFunction();
388 }
389
390 /**
391 * Returns the table where the cache entries are stored.
392 *
393 * @return string The cache table.
394 */
395 public function getCacheTable() {
396 $this->throwExceptionIfFrontendDoesNotExist();
397
398 return $this->cacheTable;
399 }
400
401 /**
402 * Sets the table where cache tags are stored.
403 *
404 * @deprecated since TYPO3 4.6: The backend calculates the table name internally, this method does nothing anymore
405 * @param string $tagsTable: Tags table name
406 * @return void
407 */
408 public function setTagsTable($tagsTable) {
409 t3lib_div::logDeprecatedFunction();
410 }
411
412 /**
413 * Gets the table where cache tags are stored.
414 *
415 * @return string Name of the table storing tags
416 */
417 public function getTagsTable() {
418 $this->throwExceptionIfFrontendDoesNotExist();
419
420 return $this->tagsTable;
421 }
422
423 /**
424 * Enable data compression
425 *
426 * @param boolean TRUE to enable compression
427 */
428 public function setCompression($compression) {
429 $this->compression = $compression;
430 }
431
432 /**
433 * Set data compression level.
434 * If compression is enabled and this is not set,
435 * gzcompress default level will be used
436 *
437 * @param integer -1 to 9: Compression level
438 */
439 public function setCompressionLevel($compressionLevel) {
440 if ($compressionLevel >= -1 && $compressionLevel <= 9) {
441 $this->compressionLevel = $compressionLevel;
442 }
443 }
444
445 /**
446 * Check if required frontend instance exists
447 *
448 * @throws t3lib_cache_Exception If there is no frontend instance in $this->cache
449 * @return void
450 */
451 protected function throwExceptionIfFrontendDoesNotExist() {
452 if (!$this->cache instanceof t3lib_cache_frontend_Frontend) {
453 throw new t3lib_cache_Exception(
454 'No cache frontend has been set via setCache() yet.',
455 1236518288
456 );
457 }
458 }
459
460 /**
461 * Create data table of cache
462 *
463 * @return void
464 */
465 protected function createCacheTable() {
466 $sql = file_get_contents(PATH_t3lib . 'cache/backend/resources/dbbackend-layout-cache.sql');
467 $sql = str_replace('###CACHE_TABLE###', $this->cacheTable, $sql);
468 $GLOBALS['TYPO3_DB']->admin_query($sql);
469 }
470
471 /**
472 * Create tags table of cache
473 *
474 * @return void
475 */
476 protected function createTagsTable() {
477 $sql = file_get_contents(PATH_t3lib . 'cache/backend/resources/dbbackend-layout-tags.sql');
478 $sql = str_replace('###TAGS_TABLE###', $this->tagsTable, $sql);
479 $GLOBALS['TYPO3_DB']->admin_query($sql);
480 }
481
482 /**
483 * Deletes rows in cache table found by where clause on tags table
484 *
485 * @param string The where clause for the tags table
486 * @return void
487 */
488 protected function deleteCacheTableRowsByTagsTableWhereClause($tagsTableWhereClause) {
489 $cacheEntryIdentifierRowsRessource = $GLOBALS['TYPO3_DB']->exec_SELECTquery(
490 'DISTINCT identifier',
491 $this->tagsTable,
492 $tagsTableWhereClause
493 );
494
495 $cacheEntryIdentifiers = array();
496 while ($cacheEntryIdentifierRow = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($cacheEntryIdentifierRowsRessource)) {
497 $cacheEntryIdentifiers[] = $GLOBALS['TYPO3_DB']->fullQuoteStr(
498 $cacheEntryIdentifierRow['identifier'],
499 $this->cacheTable
500 );
501 }
502 $GLOBALS['TYPO3_DB']->sql_free_result($cacheEntryIdentifierRowsRessource);
503
504 if (count($cacheEntryIdentifiers)) {
505 $GLOBALS['TYPO3_DB']->exec_DELETEquery(
506 $this->cacheTable,
507 'identifier IN (' . implode(', ', $cacheEntryIdentifiers) . ')'
508 );
509 }
510 }
511 }
512 ?>