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