Cache
From phpBB Development Wiki
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
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:
- The first line is read and discarded (PHP header)
- Second line is read (expiration)
- Processing ends if the expiration is invalid or in the past
- On SQL cache files the third line (query) is read and discarded
- The next line (bytes) is read containing the number of bytes of data
- Processing ends if this is invalid
- The number of bytes from the previous line is read (data) this is then stored
- 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) ...