Development Wiki

Difference between revisions of "Cache"

From phpBB Development Wiki

(File: Note about PHP header)
m (Modules: Makes more sense)
Line 189: Line 189:
| File
| File
| Utilises disk drive for data storage
| Utilises disk drive for data storage
| >= 2.1
| >= 3.0.0
| [ includes/acm/acm_file.php]
| [ includes/acm/acm_file.php]

Revision as of 15:01, 13 June 2009

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.


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)


Module Description Version File
File Utilises disk drive for data storage >= 3.0.0 includes/acm/acm_file.php
XCache [1] Storage of data in shared memory >= 3.0.6 includes/acm/acm_xcache.php
APC [2] Storage of data in shared memory >= 3.0.6 includes/acm/acm_apc.php
eAccelerator [3] Storage of data in shared memory >= 3.0.6 includes/acm/acm_eaccelerator.php
Memcache [4] Uses a memcached instance to store data >= 3.0.6 includes/acm/acm_memcache.php
Null Dummy module that doesn't actually save anything >= 3.0.6 includes/acm/acm_null.php


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.


  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


  • 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; ?>

Normal data:

<?php exit; ?>

Global data:

<?php exit; ?>

This article is a stub. You can help in improving Olympus Documentation by expanding it.