includes/actions/CachedAction.php

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