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  * 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 SpecialPage
  37  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  38  * @since 1.20
  39  */
  40 abstract class SpecialCachedPage extends SpecialPage 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 bool
  56          */
  57         protected $cacheEnabled = true;
  58
  59         /**
  60          * Gets called after @see SpecialPage::execute.
  61          *
  62          * @since 1.20
  63          *
  64          * @param string|null $subPage
  65          */
  66         protected function afterExecute( $subPage ) {
  67                 $this->saveCache();
  68
  69                 parent::afterExecute( $subPage );
  70         }
  71
  72         /**
  73          * Sets if the cache should be enabled or not.
  74          *
  75          * @since 1.20
  76          * @param bool $cacheEnabled
  77          */
  78         public function setCacheEnabled( $cacheEnabled ) {
  79                 $this->cacheHelper->setCacheEnabled( $cacheEnabled );
  80         }
  81
  82         /**
  83          * Initializes the caching.
  84          * Should be called before the first time anything is added via addCachedHTML.
  85          *
  86          * @since 1.20
  87          *
  88          * @param int|null $cacheExpiry Sets the cache expiry, either ttl in seconds or unix timestamp.
  89          * @param bool|null $cacheEnabled Sets if the cache should be enabled or not.
  90          */
  91         public function startCache( $cacheExpiry = null, $cacheEnabled = null ) {
  92                 if ( !isset( $this->cacheHelper ) ) {
  93                         $this->cacheHelper = new CacheHelper();
  94
  95                         $this->cacheHelper->setCacheEnabled( $this->cacheEnabled );
  96                         $this->cacheHelper->setOnInitializedHandler( array( $this, 'onCacheInitialized' ) );
  97
  98                         $keyArgs = $this->getCacheKey();
  99
 100                         if ( array_key_exists( 'action', $keyArgs ) && $keyArgs['action'] === 'purge' ) {
 101                                 unset( $keyArgs['action'] );
 102                         }
 103
 104                         $this->cacheHelper->setCacheKey( $keyArgs );
 105
 106                         if ( $this->getRequest()->getText( 'action' ) === 'purge' ) {
 107                                 $this->cacheHelper->rebuildOnDemand();
 108                         }
 109                 }
 110
 111                 $this->cacheHelper->startCache( $cacheExpiry, $cacheEnabled );
 112         }
 113
 114         /**
 115          * Get a cached value if available or compute it if not and then cache it if possible.
 116          * The provided $computeFunction is only called when the computation needs to happen
 117          * and should return a result value. $args are arguments that will be passed to the
 118          * compute function when called.
 119          *
 120          * @since 1.20
 121          *
 122          * @param callable $computeFunction
 123          * @param array|mixed $args
 124          * @param string|null $key
 125          *
 126          * @return mixed
 127          */
 128         public function getCachedValue( $computeFunction, $args = array(), $key = null ) {
 129                 return $this->cacheHelper->getCachedValue( $computeFunction, $args, $key );
 130         }
 131
 132         /**
 133          * Add some HTML to be cached.
 134          * This is done by providing a callback function that should
 135          * return the HTML to be added. It will only be called if the
 136          * item is not in the cache yet or when the cache has been invalidated.
 137          *
 138          * @since 1.20
 139          *
 140          * @param callable $computeFunction
 141          * @param array $args
 142          * @param string|null $key
 143          */
 144         public function addCachedHTML( $computeFunction, $args = array(), $key = null ) {
 145                 $this->getOutput()->addHTML( $this->cacheHelper->getCachedValue( $computeFunction, $args, $key ) );
 146         }
 147
 148         /**
 149          * Saves the HTML to the cache in case it got recomputed.
 150          * Should be called after the last time anything is added via addCachedHTML.
 151          *
 152          * @since 1.20
 153          */
 154         public function saveCache() {
 155                 if ( isset( $this->cacheHelper ) ) {
 156                         $this->cacheHelper->saveCache();
 157                 }
 158         }
 159
 160         /**
 161          * Sets the time to live for the cache, in seconds or a unix timestamp indicating the point of expiry.
 162          *
 163          * @since 1.20
 164          *
 165          * @param int $cacheExpiry
 166          */
 167         public function setExpiry( $cacheExpiry ) {
 168                 $this->cacheHelper->setExpiry( $cacheExpiry );
 169         }
 170
 171         /**
 172          * Returns the variables used to constructed the cache key in an array.
 173          *
 174          * @since 1.20
 175          *
 176          * @return array
 177          */
 178         protected function getCacheKey() {
 179                 return array(
 180                         $this->mName,
 181                         $this->getLanguage()->getCode()
 182                 );
 183         }
 184
 185         /**
 186          * Gets called after the cache got initialized.
 187          *
 188          * @since 1.20
 189          *
 190          * @param bool $hasCached
 191          */
 192         public function onCacheInitialized( $hasCached ) {
 193                 if ( $hasCached ) {
 194                         $this->getOutput()->setSubtitle( $this->cacheHelper->getCachedNotice( $this->getContext() ) );
 195                 }
 196         }
 197 }