From 18d15fa138fd2b1241ea1d417293ec40bae46849 Mon Sep 17 00:00:00 2001
From: Jackmcbarn <jackmcbarn@gmail.com>
Date: Wed, 28 May 2014 16:17:41 -0400
Subject: [PATCH] Add PPFrame::getTTL() and setTTL()

Add functions to frames to control the TTL of their output, and expose
this via expandtemplates in the API.

Bug: 49803
Change-Id: I412febf3469503bf4839fb1ef4dca098a8c79457
---
 includes/api/ApiExpandTemplates.php   | 15 +++++++++++++--
 includes/parser/Preprocessor.php      | 25 +++++++++++++++++++++++++
 includes/parser/Preprocessor_DOM.php  | 26 ++++++++++++++++++++++++++
 includes/parser/Preprocessor_Hash.php | 26 ++++++++++++++++++++++++++
 4 files changed, 90 insertions(+), 2 deletions(-)

diff --git a/includes/api/ApiExpandTemplates.php b/includes/api/ApiExpandTemplates.php
index e3be4e0d29..eb3f87cb56 100644
--- a/includes/api/ApiExpandTemplates.php
+++ b/includes/api/ApiExpandTemplates.php
@@ -109,10 +109,13 @@ class ApiExpandTemplates extends ApiBase {
 						$retval['categories'] = $categories_result;
 					}
 				}
-				if ( isset ( $prop['volatile'] ) && $frame->isVolatile() ) {
+				if ( isset( $prop['volatile'] ) && $frame->isVolatile() ) {
 					$retval['volatile'] = '';
 				}
-				if ( isset ( $prop['wikitext'] ) ) {
+				if ( isset( $prop['ttl'] ) && $frame->getTTL() !== null ) {
+					$retval['ttl'] = $frame->getTTL();
+				}
+				if ( isset( $prop['wikitext'] ) ) {
 					$retval['wikitext'] = $wikitext;
 				}
 			}
@@ -135,6 +138,7 @@ class ApiExpandTemplates extends ApiBase {
 					'wikitext',
 					'categories',
 					'volatile',
+					'ttl',
 					'parsetree',
 				),
 				ApiBase::PARAM_ISMULTI => true,
@@ -156,6 +160,7 @@ class ApiExpandTemplates extends ApiBase {
 				' wikitext   - The expanded wikitext',
 				' categories - Any categories present in the input that are not represented in the wikitext output',
 				' volatile   - Whether the output is volatile and should not be reused elsewhere within the page',
+				' ttl        - The maximum time after which caches of the result should be invalidated',
 				' parsetree  - The XML parse tree of the input',
 				'Note that if no values are selected, the result will contain the wikitext,',
 				'but the output will be in a deprecated format.',
@@ -182,6 +187,12 @@ class ApiExpandTemplates extends ApiBase {
 					ApiBase::PROP_NULLABLE => true,
 				),
 			),
+			'ttl' => array(
+				'ttl' => array(
+					ApiBase::PROP_TYPE => 'integer',
+					ApiBase::PROP_NULLABLE => true,
+				),
+			),
 			'parsetree' => array(
 				'parsetree' => 'string',
 			),
diff --git a/includes/parser/Preprocessor.php b/includes/parser/Preprocessor.php
index e7ccd104e8..dd5fc4fc47 100644
--- a/includes/parser/Preprocessor.php
+++ b/includes/parser/Preprocessor.php
@@ -189,6 +189,31 @@ interface PPFrame {
 	 */
 	function isVolatile();
 
+	/**
+	 * Get the TTL of the frame's output.
+	 *
+	 * This is the maximum amount of time, in seconds, that this frame's
+	 * output should be cached for. A value of null indicates that no
+	 * maximum has been specified.
+	 *
+	 * Note that this TTL only applies to caching frames as parts of pages.
+	 * It is not relevant to caching the entire rendered output of a page.
+	 *
+	 * @return int|null
+	 */
+	function getTTL();
+
+	/**
+	 * Set the TTL of the output of this frame and all of its ancestors.
+	 * Has no effect if the new TTL is greater than the one already set.
+	 * Note that it is the caller's responsibility to change the cache
+	 * expiry of the page as a whole, if such behavior is desired.
+	 *
+	 * @see self::getTTL()
+	 * @param int $ttl
+	 */
+	function setTTL( $ttl );
+
 	/**
 	 * Get a title of frame
 	 *
diff --git a/includes/parser/Preprocessor_DOM.php b/includes/parser/Preprocessor_DOM.php
index dbbeddbf8c..90af670d76 100644
--- a/includes/parser/Preprocessor_DOM.php
+++ b/includes/parser/Preprocessor_DOM.php
@@ -984,6 +984,7 @@ class PPFrame_DOM implements PPFrame {
 	var $depth;
 
 	private $volatile = false;
+	private $ttl = null;
 
 	/**
 	 * @var array
@@ -1505,6 +1506,26 @@ class PPFrame_DOM implements PPFrame {
 	function isVolatile() {
 		return $this->volatile;
 	}
+
+	/**
+	 * Set the TTL
+	 *
+	 * @param int $ttl
+	 */
+	function setTTL( $ttl ) {
+		if ( $ttl !== null && ( $this->ttl === null || $ttl < $this->ttl ) ) {
+			$this->ttl = $ttl;
+		}
+	}
+
+	/**
+	 * Get the TTL
+	 *
+	 * @return int|null
+	 */
+	function getTTL() {
+		return $this->ttl;
+	}
 }
 
 /**
@@ -1664,6 +1685,11 @@ class PPTemplateFrame_DOM extends PPFrame_DOM {
 		parent::setVolatile( $flag );
 		$this->parent->setVolatile( $flag );
 	}
+
+	function setTTL( $ttl ) {
+		parent::setTTL( $ttl );
+		$this->parent->setTTL( $ttl );
+	}
 }
 
 /**
diff --git a/includes/parser/Preprocessor_Hash.php b/includes/parser/Preprocessor_Hash.php
index ad61eec91f..bc2b68658f 100644
--- a/includes/parser/Preprocessor_Hash.php
+++ b/includes/parser/Preprocessor_Hash.php
@@ -920,6 +920,7 @@ class PPFrame_Hash implements PPFrame {
 	var $depth;
 
 	private $volatile = false;
+	private $ttl = null;
 
 	/**
 	 * @var array
@@ -1410,6 +1411,26 @@ class PPFrame_Hash implements PPFrame {
 	function isVolatile() {
 		return $this->volatile;
 	}
+
+	/**
+	 * Set the TTL
+	 *
+	 * @param int $ttl
+	 */
+	function setTTL( $ttl ) {
+		if ( $ttl !== null && ( $this->ttl === null || $ttl < $this->ttl ) ) {
+			$this->ttl = $ttl;
+		}
+	}
+
+	/**
+	 * Get the TTL
+	 *
+	 * @return int|null
+	 */
+	function getTTL() {
+		return $this->ttl;
+	}
 }
 
 /**
@@ -1585,6 +1606,11 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
 		parent::setVolatile( $flag );
 		$this->parent->setVolatile( $flag );
 	}
+
+	function setTTL( $ttl ) {
+		parent::setTTL( $ttl );
+		$this->parent->setTTL( $ttl );
+	}
 }
 
 /**
-- 
2.20.1