Cache

The cache system provides an API for caching frequently used data, it provides an interface for user code to cache data and an interface for the DBAL to cache query results.

Interface

Name	Description	Parameters			Return		Signature
		Name	Type	Description	Type	Description
Data manipulation
acm::get()	Retrieve a cached data object, returns false on failure.	$var_name	string	Variable name	mixed	False if the entry does not exist, otherwise the cached data	function get($var_name)
acm::put()	Store a data object in the cache with an optional time-to-live.	$var_name	string	Variable name	void		function put($var_name, $var, $ttl)
		$var	mixed	Data to store
		$ttl	integer	Time-to-live (optional)
acm::destroy()	Remove a stored object from the cache.	$var_name	string	Variable name	void		function destroy($var_name, $table = '')
		$table	mixed	String containing a single table or an array of tables, $var_name must be 'sql'.
Utility methods
acm::tidy()	Perform garbage collection on the cache, removing expired data objects.				void		function tidy()
acm::purge()	Empty the cache of all data. Note: this method should also clean the template cache.				void		function purge()
acm::save()	Commit in memory data to the cache back end.				void		function save()
System Methods
acm::load()	Loads the global cache from the backend.				void		function load()
acm::unload()	Shuts down the cache backend, saving and then freeing all resources.				void		function unload()
DBAL Interface
acm::sql_load()	Loads the passed query from the cache.	$query	string	Query to load from cache	mixed	Integer of query identifier on success, otherwise false.	function sql_load($query)
acm::sql_save()	Stores all result rows of the specified query in the cache.	$query	string	Query to save to the cache	void		function sql_save($query, &$query_result, $ttl)
		$query_result	mixed	Database result resource passed in, changed to a query identifier integer on successful save.
		$ttl	integer	Time-to-live
acm::sql_exists()	Test if the query represented by the identifier is stored in the cache.	$query_id	integer	Query identifier	boolean	True if the query specified by the identifier is cached, otherwise false	function sql_exists($query_id)
acm::sql_fetchrow()	Fetches the current row from the specified query result set, increments the row pointer.	$query_id	integer	Query identifier	mixed	Array containing row data or false on failure	function sql_fetchrow($query_id)
acm::sql_fetchfield()	Fetches a single field from the current row of the cached result set.	$query_id	integer	Query identifier	mixed	Array containing row data or false on failure	function sql_fetchfield($query_id, $field)
		$field	string
acm::sql_rowseek()	Seeks to the specified position in the query result set.	$rownum	integer	Row number to seek to	boolean	True on successful seek, otherwise false	function sql_rowseek($rownum, $query_id)
		$query_id	integer	Query identifier
acm::sql_freeresult()	Free the query result and associated data from memory	$query_id	integer	Query identifier	boolean	True if the result was successfully freed, otherwise false	function sql_freeresult($query_id)

Modules

Module	Description	Version	File
File	Utilises disk drive for data storage	>= 3.0.0	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/file.php
XCache [1]	Storage of data in shared memory	>= 3.0.6	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/xcache.php
APC [2]	Storage of data in shared memory	>= 3.0.6	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/apc.php
APCu [3]	Storage of data in shared memory	>= 3.2.1	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/apcu.php
eAccelerator [4]	Storage of data in shared memory	>= 3.0.6	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/eaccelerator.php
Memcache [5]	Uses a memcached instance to store data	>= 3.0.6	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/memcache.php
Null	Dummy module that doesn't actually save anything	>= 3.0.6	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/null.php
Redis [6]	Uses a key-value database	>= 3.0.9	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/redis.php
WinCache [7]	PHP bytecode cache for Windows	>= 3.0.9	https://github.com/phpbb/phpbb/tree/master/phpBB/phpbb/cache/driver/wincache.php

File

As of 3.0.6-dev the file cache module uses a new improved format for its cache files. These files are read using PHP's file system functions -- namely fread() and fgets() -- this approach uses less disk I/O as the files are read intelligently mostly line by line. The files contain a PHP header to stop information leak by browsers navigating to the cache folder, this is a last line defence -- the cache folder should really be off limits to clients -- however they are not included as PHP files by phpBB so as not to fragment opcode caches.

Steps:

1. The first line is read and discarded (PHP header)
2. Second line is read (expiration)
   1. Processing ends if the expiration is invalid or in the past
3. On SQL cache files the third line (query) is read and discarded
4. The next line (bytes) is read containing the number of bytes of data
   1. Processing ends if this is invalid
5. The number of bytes from the previous line is read (data) this is then stored
6. One single byte is read if we don't reach the end of the file now then the data is deemed to be tampered with and discarded

Where:

• expiration := expiration timestamp
• query := SQL query
• bytes := number of bytes in data (except global data includes the length of var)
• var := Variable name
• data := Cached data

SQL queries:

<?php exit; ?>
(expiration)
(query)
(bytes)
(data)

Normal data:

<?php exit; ?>
(expiration)
(bytes)
(data)

Global data:

<?php exit; ?>
(expiration)
(bytes)
(var)
(data)
(expiration-n)
(bytes-n)
(var-n)
(data-n)
...