3 * Cache for outputs of the PHP parser
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
21 * @ingroup Cache Parser
24 use MediaWiki\MediaWikiServices
;
27 * @ingroup Cache Parser
32 * Constants for self::getKey()
36 /** Use only current data */
37 const USE_CURRENT_ONLY
= 0;
39 /** Use expired data if current data is unavailable */
40 const USE_EXPIRED
= 1;
42 /** Use expired data or data from different revisions if current data is unavailable */
43 const USE_OUTDATED
= 2;
46 * Use expired data and data from different revisions, and if all else
47 * fails vary on all variable options
49 const USE_ANYTHING
= 3;
55 * Anything cached prior to this is invalidated
62 * Get an instance of this object
64 * @deprecated since 1.30, use MediaWikiServices instead
67 public static function singleton() {
68 return MediaWikiServices
::getInstance()->getParserCache();
72 * Setup a cache pathway with a given back-end storage mechanism.
74 * This class use an invalidation strategy that is compatible with
75 * MultiWriteBagOStuff in async replication mode.
77 * @param BagOStuff $cache
78 * @param string $cacheEpoch Anything before this timestamp is invalidated
81 public function __construct( BagOStuff
$cache, $cacheEpoch = '20030516000000' ) {
82 $this->cache
= $cache;
83 $this->cacheEpoch
= $cacheEpoch;
87 * @param WikiPage $article
89 * @return mixed|string
91 protected function getParserOutputKey( $article, $hash ) {
94 // idhash seem to mean 'page id' + 'rendering hash' (r3710)
95 $pageid = $article->getId();
96 $renderkey = (int)( $wgRequest->getVal( 'action' ) == 'render' );
98 $key = $this->cache
->makeKey( 'pcache', 'idhash', "{$pageid}-{$renderkey}!{$hash}" );
103 * @param WikiPage $page
104 * @return mixed|string
106 protected function getOptionsKey( $page ) {
107 return $this->cache
->makeKey( 'pcache', 'idoptions', $page->getId() );
111 * @param WikiPage $page
114 public function deleteOptionsKey( $page ) {
115 $this->cache
->delete( $this->getOptionsKey( $page ) );
119 * Provides an E-Tag suitable for the whole page. Note that $article
120 * is just the main wikitext. The E-Tag has to be unique to the whole
121 * page, even if the article itself is the same, so it uses the
122 * complete set of user options. We don't want to use the preference
123 * of a different user on a message just because it wasn't used in
124 * $article. For example give a Chinese interface to a user with
125 * English preferences. That's why we take into account *all* user
126 * options. (r70809 CR)
128 * @param WikiPage $article
129 * @param ParserOptions $popts
132 public function getETag( $article, $popts ) {
133 return 'W/"' . $this->getParserOutputKey( $article,
134 $popts->optionsHash( ParserOptions
::allCacheVaryingOptions(), $article->getTitle() ) ) .
135 "--" . $article->getTouched() . '"';
139 * Retrieve the ParserOutput from ParserCache, even if it's outdated.
140 * @param WikiPage $article
141 * @param ParserOptions $popts
142 * @return ParserOutput|bool False on failure
144 public function getDirty( $article, $popts ) {
145 $value = $this->get( $article, $popts, true );
146 return is_object( $value ) ?
$value : false;
150 * @param WikiPage $article
151 * @param string $metricSuffix
153 private function incrementStats( $article, $metricSuffix ) {
154 // old style global metric (can be removed once no longer used)
155 wfIncrStats( 'pcache.' . $metricSuffix );
156 // new per content model metric
157 $contentModel = str_replace( '.', '_', $article->getContentModel() );
158 $metricSuffix = str_replace( '.', '_', $metricSuffix );
159 wfIncrStats( 'pcache.' . $contentModel . '.' . $metricSuffix );
163 * Generates a key for caching the given article considering
164 * the given parser options.
166 * @note Which parser options influence the cache key
167 * is controlled via ParserOutput::recordOption() or
168 * ParserOptions::addExtraKey().
170 * @note Used by Article to provide a unique id for the PoolCounter.
171 * It would be preferable to have this code in get()
172 * instead of having Article looking in our internals.
174 * @param WikiPage $article
175 * @param ParserOptions $popts
176 * @param int|bool $useOutdated One of the USE constants. For backwards
177 * compatibility, boolean false is treated as USE_CURRENT_ONLY and
178 * boolean true is treated as USE_ANYTHING.
179 * @return bool|mixed|string
180 * @since 1.30 Changed $useOutdated to an int and added the non-boolean values
182 public function getKey( $article, $popts, $useOutdated = self
::USE_ANYTHING
) {
183 if ( is_bool( $useOutdated ) ) {
184 $useOutdated = $useOutdated ? self
::USE_ANYTHING
: self
::USE_CURRENT_ONLY
;
187 if ( $popts instanceof User
) {
188 wfWarn( "Use of outdated prototype ParserCache::getKey( &\$article, &\$user )\n" );
189 $popts = ParserOptions
::newFromUser( $popts );
192 // Determine the options which affect this article
193 $optionsKey = $this->cache
->get(
194 $this->getOptionsKey( $article ), BagOStuff
::READ_VERIFIED
);
195 if ( $optionsKey instanceof CacheTime
) {
196 if ( $useOutdated < self
::USE_EXPIRED
&& $optionsKey->expired( $article->getTouched() ) ) {
197 $this->incrementStats( $article, "miss.expired" );
198 $cacheTime = $optionsKey->getCacheTime();
199 wfDebugLog( "ParserCache",
200 "Parser options key expired, touched " . $article->getTouched()
201 . ", epoch {$this->cacheEpoch}, cached $cacheTime\n" );
203 } elseif ( $useOutdated < self
::USE_OUTDATED
&&
204 $optionsKey->isDifferentRevision( $article->getLatest() )
206 $this->incrementStats( $article, "miss.revid" );
207 $revId = $article->getLatest();
208 $cachedRevId = $optionsKey->getCacheRevisionId();
209 wfDebugLog( "ParserCache",
210 "ParserOutput key is for an old revision, latest $revId, cached $cachedRevId\n"
215 // $optionsKey->mUsedOptions is set by save() by calling ParserOutput::getUsedOptions()
216 $usedOptions = $optionsKey->mUsedOptions
;
217 wfDebug( "Parser cache options found.\n" );
219 if ( $useOutdated < self
::USE_ANYTHING
) {
222 $usedOptions = ParserOptions
::allCacheVaryingOptions();
225 return $this->getParserOutputKey(
227 $popts->optionsHash( $usedOptions, $article->getTitle() )
232 * Retrieve the ParserOutput from ParserCache.
233 * false if not found or outdated.
235 * @param WikiPage|Article $article
236 * @param ParserOptions $popts
237 * @param bool $useOutdated (default false)
239 * @return ParserOutput|bool False on failure
241 public function get( $article, $popts, $useOutdated = false ) {
242 $canCache = $article->checkTouched();
244 // It's a redirect now
248 $touched = $article->getTouched();
250 $parserOutputKey = $this->getKey( $article, $popts,
251 $useOutdated ? self
::USE_OUTDATED
: self
::USE_CURRENT_ONLY
253 if ( $parserOutputKey === false ) {
254 $this->incrementStats( $article, 'miss.absent' );
259 /** @var ParserOutput $value */
260 $value = $this->cache
->get( $parserOutputKey, BagOStuff
::READ_VERIFIED
);
262 wfDebug( "ParserOutput cache miss.\n" );
263 $this->incrementStats( $article, "miss.absent" );
267 wfDebug( "ParserOutput cache found.\n" );
269 $wikiPage = method_exists( $article, 'getPage' )
270 ?
$article->getPage()
273 if ( !$useOutdated && $value->expired( $touched ) ) {
274 $this->incrementStats( $article, "miss.expired" );
275 $cacheTime = $value->getCacheTime();
276 wfDebugLog( "ParserCache",
277 "ParserOutput key expired, touched $touched, "
278 . "epoch {$this->cacheEpoch}, cached $cacheTime\n" );
280 } elseif ( !$useOutdated && $value->isDifferentRevision( $article->getLatest() ) ) {
281 $this->incrementStats( $article, "miss.revid" );
282 $revId = $article->getLatest();
283 $cachedRevId = $value->getCacheRevisionId();
284 wfDebugLog( "ParserCache",
285 "ParserOutput key is for an old revision, latest $revId, cached $cachedRevId\n"
289 Hooks
::run( 'RejectParserCacheValue', [ $value, $wikiPage, $popts ] ) === false
291 $this->incrementStats( $article, 'miss.rejected' );
292 wfDebugLog( "ParserCache",
293 "ParserOutput key valid, but rejected by RejectParserCacheValue hook handler.\n"
297 $this->incrementStats( $article, "hit" );
304 * @param ParserOutput $parserOutput
305 * @param WikiPage $page
306 * @param ParserOptions $popts
307 * @param string|null $cacheTime TS_MW timestamp when the cache was generated
308 * @param int|null $revId Revision ID that was parsed
310 public function save(
311 ParserOutput
$parserOutput,
317 if ( !$parserOutput->hasText() ) {
318 throw new InvalidArgumentException( 'Attempt to cache a ParserOutput with no text set!' );
321 $expire = $parserOutput->getCacheExpiry();
322 if ( $expire > 0 && !$this->cache
instanceof EmptyBagOStuff
) {
323 $cacheTime = $cacheTime ?
: wfTimestampNow();
325 $revision = $page->getRevision();
326 $revId = $revision ?
$revision->getId() : null;
329 $optionsKey = new CacheTime
;
330 $optionsKey->mUsedOptions
= $parserOutput->getUsedOptions();
331 $optionsKey->updateCacheExpiry( $expire );
333 $optionsKey->setCacheTime( $cacheTime );
334 $parserOutput->setCacheTime( $cacheTime );
335 $optionsKey->setCacheRevisionId( $revId );
336 $parserOutput->setCacheRevisionId( $revId );
338 $parserOutputKey = $this->getParserOutputKey( $page,
339 $popts->optionsHash( $optionsKey->mUsedOptions
, $page->getTitle() ) );
341 // Save the timestamp so that we don't have to load the revision row on view
342 $parserOutput->setTimestamp( $page->getTimestamp() );
344 $msg = "Saved in parser cache with key $parserOutputKey" .
345 " and timestamp $cacheTime" .
346 " and revision id $revId" .
349 $parserOutput->mText
.= "\n<!-- $msg -->\n";
352 // Save the parser output
357 BagOStuff
::WRITE_ALLOW_SEGMENTS
360 // ...and its pointer
361 $this->cache
->set( $this->getOptionsKey( $page ), $optionsKey, $expire );
364 'ParserCacheSaveComplete',
365 [ $this, $parserOutput, $page->getTitle(), $popts, $revId ]
367 } elseif ( $expire <= 0 ) {
368 wfDebug( "Parser output was marked as uncacheable and has not been saved.\n" );
373 * Get the backend BagOStuff instance that
374 * powers the parser cache
379 public function getCacheStorage() {