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 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  * This program is free software; you can redistribute it and/or modify
  21  * it under the terms of the GNU General Public License as published by
  22  * the Free Software Foundation; either version 2 of the License, or
  23  * (at your option) any later version.
  24  *
  25  * This program is distributed in the hope that it will be useful,
  26  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  27  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  28  * GNU General Public License for more details.
  29  *
  30  * You should have received a copy of the GNU General Public License along
  31  * with this program; if not, write to the Free Software Foundation, Inc.,
  32  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  33  * http://www.gnu.org/copyleft/gpl.html
  34  *
  35  * @file
  36  * @ingroup Action
  37  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  38  * @since 1.20
  39  */
  40 abstract class CachedAction extends FormlessAction implements ICacheHelper {
  41
  42         /**
  43          * CacheHelper object to which we forward the non-SpecialPage specific caching work.
  44          * Initialized in startCache.
  45          *
  46          * @since 1.20
  47          * @var CacheHelper
  48          */
  49         protected $cacheHelper;
  50
  51         /**
  52          * If the cache is enabled or not.
  53          *
  54          * @since 1.20
  55          * @var boolean
  56          */
  57         protected $cacheEnabled = true;
  58
  59         /**
  60          * Sets if the cache should be enabled or not.
  61          *
  62          * @since 1.20
  63          * @param boolean $cacheEnabled
  64          */
  65         public function setCacheEnabled( $cacheEnabled ) {
  66                 $this->cacheHelper->setCacheEnabled( $cacheEnabled );
  67         }
  68
  69         /**
  70          * Initializes the caching.
  71          * Should be called before the first time anything is added via addCachedHTML.
  72          *
  73          * @since 1.20
  74          *
  75          * @param integer|null $cacheExpiry Sets the cache expiry, either ttl in seconds or unix timestamp.
  76          * @param boolean|null $cacheEnabled Sets if the cache should be enabled or not.
  77          */
  78         public function startCache( $cacheExpiry = null, $cacheEnabled = null ) {
  79                 $this->cacheHelper = new CacheHelper();
  80
  81                 $this->cacheHelper->setCacheEnabled( $this->cacheEnabled );
  82                 $this->cacheHelper->setOnInitializedHandler( array( $this, 'onCacheInitialized' ) );
  83
  84                 $keyArgs = $this->getCacheKey();
  85
  86                 if ( array_key_exists( 'action', $keyArgs ) && $keyArgs['action'] === 'purge' ) {
  87                         unset( $keyArgs['action'] );
  88                 }
  89
  90                 $this->cacheHelper->setCacheKey( $keyArgs );
  91
  92                 if ( $this->getRequest()->getText( 'action' ) === 'purge' ) {
  93                         $this->cacheHelper->rebuildOnDemand();
  94                 }
  95
  96                 $this->cacheHelper->startCache( $cacheExpiry, $cacheEnabled );
  97         }
  98
  99         /**
 100          * Get a cached value if available or compute it if not and then cache it if possible.
 101          * The provided $computeFunction is only called when the computation needs to happen
 102          * and should return a result value. $args are arguments that will be passed to the
 103          * compute function when called.
 104          *
 105          * @since 1.20
 106          *
 107          * @param {function} $computeFunction
 108          * @param array|mixed $args
 109          * @param string|null $key
 110          *
 111          * @return mixed
 112          */
 113         public function getCachedValue( $computeFunction, $args = array(), $key = null ) {
 114                 return $this->cacheHelper->getCachedValue( $computeFunction, $args, $key );
 115         }
 116
 117         /**
 118          * Add some HTML to be cached.
 119          * This is done by providing a callback function that should
 120          * return the HTML to be added. It will only be called if the
 121          * item is not in the cache yet or when the cache has been invalidated.
 122          *
 123          * @since 1.20
 124          *
 125          * @param {function} $computeFunction
 126          * @param array $args
 127          * @param string|null $key
 128          */
 129         public function addCachedHTML( $computeFunction, $args = array(), $key = null ) {
 130                 $this->getOutput()->addHTML( $this->cacheHelper->getCachedValue( $computeFunction, $args, $key ) );
 131         }
 132
 133         /**
 134          * Saves the HTML to the cache in case it got recomputed.
 135          * Should be called after the last time anything is added via addCachedHTML.
 136          *
 137          * @since 1.20
 138          */
 139         public function saveCache() {
 140                 $this->cacheHelper->saveCache();
 141         }
 142
 143         /**
 144          * Sets the time to live for the cache, in seconds or a unix timestamp indicating the point of expiry.
 145          *
 146          * @since 1.20
 147          *
 148          * @param integer $cacheExpiry
 149          */
 150         public function setExpiry( $cacheExpiry ) {
 151                 $this->cacheHelper->setExpiry( $cacheExpiry );
 152         }
 153
 154         /**
 155          * Returns the variables used to constructed the cache key in an array.
 156          *
 157          * @since 1.20
 158          *
 159          * @return array
 160          */
 161         protected function getCacheKey() {
 162                 return array(
 163                         get_class( $this->page ),
 164                         $this->getName(),
 165                         $this->getLanguage()->getCode()
 166                 );
 167         }
 168
 169         /**
 170          * Gets called after the cache got initialized.
 171          *
 172          * @since 1.20
 173          *
 174          * @param boolean $hasCached
 175          */
 176         public function onCacheInitialized( $hasCached ) {
 177                 if ( $hasCached ) {
 178                         $this->getOutput()->setSubtitle( $this->cacheHelper->getCachedNotice( $this->getContext() ) );
 179                 }
 180         }
 181
 182 }