includes/specials/SpecialCachedPage.php

   1 <?php
   2
   3 /**
   4  * Abstract special page class with scaffolding for caching HTML and other values
   5  * in a single blob.
   6  *
   7  * Before using any of the caching functionality, call startCache.
   8  * After the last call to either getCachedValue or addCachedHTML, call saveCache.
   9  *
  10  * To get a cached value or compute it, use getCachedValue like this:
  11  * $this->getCachedValue( $callback );
  12  *
  13  * To add HTML that should be cached, use addCachedHTML like this:
  14  * $this->addCachedHTML( $callback );
  15  *
  16  * The callback function is only called when needed, so do all your expensive
  17  * computations here. This function should returns the HTML to be cached.
  18  * It should not add anything to the PageOutput object!
  19  *
  20  * @since 1.20
  21  *
  22  * @file SpecialCachedPage.php
  23  * @ingroup SpecialPage
  24  *
  25  * @licence GNU GPL v2 or later
  26  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  27  */
  28 abstract class SpecialCachedPage extends SpecialPage implements ICacheHelper {
  29
  30         /**
  31          * CacheHelper object to which we forward the non-SpecialPage specific caching work.
  32          * Initialized in startCache.
  33          *
  34          * @since 1.20
  35          * @var CacheHelper
  36          */
  37         protected $cacheHelper;
  38
  39         /**
  40          * If the cache is enabled or not.
  41          *
  42          * @since 1.20
  43          * @var boolean
  44          */
  45         protected $cacheEnabled = true;
  46
  47         /**
  48          * Sets if the cache should be enabled or not.
  49          *
  50          * @since 1.20
  51          * @param boolean $cacheEnabled
  52          */
  53         public function setCacheEnabled( $cacheEnabled ) {
  54                 $this->cacheHelper->setCacheEnabled( $cacheEnabled );
  55         }
  56
  57         /**
  58          * Initializes the caching.
  59          * Should be called before the first time anything is added via addCachedHTML.
  60          *
  61          * @since 1.20
  62          *
  63          * @param integer|null $cacheExpiry Sets the cache expiry, either ttl in seconds or unix timestamp.
  64          * @param boolean|null $cacheEnabled Sets if the cache should be enabled or not.
  65          */
  66         public function startCache( $cacheExpiry = null, $cacheEnabled = null ) {
  67                 $this->cacheHelper = new CacheHelper();
  68
  69                 $this->cacheHelper->setCacheEnabled( $this->cacheEnabled );
  70                 $this->cacheHelper->setOnInitializedHandler( array( $this, 'onCacheInitialized' ) );
  71
  72                 $keyArgs = $this->getCacheKey();
  73
  74                 if ( array_key_exists( 'action', $keyArgs ) && $keyArgs['action'] === 'purge' ) {
  75                         unset( $keyArgs['action'] );
  76                 }
  77
  78                 $this->cacheHelper->setCacheKey( $keyArgs );
  79
  80                 if ( $this->getRequest()->getText( 'action' ) === 'purge' ) {
  81                         $this->cacheHelper->rebuildOnDemand();
  82                 }
  83
  84                 $this->cacheHelper->startCache( $cacheExpiry, $cacheEnabled );
  85         }
  86
  87         /**
  88          * Get a cached value if available or compute it if not and then cache it if possible.
  89          * The provided $computeFunction is only called when the computation needs to happen
  90          * and should return a result value. $args are arguments that will be passed to the
  91          * compute function when called.
  92          *
  93          * @since 1.20
  94          *
  95          * @param {function} $computeFunction
  96          * @param array|mixed $args
  97          * @param string|null $key
  98          *
  99          * @return mixed
 100          */
 101         public function getCachedValue( $computeFunction, $args = array(), $key = null ) {
 102                 return $this->cacheHelper->getCachedValue( $computeFunction, $args, $key );
 103         }
 104
 105         /**
 106          * Add some HTML to be cached.
 107          * This is done by providing a callback function that should
 108          * return the HTML to be added. It will only be called if the
 109          * item is not in the cache yet or when the cache has been invalidated.
 110          *
 111          * @since 1.20
 112          *
 113          * @param {function} $computeFunction
 114          * @param array $args
 115          * @param string|null $key
 116          */
 117         public function addCachedHTML( $computeFunction, $args = array(), $key = null ) {
 118                 $this->getOutput()->addHTML( $this->cacheHelper->getCachedValue( $computeFunction, $args, $key ) );
 119         }
 120
 121         /**
 122          * Saves the HTML to the cache in case it got recomputed.
 123          * Should be called after the last time anything is added via addCachedHTML.
 124          *
 125          * @since 1.20
 126          */
 127         public function saveCache() {
 128                 $this->cacheHelper->saveCache();
 129         }
 130
 131         /**
 132          * Sets the time to live for the cache, in seconds or a unix timestamp indicating the point of expiry.
 133          *
 134          * @since 1.20
 135          *
 136          * @param integer $cacheExpiry
 137          */
 138         public function setExpiry( $cacheExpiry ) {
 139                 $this->cacheHelper->setExpiry( $cacheExpiry );
 140         }
 141
 142         /**
 143          * Returns the variables used to constructed the cache key in an array.
 144          *
 145          * @since 1.20
 146          *
 147          * @return array
 148          */
 149         protected function getCacheKey() {
 150                 return array(
 151                         $this->mName,
 152                         $this->getLanguage()->getCode()
 153                 );
 154         }
 155
 156         /**
 157          * Gets called after the cache got initialized.
 158          *
 159          * @since 1.20
 160          *
 161          * @param boolean $hasCached
 162          */
 163         public function onCacheInitialized( $hasCached ) {
 164                 if ( $hasCached ) {
 165                         $this->getOutput()->setSubtitle( $this->cacheHelper->getCachedNotice( $this->getContext() ) );
 166                 }
 167         }
 168
 169 }