Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 138
0.00% covered (danger)
0.00%
0 / 5
CRAP
0.00% covered (danger)
0.00%
0 / 1
ApiExpandTemplates
0.00% covered (danger)
0.00%
0 / 138
0.00% covered (danger)
0.00%
0 / 5
1406
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
2
 execute
0.00% covered (danger)
0.00%
0 / 99
0.00% covered (danger)
0.00%
0 / 1
1122
 getAllowedParams
0.00% covered (danger)
0.00%
0 / 31
0.00% covered (danger)
0.00%
0 / 1
2
 getExamplesMessages
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
2
 getHelpUrls
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
1<?php
2/**
3 * Copyright © 2007 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
4 *
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.
9 *
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.
14 *
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
19 *
20 * @file
21 */
22
23use MediaWiki\Json\FormatJson;
24use MediaWiki\Parser\Parser;
25use MediaWiki\Revision\RevisionStore;
26use MediaWiki\Title\Title;
27use Wikimedia\ParamValidator\ParamValidator;
28
29/**
30 * API module that functions as a shortcut to the wikitext preprocessor. Expands
31 * any templates in a provided string, and returns the result of this expansion
32 * to the caller.
33 *
34 * @ingroup API
35 */
36class ApiExpandTemplates extends ApiBase {
37    private RevisionStore $revisionStore;
38    private ParserFactory $parserFactory;
39
40    /**
41     * @param ApiMain $main
42     * @param string $action
43     * @param RevisionStore $revisionStore
44     * @param ParserFactory $parserFactory
45     */
46    public function __construct(
47        ApiMain $main,
48        $action,
49        RevisionStore $revisionStore,
50        ParserFactory $parserFactory
51    ) {
52        parent::__construct( $main, $action );
53        $this->revisionStore = $revisionStore;
54        $this->parserFactory = $parserFactory;
55    }
56
57    public function execute() {
58        // Cache may vary on the user because ParserOptions gets data from it
59        $this->getMain()->setCacheMode( 'anon-public-user-private' );
60
61        // Get parameters
62        $params = $this->extractRequestParams();
63        $this->requireMaxOneParameter( $params, 'prop', 'generatexml' );
64
65        $title = $params['title'];
66        if ( $title === null ) {
67            $titleProvided = false;
68            // A title is needed for parsing, so arbitrarily choose one
69            $title = 'API';
70        } else {
71            $titleProvided = true;
72        }
73
74        if ( $params['prop'] === null ) {
75            $this->addDeprecation(
76                [ 'apiwarn-deprecation-missingparam', 'prop' ], 'action=expandtemplates&!prop'
77            );
78            $prop = [];
79        } else {
80            $prop = array_fill_keys( $params['prop'], true );
81        }
82
83        $titleObj = Title::newFromText( $title );
84        if ( !$titleObj || $titleObj->isExternal() ) {
85            $this->dieWithError( [ 'apierror-invalidtitle', wfEscapeWikiText( $params['title'] ) ] );
86        }
87
88        // Get title and revision ID for parser
89        $revid = $params['revid'];
90        if ( $revid !== null ) {
91            $rev = $this->revisionStore->getRevisionById( $revid );
92            if ( !$rev ) {
93                $this->dieWithError( [ 'apierror-nosuchrevid', $revid ] );
94            }
95            $pTitleObj = $titleObj;
96            $titleObj = Title::newFromLinkTarget( $rev->getPageAsLinkTarget() );
97            if ( $titleProvided && !$titleObj->equals( $pTitleObj ) ) {
98                $this->addWarning( [ 'apierror-revwrongpage', $rev->getId(),
99                    wfEscapeWikiText( $pTitleObj->getPrefixedText() ) ] );
100            }
101        }
102
103        $result = $this->getResult();
104
105        // Parse text
106        $options = ParserOptions::newFromContext( $this->getContext() );
107
108        if ( $params['includecomments'] ) {
109            $options->setRemoveComments( false );
110        }
111
112        $reset = null;
113        $suppressCache = false;
114        $this->getHookRunner()->onApiMakeParserOptions(
115            $options, $titleObj, $params, $this, $reset, $suppressCache );
116
117        $retval = [];
118
119        if ( isset( $prop['parsetree'] ) || $params['generatexml'] ) {
120            $parser = $this->parserFactory->getInstance();
121            $parser->startExternalParse( $titleObj, $options, Parser::OT_PREPROCESS );
122            $dom = $parser->preprocessToDom( $params['text'] );
123            // @phan-suppress-next-line PhanUndeclaredMethodInCallable
124            if ( is_callable( [ $dom, 'saveXML' ] ) ) {
125                // @phan-suppress-next-line PhanUndeclaredMethod
126                $xml = $dom->saveXML();
127            } else {
128                // @phan-suppress-next-line PhanUndeclaredMethod
129                $xml = $dom->__toString();
130            }
131            if ( isset( $prop['parsetree'] ) ) {
132                unset( $prop['parsetree'] );
133                $retval['parsetree'] = $xml;
134            } else {
135                // the old way
136                $result->addValue( null, 'parsetree', $xml );
137                $result->addValue( null, ApiResult::META_BC_SUBELEMENTS, [ 'parsetree' ] );
138            }
139        }
140
141        // if they didn't want any output except (probably) the parse tree,
142        // then don't bother actually fully expanding it
143        if ( $prop || $params['prop'] === null ) {
144            $parser = $this->parserFactory->getInstance();
145            $parser->startExternalParse( $titleObj, $options, Parser::OT_PREPROCESS );
146            $frame = $parser->getPreprocessor()->newFrame();
147            $wikitext = $parser->preprocess( $params['text'], $titleObj, $options, $revid, $frame );
148            if ( $params['prop'] === null ) {
149                // the old way
150                ApiResult::setContentValue( $retval, 'wikitext', $wikitext );
151            } else {
152                $p_output = $parser->getOutput();
153                if ( isset( $prop['categories'] ) ) {
154                    $categories = $p_output->getCategoryNames();
155                    if ( $categories ) {
156                        $defaultSortKey = $p_output->getPageProperty( 'defaultsort' ) ?? '';
157                        $categories_result = [];
158                        foreach ( $categories as $category ) {
159                            $entry = [
160                                // Note that ::getCategorySortKey() returns
161                                // the empty string '' to mean
162                                // "use the default sort key"
163                                'sortkey' => $p_output->getCategorySortKey( $category ) ?: $defaultSortKey,
164                            ];
165                            ApiResult::setContentValue( $entry, 'category', $category );
166                            $categories_result[] = $entry;
167                        }
168                        ApiResult::setIndexedTagName( $categories_result, 'category' );
169                        $retval['categories'] = $categories_result;
170                    }
171                }
172                if ( isset( $prop['properties'] ) ) {
173                    $properties = $p_output->getPageProperties();
174                    if ( $properties ) {
175                        ApiResult::setArrayType( $properties, 'BCkvp', 'name' );
176                        ApiResult::setIndexedTagName( $properties, 'property' );
177                        $retval['properties'] = $properties;
178                    }
179                }
180                if ( isset( $prop['volatile'] ) ) {
181                    $retval['volatile'] = $frame->isVolatile();
182                }
183                if ( isset( $prop['ttl'] ) && $frame->getTTL() !== null ) {
184                    $retval['ttl'] = $frame->getTTL();
185                }
186                if ( isset( $prop['wikitext'] ) ) {
187                    $retval['wikitext'] = $wikitext;
188                }
189                if ( isset( $prop['modules'] ) ) {
190                    $retval['modules'] = array_values( array_unique( $p_output->getModules() ) );
191                    // Deprecated since 1.32 (T188689)
192                    $retval['modulescripts'] = [];
193                    $retval['modulestyles'] = array_values( array_unique( $p_output->getModuleStyles() ) );
194                }
195                if ( isset( $prop['jsconfigvars'] ) ) {
196                    $showStrategyKeys = (bool)( $params['showstrategykeys'] );
197                    $retval['jsconfigvars'] =
198                        ApiResult::addMetadataToResultVars( $p_output->getJsConfigVars( $showStrategyKeys ) );
199                }
200                if ( isset( $prop['encodedjsconfigvars'] ) ) {
201                    $retval['encodedjsconfigvars'] = FormatJson::encode(
202                        $p_output->getJsConfigVars(), false, FormatJson::ALL_OK
203                    );
204                    $retval[ApiResult::META_SUBELEMENTS][] = 'encodedjsconfigvars';
205                }
206                if ( isset( $prop['modules'] ) &&
207                    !isset( $prop['jsconfigvars'] ) && !isset( $prop['encodedjsconfigvars'] ) ) {
208                    $this->addWarning( 'apiwarn-moduleswithoutvars' );
209                }
210            }
211        }
212        ApiResult::setSubelementsList( $retval, [ 'wikitext', 'parsetree' ] );
213        $result->addValue( null, $this->getModuleName(), $retval );
214    }
215
216    public function getAllowedParams() {
217        return [
218            'title' => null,
219            'text' => [
220                ParamValidator::PARAM_TYPE => 'text',
221                ParamValidator::PARAM_REQUIRED => true,
222            ],
223            'revid' => [
224                ParamValidator::PARAM_TYPE => 'integer',
225            ],
226            'prop' => [
227                ParamValidator::PARAM_TYPE => [
228                    'wikitext',
229                    'categories',
230                    'properties',
231                    'volatile',
232                    'ttl',
233                    'modules',
234                    'jsconfigvars',
235                    'encodedjsconfigvars',
236                    'parsetree',
237                ],
238                ParamValidator::PARAM_ISMULTI => true,
239                ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
240            ],
241            'includecomments' => false,
242            'showstrategykeys' => false,
243            'generatexml' => [
244                ParamValidator::PARAM_TYPE => 'boolean',
245                ParamValidator::PARAM_DEPRECATED => true,
246            ],
247        ];
248    }
249
250    protected function getExamplesMessages() {
251        return [
252            'action=expandtemplates&text={{Project:Sandbox}}'
253                => 'apihelp-expandtemplates-example-simple',
254        ];
255    }
256
257    public function getHelpUrls() {
258        return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Expandtemplates';
259    }
260}