From 7c92fcab00e07b18bc2b7234d35b58b8595572a0 Mon Sep 17 00:00:00 2001 From: Jeroen De Dauw Date: Mon, 19 Mar 2012 23:33:25 +0000 Subject: [PATCH] split general cache helper functionality to its own class, so we can also easily use it in stuff that does not derive from SpecialPage, such as Action --- includes/AutoLoader.php | 2 + includes/CacheHelper.php | 348 ++++++++++++++++++++++++ includes/specials/SpecialCachedPage.php | 235 +++------------- 3 files changed, 388 insertions(+), 197 deletions(-) create mode 100644 includes/CacheHelper.php diff --git a/includes/AutoLoader.php b/includes/AutoLoader.php index 905d35b6c6..adf7834559 100644 --- a/includes/AutoLoader.php +++ b/includes/AutoLoader.php @@ -27,6 +27,7 @@ $wgAutoloadLocalClasses = array( 'BadTitleError' => 'includes/Exception.php', 'BaseTemplate' => 'includes/SkinTemplate.php', 'Block' => 'includes/Block.php', + 'CacheHelper' => 'includes/CacheHelper.php', 'Category' => 'includes/Category.php', 'Categoryfinder' => 'includes/Categoryfinder.php', 'CategoryPage' => 'includes/CategoryPage.php', @@ -119,6 +120,7 @@ $wgAutoloadLocalClasses = array( 'Http' => 'includes/HttpFunctions.php', 'HttpError' => 'includes/Exception.php', 'HttpRequest' => 'includes/HttpFunctions.old.php', + 'ICacheHelper' => 'includes/CacheHelper.php', 'IcuCollation' => 'includes/Collation.php', 'IdentityCollation' => 'includes/Collation.php', 'ImageGallery' => 'includes/ImageGallery.php', diff --git a/includes/CacheHelper.php b/includes/CacheHelper.php new file mode 100644 index 0000000000..b61e2ada2a --- /dev/null +++ b/includes/CacheHelper.php @@ -0,0 +1,348 @@ +getCachedValue( $callback ); + * + * To add HTML that should be cached, use addCachedHTML like this: + * $this->addCachedHTML( $callback ); + * + * 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! + * + * Before the first addCachedHTML call, you should call $this->startCache(); + * After adding the last HTML that should be cached, call $this->saveCache(); + * + * @since 1.20 + * + * @file CacheHelper.php + * @ingroup SpecialPage + * + * @licence GNU GPL v2 or later + * @author Jeroen De Dauw < jeroendedauw@gmail.com > + */ +class CacheHelper implements ICacheHelper { + + /** + * The time to live for the cache, in seconds or a unix timestamp indicating the point of expiry. + * + * @since 1.20 + * @var integer + */ + protected $cacheExpiry = 3600; + + /** + * 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. + * + * @since 1.20 + * @var array + */ + protected $cachedChunks; + + /** + * Indicates if the to be cached content was already cached. + * Null if this information is not available yet. + * + * @since 1.20 + * @var boolean|null + */ + protected $hasCached = null; + + /** + * If the cache is enabled or not. + * + * @since 1.20 + * @var boolean + */ + protected $cacheEnabled = true; + + /** + * Function that gets called when initialization is done. + * + * @since 1.20 + * @var function + */ + protected $onInitHandler = false; + + /** + * Sets if the cache should be enabled or not. + * + * @since 1.20 + * @param boolean $cacheEnabled + */ + public function setCacheEnabled( $cacheEnabled ) { + $this->cacheEnabled = $cacheEnabled; + } + + /** + * Initializes the caching. + * Should be called before the first time anything is added via addCachedHTML. + * + * @since 1.20 + * + * @param integer|null $cacheExpiry Sets the cache expirty, either ttl in seconds or unix timestamp. + * @param boolean|null $cacheEnabled Sets if the cache should be enabled or not. + */ + public function startCache( $cacheExpiry = null, $cacheEnabled = null ) { + if ( is_null( $this->hasCached ) ) { + if ( !is_null( $cacheExpiry ) ) { + $this->cacheExpiry = $cacheExpiry; + } + + if ( !is_null( $cacheEnabled ) ) { + $this->setCacheEnabled( $cacheEnabled ); + } + + $this->initCaching(); + } + } + + /** + * Returns a message that notifies the user he/she is looking at + * a cached version of the page, including a refresh link. + * + * @since 1.20 + * + * @param IContextSource $context + * + * @return string + */ + public function getCachedNotice( IContextSource $context ) { + $refreshArgs = $context->getRequest()->getQueryValues(); + unset( $refreshArgs['title'] ); + $refreshArgs['action'] = 'purge'; + + $subPage = $context->getTitle()->getFullText(); + $subPage = explode( '/', $subPage, 2 ); + $subPage = count( $subPage ) > 1 ? $subPage[1] : false; + + $refreshLink = Linker::link( + $context->getTitle( $subPage ), + $context->msg( 'cachedspecial-refresh-now' )->escaped(), + array(), + $refreshArgs + ); + + if ( $this->cacheExpiry < 86400 * 3650 ) { + $message = $context->msg( + 'cachedspecial-viewing-cached-ttl', + $context->getLanguage()->formatDuration( $this->cacheExpiry ) + )->escaped(); + } + else { + $message = $context->msg( + 'cachedspecial-viewing-cached-ts' + )->escaped(); + } + + return $message . ' ' . $refreshLink; + } + + /** + * Initializes the caching if not already done so. + * Should be called before any of the caching functionality is used. + * + * @since 1.20 + */ + protected function initCaching() { + if ( $this->cacheEnabled && is_null( $this->hasCached ) ) { + $cachedChunks = wfGetCache( CACHE_ANYTHING )->get( $this->getCacheKeyString() ); + + $this->hasCached = is_array( $cachedChunks ); + $this->cachedChunks = $this->hasCached ? $cachedChunks : array(); + + if ( $this->onInitHandler !== false ) { + call_user_func( $this->onInitHandler, $this->hasCached ); + } + } + } + + + + /** + * Add some HTML to be cached. + * This is done by providing a callback function that should + * return the HTML to be added. It will only be called if the + * item is not in the cache yet or when the cache has been invalidated. + * + * @since 1.20 + * + * @param {function} $computeFunction + * @param array $args + * @param string|null $key + */ + public function addCachedHTML( $computeFunction, $args = array(), $key = null ) { + $this->getOutput()->addHTML( $this->getCachedValue( $computeFunction, $args, $key ) ); + } + + /** + * 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 + */ + public function getCachedValue( $computeFunction, $args = array(), $key = null ) { + $this->initCaching(); + + if ( $this->cacheEnabled && $this->hasCached ) { + $value = null; + + 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 { + $value = array_shift( $this->cachedChunks ); + } + } + else { + if ( array_key_exists( $key, $this->cachedChunks ) ) { + $value = $this->cachedChunks[$key]; + unset( $this->cachedChunks[$key] ); + } + else { + wfWarn( "There is no item with key '$key' in this->cachedChunks in " . __METHOD__ ); + } + } + } + else { + if ( !is_array( $args ) ) { + $args = array( $args ); + } + + $value = call_user_func_array( $computeFunction, $args ); + + if ( $this->cacheEnabled ) { + if ( is_null( $key ) ) { + $this->cachedChunks[] = $value; + } + else { + $this->cachedChunks[$key] = $value; + } + } + } + + return $value; + } + + /** + * Saves the HTML to the cache in case it got recomputed. + * Should be called after the last time anything is added via addCachedHTML. + * + * @since 1.20 + */ + public function saveCache() { + if ( $this->cacheEnabled && $this->hasCached === false && !empty( $this->cachedChunks ) ) { + wfGetCache( CACHE_ANYTHING )->set( $this->getCacheKeyString(), $this->cachedChunks, $this->cacheExpiry ); + } + } + + /** + * 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 + */ + public function setExpirey( $cacheExpiry ) { + $this->cacheExpiry = $cacheExpiry; + } + + /** + * Returns the cache key to use to cache this page's HTML output. + * Is constructed from the special page name and language code. + * + * @since 1.20 + * + * @return string + */ + protected function getCacheKeyString() { + return call_user_func_array( 'wfMemcKey', $this->cacheKey ); + } + + public function setCacheKey( array $cacheKey ) { + $this->cacheKey = $cacheKey; + } + + public function purge() { + $this->hasCached = false; + } + + public function setOnInitializedHandler( $handlerFunction ) { + $this->onInitHandler = $handlerFunction; + } + +} diff --git a/includes/specials/SpecialCachedPage.php b/includes/specials/SpecialCachedPage.php index 9a13e3d14c..b721c26ff6 100644 --- a/includes/specials/SpecialCachedPage.php +++ b/includes/specials/SpecialCachedPage.php @@ -3,6 +3,12 @@ /** * Abstract special page class with scaffolding for caching the HTML output. * + * Before using any of the cahing 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( $callback ); * @@ -10,9 +16,6 @@ * computations here. This function should returns the HTML to be cached. * It should not add anything to the PageOutput object! * - * Before the first addCachedHTML call, you should call $this->startCache(); - * After adding the last HTML that should be cached, call $this->saveCache(); - * * @since 1.20 * * @file SpecialCachedPage.php @@ -21,42 +24,16 @@ * @licence GNU GPL v2 or later * @author Jeroen De Dauw < jeroendedauw@gmail.com > */ -abstract class SpecialCachedPage extends SpecialPage { - - /** - * The time to live for the cache, in seconds or a unix timestamp indicating the point of expiry. - * - * @since 1.20 - * @var integer - */ - protected $cacheExpiry = 3600; +abstract class SpecialCachedPage extends SpecialPage implements ICacheHelper { /** - * 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. + * CacheHelper object to which we foreward the non-SpecialPage specific caching work. + * Initialized in startCache. * * @since 1.20 - * @var array + * @var CacheHelper */ - protected $cachedChunks; - - /** - * Indicates if the to be cached content was already cached. - * Null if this information is not available yet. - * - * @since 1.20 - * @var boolean|null - */ - protected $hasCached = null; - - /** - * If the cache is enabled or not. - * - * @since 1.20 - * @var boolean - */ - protected $cacheEnabled = true; + protected $cacheHelper; /** * Sets if the cache should be enabled or not. @@ -65,7 +42,7 @@ abstract class SpecialCachedPage extends SpecialPage { * @param boolean $cacheEnabled */ public function setCacheEnabled( $cacheEnabled ) { - $this->cacheEnabled = $cacheEnabled; + $this->cacheHelper->setCacheEnabled( $cacheEnabled ); } /** @@ -78,88 +55,23 @@ abstract class SpecialCachedPage extends SpecialPage { * @param boolean|null $cacheEnabled Sets if the cache should be enabled or not. */ public function startCache( $cacheExpiry = null, $cacheEnabled = null ) { - if ( is_null( $this->hasCached ) ) { - if ( !is_null( $cacheExpiry ) ) { - $this->cacheExpiry = $cacheExpiry; - } + $this->cacheHelper = new CacheHelper( $this->get ); - if ( !is_null( $cacheEnabled ) ) { - $this->setCacheEnabled( $cacheEnabled ); - } + $this->cacheHelper->setOnInitializedHandler( array( $this, 'onCacheInitialized' ) ); - if ( $this->getRequest()->getText( 'action' ) === 'purge' ) { - $this->hasCached = false; - } + $keyArgs = $this->getCacheKey(); - $this->initCaching(); + if ( array_key_exists( 'action', $keyArgs ) && $keyArgs['action'] === 'purge' ) { + unset( $keyArgs['action'] ); } - } - /** - * Returns a message that notifies the user he/she is looking at - * a cached version of the page, including a refresh link. - * - * @since 1.20 - * - * @return string - */ - protected function getCachedNotice() { - $refreshArgs = $this->getRequest()->getQueryValues(); - unset( $refreshArgs['title'] ); - $refreshArgs['action'] = 'purge'; - - $subPage = $this->getTitle()->getFullText(); - $subPage = explode( '/', $subPage, 2 ); - $subPage = count( $subPage ) > 1 ? $subPage[1] : false; + $this->cacheHelper->setCacheKey( $keyArgs ); - $refreshLink = Linker::link( - $this->getTitle( $subPage ), - $this->msg( 'cachedspecial-refresh-now' )->escaped(), - array(), - $refreshArgs - ); - - if ( $this->cacheExpiry < 86400 * 3650 ) { - $message = $this->msg( - 'cachedspecial-viewing-cached-ttl', - $this->getLanguage()->formatDuration( $this->cacheExpiry ) - )->escaped(); - } - else { - $message = $this->msg( - 'cachedspecial-viewing-cached-ts' - )->escaped(); + if ( $this->getRequest()->getText( 'action' ) === 'purge' ) { + $this->cacheHelper->purge(); } - return $message . ' ' . $refreshLink; - } - - /** - * Initializes the caching if not already done so. - * Should be called before any of the caching functionality is used. - * - * @since 1.20 - */ - protected function initCaching() { - if ( $this->cacheEnabled && is_null( $this->hasCached ) ) { - $cachedChunks = wfGetCache( CACHE_ANYTHING )->get( $this->getCacheKeyString() ); - - $this->hasCached = is_array( $cachedChunks ); - $this->cachedChunks = $this->hasCached ? $cachedChunks : array(); - - $this->onCacheInitialized(); - } - } - - /** - * Gets called after the cache got initialized. - * - * @since 1.20 - */ - protected function onCacheInitialized() { - if ( $this->hasCached ) { - $this->getOutput()->setSubtitle( $this->getCachedNotice() ); - } + $this->cacheHelper->startCache( $cacheExpiry, $cacheEnabled ); } /** @@ -175,71 +87,7 @@ abstract class SpecialCachedPage extends SpecialPage { * @param string|null $key */ public function addCachedHTML( $computeFunction, $args = array(), $key = null ) { - $this->getOutput()->addHTML( $this->getCachedValue( $computeFunction, $args, $key ) ); - } - - /** - * 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 getCachedValue( $computeFunction, $args = array(), $key = null ) { - $this->initCaching(); - - if ( $this->cacheEnabled && $this->hasCached ) { - $value = null; - - 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 { - $value = array_shift( $this->cachedChunks ); - } - } - else { - if ( array_key_exists( $key, $this->cachedChunks ) ) { - $value = $this->cachedChunks[$key]; - unset( $this->cachedChunks[$key] ); - } - else { - wfWarn( "There is no item with key '$key' in this->cachedChunks in " . __METHOD__ ); - } - } - } - else { - if ( !is_array( $args ) ) { - $args = array( $args ); - } - - $value = call_user_func_array( $computeFunction, $args ); - - if ( $this->cacheEnabled ) { - if ( is_null( $key ) ) { - $this->cachedChunks[] = $value; - } - else { - $this->cachedChunks[$key] = $value; - } - } - } - - return $value; + $this->getOutput()->addHTML( $this->cacheHelper->getCachedValue( $computeFunction, $args, $key ) ); } /** @@ -249,9 +97,7 @@ abstract class SpecialCachedPage extends SpecialPage { * @since 1.20 */ public function saveCache() { - if ( $this->cacheEnabled && $this->hasCached === false && !empty( $this->cachedChunks ) ) { - wfGetCache( CACHE_ANYTHING )->set( $this->getCacheKeyString(), $this->cachedChunks, $this->cacheExpiry ); - } + $this->cacheHelper->saveCache(); } /** @@ -261,26 +107,8 @@ abstract class SpecialCachedPage extends SpecialPage { * * @param integer $cacheExpiry */ - protected function setExpirey( $cacheExpiry ) { - $this->cacheExpiry = $cacheExpiry; - } - - /** - * Returns the cache key to use to cache this page's HTML output. - * Is constructed from the special page name and language code. - * - * @since 1.20 - * - * @return string - */ - protected function getCacheKeyString() { - $keyArgs = $this->getCacheKey(); - - if ( array_key_exists( 'action', $keyArgs ) && $keyArgs['action'] === 'purge' ) { - unset( $keyArgs['action'] ); - } - - return call_user_func_array( 'wfMemcKey', $keyArgs ); + public function setExpirey( $cacheExpiry ) { + $this->cacheHelper->setExpirey( $cacheExpiry ); } /** @@ -297,4 +125,17 @@ abstract class SpecialCachedPage extends SpecialPage { ); } + /** + * 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() ) ); + } + } + } -- 2.20.1