includes/CacheHelper.php

   1 <?php
   2
   3 /**
   4  * Interface for all classes implementing CacheHelper functionality.
   5  *
   6  * @since 1.20
   7  *
   8  * @licence GNU GPL v2 or later
   9  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  10  */
  11 interface ICacheHelper {
  12
  13         /**
  14          * Sets if the cache should be enabled or not.
  15          *
  16          * @since 1.20
  17          * @param boolean $cacheEnabled
  18          */
  19         function setCacheEnabled( $cacheEnabled );
  20
  21         /**
  22          * Initializes the caching.
  23          * Should be called before the first time anything is added via addCachedHTML.
  24          *
  25          * @since 1.20
  26          *
  27          * @param integer|null $cacheExpiry Sets the cache expirty, either ttl in seconds or unix timestamp.
  28          * @param boolean|null $cacheEnabled Sets if the cache should be enabled or not.
  29          */
  30         function startCache( $cacheExpiry = null, $cacheEnabled = null );
  31
  32         /**
  33          * Get a cached value if available or compute it if not and then cache it if possible.
  34          * The provided $computeFunction is only called when the computation needs to happen
  35          * and should return a result value. $args are arguments that will be passed to the
  36          * compute function when called.
  37          *
  38          * @since 1.20
  39          *
  40          * @param {function} $computeFunction
  41          * @param array|mixed $args
  42          * @param string|null $key
  43          *
  44          * @return mixed
  45          */
  46         function getCachedValue( $computeFunction, $args = array(), $key = null );
  47
  48         /**
  49          * Saves the HTML to the cache in case it got recomputed.
  50          * Should be called after the last time anything is added via addCachedHTML.
  51          *
  52          * @since 1.20
  53          */
  54         function saveCache();
  55
  56         /**
  57          * Sets the time to live for the cache, in seconds or a unix timestamp indicating the point of expiry..
  58          *
  59          * @since 1.20
  60          *
  61          * @param integer $cacheExpiry
  62          */
  63         function setExpirey( $cacheExpiry );
  64
  65 }
  66
  67 /**
  68  * Helper class for caching various elements in a single cache entry.
  69  *
  70  * To get a cached value or compute it, use getCachedValue like this:
  71  * $this->getCachedValue( $callback );
  72  *
  73  * To add HTML that should be cached, use addCachedHTML like this:
  74  * $this->addCachedHTML( $callback );
  75  *
  76  * The callback function is only called when needed, so do all your expensive
  77  * computations here. This function should returns the HTML to be cached.
  78  * It should not add anything to the PageOutput object!
  79  *
  80  * Before the first addCachedHTML call, you should call $this->startCache();
  81  * After adding the last HTML that should be cached, call $this->saveCache();
  82  *
  83  * @since 1.20
  84  *
  85  * @file CacheHelper.php
  86  *
  87  * @licence GNU GPL v2 or later
  88  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  89  */
  90 class CacheHelper implements ICacheHelper {
  91
  92         /**
  93          * The time to live for the cache, in seconds or a unix timestamp indicating the point of expiry.
  94          *
  95          * @since 1.20
  96          * @var integer
  97          */
  98         protected $cacheExpiry = 3600;
  99
 100         /**
 101          * List of HTML chunks to be cached (if !hasCached) or that where cashed (of hasCached).
 102          * If no cached already, then the newly computed chunks are added here,
 103          * if it as cached already, chunks are removed from this list as they are needed.
 104          *
 105          * @since 1.20
 106          * @var array
 107          */
 108         protected $cachedChunks;
 109
 110         /**
 111          * Indicates if the to be cached content was already cached.
 112          * Null if this information is not available yet.
 113          *
 114          * @since 1.20
 115          * @var boolean|null
 116          */
 117         protected $hasCached = null;
 118
 119         /**
 120          * If the cache is enabled or not.
 121          *
 122          * @since 1.20
 123          * @var boolean
 124          */
 125         protected $cacheEnabled = true;
 126
 127         /**
 128          * Function that gets called when initialization is done.
 129          *
 130          * @since 1.20
 131          * @var function
 132          */
 133         protected $onInitHandler = false;
 134
 135         /**
 136          * Sets if the cache should be enabled or not.
 137          *
 138          * @since 1.20
 139          * @param boolean $cacheEnabled
 140          */
 141         public function setCacheEnabled( $cacheEnabled ) {
 142                 $this->cacheEnabled = $cacheEnabled;
 143         }
 144
 145         /**
 146          * Initializes the caching.
 147          * Should be called before the first time anything is added via addCachedHTML.
 148          *
 149          * @since 1.20
 150          *
 151          * @param integer|null $cacheExpiry Sets the cache expirty, either ttl in seconds or unix timestamp.
 152          * @param boolean|null $cacheEnabled Sets if the cache should be enabled or not.
 153          */
 154         public function startCache( $cacheExpiry = null, $cacheEnabled = null ) {
 155                 if ( is_null( $this->hasCached ) ) {
 156                         if ( !is_null( $cacheExpiry ) ) {
 157                                 $this->cacheExpiry = $cacheExpiry;
 158                         }
 159
 160                         if ( !is_null( $cacheEnabled ) ) {
 161                                 $this->setCacheEnabled( $cacheEnabled );
 162                         }
 163
 164                         $this->initCaching();
 165                 }
 166         }
 167
 168         /**
 169          * Returns a message that notifies the user he/she is looking at
 170          * a cached version of the page, including a refresh link.
 171          *
 172          * @since 1.20
 173          *
 174          * @param IContextSource $context
 175          *
 176          * @return string
 177          */
 178         public function getCachedNotice( IContextSource $context ) {
 179                 $refreshArgs = $context->getRequest()->getQueryValues();
 180                 unset( $refreshArgs['title'] );
 181                 $refreshArgs['action'] = 'purge';
 182
 183                 $subPage = $context->getTitle()->getFullText();
 184                 $subPage = explode( '/', $subPage, 2 );
 185                 $subPage = count( $subPage ) > 1 ? $subPage[1] : false;
 186
 187                 $refreshLink = Linker::link(
 188                         $context->getTitle( $subPage ),
 189                         $context->msg( 'cachedspecial-refresh-now' )->escaped(),
 190                         array(),
 191                         $refreshArgs
 192                 );
 193
 194                 if ( $this->cacheExpiry < 86400 * 3650 ) {
 195                         $message = $context->msg(
 196                                 'cachedspecial-viewing-cached-ttl',
 197                                 $context->getLanguage()->formatDuration( $this->cacheExpiry )
 198                         )->escaped();
 199                 }
 200                 else {
 201                         $message = $context->msg(
 202                                 'cachedspecial-viewing-cached-ts'
 203                         )->escaped();
 204                 }
 205
 206                 return $message . ' ' . $refreshLink;
 207         }
 208
 209         /**
 210          * Initializes the caching if not already done so.
 211          * Should be called before any of the caching functionality is used.
 212          *
 213          * @since 1.20
 214          */
 215         protected function initCaching() {
 216                 if ( $this->cacheEnabled && is_null( $this->hasCached ) ) {
 217                         $cachedChunks = wfGetCache( CACHE_ANYTHING )->get( $this->getCacheKeyString() );
 218
 219                         $this->hasCached = is_array( $cachedChunks );
 220                         $this->cachedChunks = $this->hasCached ? $cachedChunks : array();
 221
 222                         if ( $this->onInitHandler !== false ) {
 223                                 call_user_func( $this->onInitHandler, $this->hasCached );
 224                         }
 225                 }
 226         }
 227
 228         /**
 229          * Get a cached value if available or compute it if not and then cache it if possible.
 230          * The provided $computeFunction is only called when the computation needs to happen
 231          * and should return a result value. $args are arguments that will be passed to the
 232          * compute function when called.
 233          *
 234          * @since 1.20
 235          *
 236          * @param {function} $computeFunction
 237          * @param array|mixed $args
 238          * @param string|null $key
 239          *
 240          * @return mixed
 241          */
 242         public function getCachedValue( $computeFunction, $args = array(), $key = null ) {
 243                 $this->initCaching();
 244
 245                 if ( $this->cacheEnabled && $this->hasCached ) {
 246                         $value = null;
 247
 248                         if ( is_null( $key ) ) {
 249                                 $itemKey = array_keys( array_slice( $this->cachedChunks, 0, 1 ) );
 250                                 $itemKey = array_shift( $itemKey );
 251
 252                                 if ( !is_integer( $itemKey ) ) {
 253                                         wfWarn( "Attempted to get item with non-numeric key while the next item in the queue has a key ($itemKey) in " . __METHOD__ );
 254                                 }
 255                                 elseif ( is_null( $itemKey ) ) {
 256                                         wfWarn( "Attempted to get an item while the queue is empty in " . __METHOD__ );
 257                                 }
 258                                 else {
 259                                         $value = array_shift( $this->cachedChunks );
 260                                 }
 261                         }
 262                         else {
 263                                 if ( array_key_exists( $key, $this->cachedChunks ) ) {
 264                                         $value = $this->cachedChunks[$key];
 265                                         unset( $this->cachedChunks[$key] );
 266                                 }
 267                                 else {
 268                                         wfWarn( "There is no item with key '$key' in this->cachedChunks in " . __METHOD__ );
 269                                 }
 270                         }
 271                 }
 272                 else {
 273                         if ( !is_array( $args ) ) {
 274                                 $args = array( $args );
 275                         }
 276
 277                         $value = call_user_func_array( $computeFunction, $args );
 278
 279                         if ( $this->cacheEnabled ) {
 280                                 if ( is_null( $key ) ) {
 281                                         $this->cachedChunks[] = $value;
 282                                 }
 283                                 else {
 284                                         $this->cachedChunks[$key] = $value;
 285                                 }
 286                         }
 287                 }
 288
 289                 return $value;
 290         }
 291
 292         /**
 293          * Saves the HTML to the cache in case it got recomputed.
 294          * Should be called after the last time anything is added via addCachedHTML.
 295          *
 296          * @since 1.20
 297          */
 298         public function saveCache() {
 299                 if ( $this->cacheEnabled && $this->hasCached === false && !empty( $this->cachedChunks ) ) {
 300                         wfGetCache( CACHE_ANYTHING )->set( $this->getCacheKeyString(), $this->cachedChunks, $this->cacheExpiry );
 301                 }
 302         }
 303
 304         /**
 305          * Sets the time to live for the cache, in seconds or a unix timestamp indicating the point of expiry..
 306          *
 307          * @since 1.20
 308          *
 309          * @param integer $cacheExpiry
 310          */
 311         public function setExpirey( $cacheExpiry ) {
 312                 $this->cacheExpiry = $cacheExpiry;
 313         }
 314
 315         /**
 316          * Returns the cache key to use to cache this page's HTML output.
 317          * Is constructed from the special page name and language code.
 318          *
 319          * @since 1.20
 320          *
 321          * @return string
 322          */
 323         protected function getCacheKeyString() {
 324                 return call_user_func_array( 'wfMemcKey', $this->cacheKey );
 325         }
 326
 327         public function setCacheKey( array $cacheKey ) {
 328                 $this->cacheKey = $cacheKey;
 329         }
 330
 331         public function purge() {
 332                 $this->hasCached = false;
 333         }
 334
 335         public function setOnInitializedHandler( $handlerFunction ) {
 336                 $this->onInitHandler = $handlerFunction;
 337         }
 338
 339 }