Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
12.50% covered (danger)
12.50%
19 / 152
33.33% covered (danger)
33.33%
2 / 6
CRAP
0.00% covered (danger)
0.00%
0 / 1
ExtensionHandler
12.50% covered (danger)
12.50%
19 / 152
33.33% covered (danger)
33.33%
2 / 6
762.54
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 normalizeExtOptions
100.00% covered (success)
100.00%
14 / 14
100.00% covered (success)
100.00%
1 / 1
5
 onExtension
0.00% covered (danger)
0.00%
0 / 81
0.00% covered (danger)
0.00%
0 / 1
240
 onDocumentFragment
0.00% covered (danger)
0.00%
0 / 50
0.00% covered (danger)
0.00%
0 / 1
72
 onTag
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
6
 stripAnnotations
100.00% covered (success)
100.00%
5 / 5
100.00% covered (success)
100.00%
1 / 1
2
1<?php
2declare( strict_types = 1 );
3
4namespace Wikimedia\Parsoid\Wt2Html\TT;
5
6use Wikimedia\Assert\Assert;
7use Wikimedia\Parsoid\Config\SiteConfig;
8use Wikimedia\Parsoid\DOM\DocumentFragment;
9use Wikimedia\Parsoid\DOM\Element;
10use Wikimedia\Parsoid\Ext\ExtensionError;
11use Wikimedia\Parsoid\Ext\ExtensionTag;
12use Wikimedia\Parsoid\Ext\ParsoidExtensionAPI;
13use Wikimedia\Parsoid\Fragments\WikitextPFragment;
14use Wikimedia\Parsoid\NodeData\DataMw;
15use Wikimedia\Parsoid\NodeData\DataMwError;
16use Wikimedia\Parsoid\Tokens\Token;
17use Wikimedia\Parsoid\Tokens\XMLTagTk;
18use Wikimedia\Parsoid\Utils\DOMDataUtils;
19use Wikimedia\Parsoid\Utils\DOMUtils;
20use Wikimedia\Parsoid\Utils\PipelineUtils;
21use Wikimedia\Parsoid\Utils\TokenUtils;
22use Wikimedia\Parsoid\Utils\Utils;
23use Wikimedia\Parsoid\Utils\WTUtils;
24use Wikimedia\Parsoid\Wt2Html\TokenHandlerPipeline;
25
26class ExtensionHandler extends XMLTagBasedHandler {
27
28    public function __construct( TokenHandlerPipeline $manager, array $options ) {
29        parent::__construct( $manager, $options );
30    }
31
32    private static function normalizeExtOptions( array $options, string $defaultNorm, array $exceptions ): array {
33        // Mimics Sanitizer::decodeTagAttributes from the PHP parser
34        //
35        // Extension options should always be interpreted as plain text. The
36        // tokenizer parses them to tokens in case they are for an HTML tag,
37        // but here we use the text source instead.
38        $n = count( $options );
39        for ( $i = 0; $i < $n; $i++ ) {
40            $o = $options[$i];
41            // Use the source if present. If not use the value, but ensure it's a
42            // string, as it can be a token stream if the parser has recognized it
43            // as a directive.
44            $v = $o->vsrc ?? TokenUtils::tokensToString( $o->v, false, [ 'includeEntities' => true ] );
45
46            if ( is_string( $o->k ) ) {
47                $normalizeFlag = $exceptions[$o->k] ?? $defaultNorm;
48            } else {
49                $normalizeFlag = $defaultNorm;
50            }
51
52            // Let extensions decide which format they want their options in; by default they are interpreted as
53            // with normalized spaces and trimmed.
54            if ( $normalizeFlag === 'keepspaces' ) {
55                $o->v = $v;
56            } elseif ( $normalizeFlag === 'trim' ) {
57                $o->v = trim( $v );
58            } else {
59                $o->v = trim( preg_replace( '/[\r\n\t ]+/', ' ', $v ) );
60            }
61
62            // Decode character references
63            $o->v = Utils::decodeWtEntities( $o->v );
64        }
65        return $options;
66    }
67
68    /**
69     * @return array<string|Token>
70     */
71    private function onExtension( Token $token ): array {
72        $env = $this->env;
73        $siteConfig = $env->getSiteConfig();
74        $extensionName = $token->getAttributeV( 'name' );
75        $extConfig = $env->getSiteConfig()->getExtTagConfig( $extensionName );
76
77        $metrics = $siteConfig->metrics();
78        if ( $metrics ) {
79            // Track uses of extensions
80            $wiki = $siteConfig->iwp();
81            $ns = $env->getContextTitle()->getNamespace();
82            if ( $ns === 0 ) {
83                // Article space
84                $nsName = 'main';
85            } elseif ( $siteConfig->namespaceIsTalk( $ns ) ) {
86                // Any talk namespace
87                $nsName = 'talk';
88            } else {
89                // Everything else
90                $nsName = "ns-$ns";
91            }
92            $metrics->increment( "extension.{$wiki}.{$nsName}.{$extensionName}" );
93            $siteConfig->incrementCounter( "extension_total", [
94                "wiki" => $wiki,
95                "namespace" => $nsName,
96                "name" => $extensionName,
97            ] );
98        }
99
100        $nativeExt = $siteConfig->getExtTagImpl( $extensionName );
101        $options = $token->getAttributeV( 'options' );
102        $normalizeFlag = $extConfig['options']['wt2html']['attributeWSNormalizationDefault'] ?? 'normalize';
103        $normalizeExceptions = $extConfig['options']['wt2html']['attributeWSNormalization'] ?? [];
104        $token->setAttribute( 'options', self::normalizeExtOptions( $options, $normalizeFlag, $normalizeExceptions ) );
105
106        // Call after normalizing extension options, since that can affect the result
107        $dataMw = Utils::getExtArgInfo( $token );
108
109        $extApi = new ParsoidExtensionAPI( $env, [
110            'wt2html' => [
111                'frame' => $this->manager->getFrame(),
112                'parseOpts' => $this->options,
113                'extTag' => new ExtensionTag( $token ),
114            ],
115        ] );
116        if ( $nativeExt !== null ) {
117            $extArgs = $token->getAttributeV( 'options' );
118            try {
119                $extSrc = $dataMw->body->extsrc ?? '';
120                if ( !( $extConfig['options']['hasWikitextInput'] ?? true ) ) {
121                    $extSrc = $this->stripAnnotations( $extSrc, $env->getSiteConfig() );
122                }
123                $domFragment = $nativeExt->sourceToDom(
124                    $extApi, $extSrc, $extArgs
125                );
126                $errors = $extApi->getErrors();
127                if ( $extConfig['options']['wt2html']['customizesDataMw'] ?? false ) {
128                    $firstNode = $domFragment->firstChild;
129                    '@phan-var Element $firstNode'; // @var Element $firstNode
130                    $dataMw = DOMDataUtils::getDataMw( $firstNode );
131                }
132            } catch ( ExtensionError $e ) {
133                $domFragment = WTUtils::createInterfaceI18nFragment(
134                    $env->getTopLevelDoc(), $e->err->key, $e->err->params ?: null
135                );
136                $i18nFrag = $domFragment->firstChild;
137                '@phan-var Element $i18nFrag'; // @var Element $firstNode
138                $i18nFrag->setAttribute( 'class', 'error' );
139                $errors = [ $e->err ];
140                // FIXME: Should we include any errors collected
141                // from $extApi->getErrors() here?  Also, what's the correct $dataMw
142                // to apply in this case?
143            }
144            if ( $domFragment !== false ) {
145                if ( $domFragment !== null ) {
146                    // Turn this document fragment into a token
147                    $toks = $this->onDocumentFragment(
148                        $token, $domFragment, $dataMw, $errors
149                    );
150                    return $toks;
151                } else {
152                    // The extension dropped this instance completely (!!)
153                    // Should be a rarity and presumably the extension
154                    // knows what it is doing. Ex: nested refs are dropped
155                    // in some scenarios.
156                    return [];
157                }
158            }
159            // Fall through: this extension is electing not to use
160            // a custom sourceToDom method (by returning false from
161            // sourceToDom).
162        }
163        $extSrc = $token->getAttributeV( 'source' );
164        if ( str_contains( $extSrc, PipelineUtils::PARSOID_FRAGMENT_PREFIX ) ) {
165            // Convert to pFragments; this is a bit hacky
166            $pieces = preg_split(
167                '/(' . preg_quote( PipelineUtils::PARSOID_FRAGMENT_PREFIX, '/' ) . '\d+}})/',
168                $extSrc, -1, PREG_SPLIT_DELIM_CAPTURE
169            );
170            for ( $i = 1; $i < count( $pieces ); $i += 2 ) {
171                $pieces[$i] = $env->getPFragment( $pieces[$i] );
172            }
173            $extSrc = WikitextPFragment::newFromSplitWt( $pieces, null, unsafeConcat: true );
174        }
175
176        $start = hrtime( true );
177        $domFragment = PipelineUtils::parseToHTML(
178            $env,
179            $extSrc,
180            $this->manager->getFrame(),
181            $extApi,
182        );
183        if ( $env->profiling() ) {
184            $profile = $env->getCurrentProfile();
185            $profile->bumpMWTime( "Extension", hrtime( true ) - $start, "api" );
186            $profile->bumpCount( "Extension" );
187        }
188        if ( !$domFragment ) {
189            $domFragment = DOMUtils::parseHTMLToFragment( $env->getTopLevelDoc(), '' );
190        }
191        return $this->onDocumentFragment( $token, $domFragment, $dataMw, [] );
192    }
193
194    /**
195     * DOMFragment-based encapsulation
196     *
197     * @param Token $extToken
198     * @param DocumentFragment $domFragment
199     * @param DataMw $dataMw
200     * @param list<DataMwError> $errors
201     * @return array<string|Token>
202     */
203    private function onDocumentFragment(
204        Token $extToken, DocumentFragment $domFragment, DataMw $dataMw,
205        array $errors
206    ): array {
207        $env = $this->env;
208        $extensionName = $extToken->getAttributeV( 'name' );
209
210        if ( $env->hasDumpFlag( 'extoutput' ) ) {
211            $logger = $env->getSiteConfig()->getLogger();
212            $logger->warning( str_repeat( '=', 80 ) );
213            $logger->warning(
214                'EXTENSION INPUT: ' . $extToken->getAttributeV( 'source' )
215            );
216            $logger->warning( str_repeat( '=', 80 ) );
217            $logger->warning( "EXTENSION OUTPUT:\n" );
218            $logger->warning(
219                DOMUtils::getFragmentInnerHTML( $domFragment )
220            );
221            $logger->warning( str_repeat( '-', 80 ) );
222        }
223
224        $opts = [
225            'setDSR' => true,
226            'wrapperName' => $extensionName,
227        ];
228
229        // Check if the tag wants its DOM fragment not to be unpacked.
230        // The default setting is to unpack the content DOM fragment automatically.
231        $extConfig = $env->getSiteConfig()->getExtTagConfig( $extensionName );
232        if ( isset( $extConfig['options']['wt2html'] ) ) {
233            $opts += $extConfig['options']['wt2html'];
234        }
235
236        // This special case is only because, from the beginning, Parsoid has
237        // treated <nowiki>s as core functionality with lean markup (no about,
238        // no data-mw, custom typeof).
239        //
240        // We'll keep this hardcoded to avoid exposing the functionality to
241        // other native extensions until it's needed.
242        if ( $extensionName !== 'nowiki' ) {
243            if ( !$domFragment->hasChildNodes() ) {
244                // RT extensions expanding to nothing.
245                $link = $domFragment->ownerDocument->createElement( 'link' );
246                DOMDataUtils::getDataParsoid( $link )->getTemp()->empty = true;
247                $domFragment->appendChild( $link );
248            }
249
250            // Wrap the top-level nodes so that we have a firstNode element
251            // to annotate with the typeof and to apply about ids.
252            PipelineUtils::addSpanWrappers( DOMUtils::childNodes( $domFragment ) );
253
254            // Now get the firstNode
255            $firstNode = $domFragment->firstChild;
256
257            '@phan-var Element $firstNode'; // @var Element $firstNode
258
259            // Adds the wrapper attributes to the first element
260            DOMUtils::addTypeOf( $firstNode, "mw:Extension/{$extensionName}" );
261
262            // FIXME: What happens if $firstNode is template generated, since
263            // they have higher precedence?  These questions and more in T214241
264            Assert::invariant(
265                !DOMUtils::hasTypeOf( $firstNode, 'mw:Transclusion' ),
266                'First node of extension content is transcluded.'
267            );
268
269            if ( count( $errors ) > 0 ) {
270                DOMUtils::addTypeOf( $firstNode, 'mw:Error' );
271                $dataMw->errors = is_array( $dataMw->errors ?? null ) ?
272                    array_merge( $dataMw->errors, $errors ) : $errors;
273            }
274
275            // Set data-mw
276            // FIXME: Similar to T214241, we're clobbering $firstNode
277            DOMDataUtils::setDataMw( $firstNode, $dataMw );
278
279            // Add about to all wrapper tokens.
280            $about = $env->newAboutId();
281            $n = $firstNode;
282            while ( $n ) {
283                $n->setAttribute( 'about', $about );
284                $n = $n->nextSibling;
285            }
286
287            // Update data-parsoid
288            $dp = DOMDataUtils::getDataParsoid( $firstNode );
289            $dp->tsr = clone $extToken->dataParsoid->tsr;
290            $dp->src = $extToken->dataParsoid->src;
291            DOMDataUtils::setDataParsoid( $firstNode, $dp );
292        }
293
294        return PipelineUtils::tunnelDOMThroughTokens(
295            $env, $extToken, $domFragment, $opts
296        );
297    }
298
299    /**
300     * @inheritDoc
301     */
302    public function onTag( XMLTagTk $token ): ?array {
303        return $token->getName() === 'extension' ? $this->onExtension( $token ) : null;
304    }
305
306    private function stripAnnotations( string $s, SiteConfig $siteConfig ): string {
307        $annotationStrippers = $siteConfig->getAnnotationStrippers();
308
309        $res = $s;
310        foreach ( $annotationStrippers as $annotationStripper ) {
311            $res = $annotationStripper->stripAnnotations( $res );
312        }
313        return $res;
314    }
315}