<?php
/**
- * Abstract special page class with scaffolding for caching the HTML output.
+ * Abstract special page class with scaffolding for caching HTML and other values
+ * in a single blob.
*
- * To enable the caching functionality, the cacheExpiry field should be set
- * in the constructor.
+ * Before using any of the caching functionality, call startCache.
+ * After the last call to either getCachedValue or addCachedHTML, call saveCache.
+ *
+ * To get a cached value or compute it, use getCachedValue like this:
+ * $this->getCachedValue( $callback );
*
* To add HTML that should be cached, use addCachedHTML like this:
- * $this->addCachedHTML( array( $this, 'displayCachedContent' ) );
+ * $this->addCachedHTML( $callback );
*
- * After adding the last HTML that should be cached, call $this->saveCache();
+ * The callback function is only called when needed, so do all your expensive
+ * computations here. This function should returns the HTML to be cached.
+ * It should not add anything to the PageOutput object!
*
- * @since 1.20
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
*
- * @file SpecialCachedPage.php
- * @ingroup SpecialPage
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
*
- * @licence GNU GPL v2 or later
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup SpecialPage
* @author Jeroen De Dauw < jeroendedauw@gmail.com >
+ * @since 1.20
*/
-abstract class SpecialCachedPage extends SpecialPage {
+abstract class SpecialCachedPage extends SpecialPage implements ICacheHelper {
/**
- * The time to live for the cache, in seconds or a unix timestamp indicating the point of expiry.
+ * CacheHelper object to which we forward the non-SpecialPage specific caching work.
+ * Initialized in startCache.
*
* @since 1.20
- * @var integer|null
+ * @var CacheHelper
*/
- protected $cacheExpiry = null;
+ protected $cacheHelper;
/**
- * List of HTML chunks to be cached (if !hasCached) or that where cashed (of hasCached).
- * If no cached already, then the newly computed chunks are added here,
- * if it as cached already, chunks are removed from this list as they are needed.
+ * If the cache is enabled or not.
*
* @since 1.20
- * @var array
+ * @var boolean
*/
- protected $cachedChunks;
+ protected $cacheEnabled = true;
/**
- * Indicates if the to be cached content was already cached.
- * Null if this information is not available yet.
+ * Gets called after @see SpecialPage::execute.
*
* @since 1.20
- * @var boolean|null
+ *
+ * @param $subPage string|null
*/
- protected $hasCached = null;
+ protected function afterExecute( $subPage ) {
+ $this->saveCache();
+
+ parent::afterExecute( $subPage );
+ }
/**
- * Main method.
+ * Sets if the cache should be enabled or not.
*
* @since 1.20
- *
- * @param string|null $subPage
+ * @param boolean $cacheEnabled
*/
- public function execute( $subPage ) {
- if ( $this->getRequest()->getText( 'action' ) === 'purge' ) {
- $this->hasCached = false;
- }
-
- if ( !is_null( $this->cacheExpiry ) ) {
- $this->initCaching();
-
- if ( $this->hasCached === true ) {
- $this->getOutput()->setSubtitle( $this->getCachedNotice( $subPage ) );
- }
- }
+ public function setCacheEnabled( $cacheEnabled ) {
+ $this->cacheHelper->setCacheEnabled( $cacheEnabled );
}
/**
- * Returns a message that notifies the user he/she is looking at
- * a cached version of the page, including a refresh link.
+ * Initializes the caching.
+ * Should be called before the first time anything is added via addCachedHTML.
*
* @since 1.20
*
- * @param string|null $subPage
- *
- * @return string
+ * @param integer|null $cacheExpiry Sets the cache expiry, either ttl in seconds or unix timestamp.
+ * @param boolean|null $cacheEnabled Sets if the cache should be enabled or not.
*/
- protected function getCachedNotice( $subPage ) {
- $refreshArgs = $this->getRequest()->getQueryValues();
- unset( $refreshArgs['title'] );
- $refreshArgs['action'] = 'purge';
-
- $refreshLink = Linker::link(
- $this->getTitle( $subPage ),
- $this->msg( 'cachedspecial-refresh-now' )->escaped(),
- array(),
- $refreshArgs
- );
+ public function startCache( $cacheExpiry = null, $cacheEnabled = null ) {
+ if ( !isset( $this->cacheHelper ) ) {
+ $this->cacheHelper = new CacheHelper();
- if ( $this->cacheExpiry < 1000000000 ) {
- $message = $this->msg(
- 'cachedspecial-viewing-cached-ttl',
- $this->getLanguage()->formatDuration( $this->cacheExpiry )
- )->escaped();
- }
- else {
- $message = $this->msg(
- 'cachedspecial-viewing-cached-ts'
- )->escaped();
+ $this->cacheHelper->setCacheEnabled( $this->cacheEnabled );
+ $this->cacheHelper->setOnInitializedHandler( array( $this, 'onCacheInitialized' ) );
+
+ $keyArgs = $this->getCacheKey();
+
+ if ( array_key_exists( 'action', $keyArgs ) && $keyArgs['action'] === 'purge' ) {
+ unset( $keyArgs['action'] );
+ }
+
+ $this->cacheHelper->setCacheKey( $keyArgs );
+
+ if ( $this->getRequest()->getText( 'action' ) === 'purge' ) {
+ $this->cacheHelper->rebuildOnDemand();
+ }
}
- return $message . ' ' . $refreshLink;
+ $this->cacheHelper->startCache( $cacheExpiry, $cacheEnabled );
}
/**
- * Initializes the caching if not already done so.
- * Should be called before any of the caching functionality is used.
+ * Get a cached value if available or compute it if not and then cache it if possible.
+ * The provided $computeFunction is only called when the computation needs to happen
+ * and should return a result value. $args are arguments that will be passed to the
+ * compute function when called.
*
* @since 1.20
+ *
+ * @param {function} $computeFunction
+ * @param array|mixed $args
+ * @param string|null $key
+ *
+ * @return mixed
*/
- protected function initCaching() {
- if ( is_null( $this->hasCached ) ) {
- $cachedChunks = wfGetCache( CACHE_ANYTHING )->get( $this->getCacheKey() );
-
- $this->hasCached = is_array( $cachedChunks );
- $this->cachedChunks = $this->hasCached ? $cachedChunks : array();
- }
+ public function getCachedValue( $computeFunction, $args = array(), $key = null ) {
+ return $this->cacheHelper->getCachedValue( $computeFunction, $args, $key );
}
/**
*
* @since 1.20
*
- * @param {function} $callback
+ * @param {function} $computeFunction
* @param array $args
* @param string|null $key
*/
- public function addCachedHTML( $callback, $args = array(), $key = null ) {
- $this->initCaching();
-
- if ( $this->hasCached ) {
- $html = '';
-
- if ( is_null( $key ) ) {
- $itemKey = array_keys( array_slice( $this->cachedChunks, 0, 1 ) );
- $itemKey = array_shift( $itemKey );
-
- if ( !is_integer( $itemKey ) ) {
- wfWarn( "Attempted to get item with non-numeric key while the next item in the queue has a key ($itemKey) in " . __METHOD__ );
- }
- elseif ( is_null( $itemKey ) ) {
- wfWarn( "Attempted to get an item while the queue is empty in " . __METHOD__ );
- }
- else {
- $html = array_shift( $this->cachedChunks );
- }
- }
- else {
- if ( array_key_exists( $key, $this->cachedChunks ) ) {
- $html = $this->cachedChunks[$key];
- unset( $this->cachedChunks[$key] );
- }
- else {
- wfWarn( "There is no item with key '$key' in this->cachedChunks in " . __METHOD__ );
- }
- }
- }
- else {
- $html = call_user_func_array( $callback, $args );
-
- if ( is_null( $key ) ) {
- $this->cachedChunks[] = $html;
- }
- else {
- $this->cachedChunks[$key] = $html;
- }
- }
-
- $this->getOutput()->addHTML( $html );
+ public function addCachedHTML( $computeFunction, $args = array(), $key = null ) {
+ $this->getOutput()->addHTML( $this->cacheHelper->getCachedValue( $computeFunction, $args, $key ) );
}
/**
* @since 1.20
*/
public function saveCache() {
- if ( $this->hasCached === false && !empty( $this->cachedChunks ) ) {
- wfGetCache( CACHE_ANYTHING )->set( $this->getCacheKey(), $this->cachedChunks, $this->cacheExpiry );
+ if ( isset( $this->cacheHelper ) ) {
+ $this->cacheHelper->saveCache();
}
}
/**
- * Sets the time to live for the cache, in seconds or a unix timestamp indicating the point of expiry..
+ * Sets the time to live for the cache, in seconds or a unix timestamp indicating the point of expiry.
*
* @since 1.20
*
* @param integer $cacheExpiry
*/
- protected function setExpirey( $cacheExpiry ) {
- $this->cacheExpiry = $cacheExpiry;
+ public function setExpiry( $cacheExpiry ) {
+ $this->cacheHelper->setExpiry( $cacheExpiry );
}
/**
- * Returns the cache key to use to cache this page's HTML output.
- * Is constructed from the special page name and language code.
+ * Returns the variables used to constructed the cache key in an array.
*
* @since 1.20
*
- * @return string
+ * @return array
*/
protected function getCacheKey() {
- return wfMemcKey( $this->mName, $this->getLanguage()->getCode() );
+ return array(
+ $this->mName,
+ $this->getLanguage()->getCode()
+ );
+ }
+
+ /**
+ * Gets called after the cache got initialized.
+ *
+ * @since 1.20
+ *
+ * @param boolean $hasCached
+ */
+ public function onCacheInitialized( $hasCached ) {
+ if ( $hasCached ) {
+ $this->getOutput()->setSubtitle( $this->cacheHelper->getCachedNotice( $this->getContext() ) );
+ }
}
}