1	<?php
2
3	namespace MediaWiki\OutputTransform;
4
5	use MediaWiki\Parser\ParserOutput;
6	use ParserOptions;
7
8	/**
9	* Classes implementing the OutputTransformStage aim at being added to a pipeline of transformations that transform
10	* a ParserOutput. The argument ParserOutput can explicitly be modified in place; ensuring that cached objects
11	* do not suffer from side effects is the caller's (typically the pipeline's) responsibility.
12	* @unstable
13	*/
14	interface OutputTransformStage {
15	/**
16	* Decides whether or not the stage should be run
17	* @param ParserOutput $po
18	* @unstable
19	* @param ParserOptions|null $popts
20	* @param array $options
21	* @return bool
22	*/
23	public function shouldRun( ParserOutput $po, ?ParserOptions $popts, array $options = [] ): bool;
24
25	/**
26	* Transforms the input ParserOutput into the returned ParserOutput.
27	* The returned ParserOutput can explicitly be a modified version of the input ParserOutput; if modifications
28	* to that object are unexpected, a copy should be made before passing it to this method.
29	* TODO Some transformations require the possibility of modifying options (this is the case of
30	* ExecutePostCacheTransformHooks in particular). We do NOT want to keep this mechanism for later versions of
31	* this interface - the currently foreseen goal is to not pass $options at all.
32	* Modifying $options during this pass is considered deprecated.
33	* @unstable
34	*/
35	public function transform( ParserOutput $po, ?ParserOptions $popts, array &$options ): ParserOutput;
36	}