Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
| Total | |
30.26% |
23 / 76 |
|
14.29% |
1 / 7 |
CRAP | |
0.00% |
0 / 1 |
| ContentModelHandler | |
30.26% |
23 / 76 |
|
14.29% |
1 / 7 |
91.31 | |
0.00% |
0 / 1 |
| __construct | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
| canonicalizeDOM | |
0.00% |
0 / 10 |
|
0.00% |
0 / 1 |
2 | |||
| setupSelser | |
0.00% |
0 / 10 |
|
0.00% |
0 / 1 |
6 | |||
| processIndicators | |
0.00% |
0 / 8 |
|
0.00% |
0 / 1 |
12 | |||
| toDOM | |
0.00% |
0 / 14 |
|
0.00% |
0 / 1 |
12 | |||
| preprocessEditedDOM | |
0.00% |
0 / 10 |
|
0.00% |
0 / 1 |
12 | |||
| fromDOM | |
100.00% |
23 / 23 |
|
100.00% |
1 / 1 |
2 | |||
| 1 | <?php |
| 2 | declare( strict_types = 1 ); |
| 3 | |
| 4 | namespace Wikimedia\Parsoid\Wikitext; |
| 5 | |
| 6 | use Wikimedia\Parsoid\Config\Env; |
| 7 | use Wikimedia\Parsoid\Core\ContentModelHandler as IContentModelHandler; |
| 8 | use Wikimedia\Parsoid\Core\SelectiveUpdateData; |
| 9 | use Wikimedia\Parsoid\DOM\Document; |
| 10 | use Wikimedia\Parsoid\Ext\DOMProcessor as ExtDOMProcessor; |
| 11 | use Wikimedia\Parsoid\Ext\ParsoidExtensionAPI; |
| 12 | use Wikimedia\Parsoid\Html2Wt\RemoveRedLinks; |
| 13 | use Wikimedia\Parsoid\Html2Wt\SelectiveSerializer; |
| 14 | use Wikimedia\Parsoid\Html2Wt\WikitextSerializer; |
| 15 | use Wikimedia\Parsoid\Utils\ContentUtils; |
| 16 | use Wikimedia\Parsoid\Utils\DOMCompat; |
| 17 | use Wikimedia\Parsoid\Utils\DOMDataUtils; |
| 18 | use Wikimedia\Parsoid\Utils\Timing; |
| 19 | |
| 20 | class ContentModelHandler extends IContentModelHandler { |
| 21 | |
| 22 | /** @var Env */ |
| 23 | private $env; |
| 24 | |
| 25 | /** |
| 26 | * Sneak an environment in here since it's not exposed as part of the |
| 27 | * ParsoidExtensionAPI |
| 28 | * |
| 29 | * @param Env $env |
| 30 | */ |
| 31 | public function __construct( Env $env ) { |
| 32 | $this->env = $env; |
| 33 | } |
| 34 | |
| 35 | /** |
| 36 | * Bring DOM to expected canonical form |
| 37 | */ |
| 38 | private function canonicalizeDOM( |
| 39 | Env $env, Document $doc, bool $isSelectiveUpdate |
| 40 | ): void { |
| 41 | $body = DOMCompat::getBody( $doc ); |
| 42 | |
| 43 | // Convert DOM to internal canonical form |
| 44 | DOMDataUtils::visitAndLoadDataAttribs( $body, [ |
| 45 | 'markNew' => !$isSelectiveUpdate, |
| 46 | ] ); |
| 47 | |
| 48 | // Update DSR offsets if necessary. |
| 49 | ContentUtils::convertOffsets( |
| 50 | $env, $doc, $env->getRequestOffsetType(), 'byte' |
| 51 | ); |
| 52 | |
| 53 | // Strip <section> and mw:FallbackId <span> tags, if present, |
| 54 | // as well as extended annotation wrappers. |
| 55 | // This ensures that we can accept HTML from CX / VE |
| 56 | // and other clients that might have stripped them. |
| 57 | ContentUtils::stripUnnecessaryWrappersAndSyntheticNodes( $body ); |
| 58 | |
| 59 | $redLinkRemover = new RemoveRedLinks( $this->env ); |
| 60 | $redLinkRemover->run( $body ); |
| 61 | } |
| 62 | |
| 63 | /** |
| 64 | * Fetch prior DOM for selser. |
| 65 | * |
| 66 | * @param ParsoidExtensionAPI $extApi |
| 67 | * @param SelectiveUpdateData $selserData |
| 68 | */ |
| 69 | private function setupSelser( |
| 70 | ParsoidExtensionAPI $extApi, SelectiveUpdateData $selserData |
| 71 | ) { |
| 72 | $env = $this->env; |
| 73 | |
| 74 | // Why is it safe to use a reparsed dom for dom diff'ing? |
| 75 | // (Since that's the only use of `env.page.dom`) |
| 76 | // |
| 77 | // There are two types of non-determinism to discuss: |
| 78 | // |
| 79 | // * The first is from parsoid generated ids. At this point, |
| 80 | // data-attributes have already been applied so there's no chance |
| 81 | // that variability in the ids used to associate data-attributes |
| 82 | // will lead to data being applied to the wrong nodes. |
| 83 | // |
| 84 | // Further, although about ids will differ, they belong to the set |
| 85 | // of ignorable attributes in the dom differ. |
| 86 | // |
| 87 | // * Templates, and encapsulated content in general, are the second. |
| 88 | // Since that content can change in between parses, the resulting |
| 89 | // dom might not be the same. However, because dom diffing on |
| 90 | // on those regions only uses data-mw for comparision (which will |
| 91 | // remain constant between parses), this also shouldn't be an |
| 92 | // issue. |
| 93 | // |
| 94 | // There is one caveat. Because encapsulated content isn't |
| 95 | // guaranteed to be "balanced", the template affected regions |
| 96 | // may change between parses. This should be rare. |
| 97 | // |
| 98 | // We therefore consider this safe since it won't corrupt the page |
| 99 | // and, at worst, mixed up diff'ing annotations can end up with an |
| 100 | // unfaithful serialization of the edit. |
| 101 | // |
| 102 | // However, in cases where original content is not returned by the |
| 103 | // client / RESTBase, selective serialization cannot proceed and |
| 104 | // we're forced to fallback to normalizing the entire page. This has |
| 105 | // proved unacceptable to editors as is and, as we lean heavier on |
| 106 | // selser, will only get worse over time. |
| 107 | // |
| 108 | // So, we're forced to trade off the correctness for usability. |
| 109 | if ( $selserData->revHTML === null ) { |
| 110 | $env->log( "warn/html2wt", "Missing selserData->revHTML. Regenerating." ); |
| 111 | |
| 112 | // FIXME(T266838): Create a new Env for this parse? Something is |
| 113 | // needed to avoid this rigmarole. |
| 114 | $topLevelDoc = $env->getTopLevelDoc(); |
| 115 | $env->setupTopLevelDoc(); |
| 116 | // This effectively parses $selserData->revText for us because |
| 117 | // $selserData->revText = $env->getPageconfig()->getPageMainContent() |
| 118 | $doc = $this->toDOM( $extApi ); |
| 119 | $env->setTopLevelDoc( $topLevelDoc ); |
| 120 | } else { |
| 121 | $doc = ContentUtils::createDocument( $selserData->revHTML, true ); |
| 122 | } |
| 123 | |
| 124 | $this->canonicalizeDOM( $env, $doc, false ); |
| 125 | $selserData->revDOM = $doc; |
| 126 | } |
| 127 | |
| 128 | private function processIndicators( Document $doc, ParsoidExtensionAPI $extApi ): void { |
| 129 | // Erroneous indicators without names will be <span>s |
| 130 | $indicators = DOMCompat::querySelectorAll( $doc, 'meta[typeof~="mw:Extension/indicator"]' ); |
| 131 | $iData = []; |
| 132 | |
| 133 | // https://www.mediawiki.org/wiki/Help:Page_status_indicators#Adding_page_status_indicators |
| 134 | // says that last one wins. But, that may just be documentation of the |
| 135 | // implementation vs. being a deliberate strategy. |
| 136 | // |
| 137 | // The indicators are ordered by depth-first pre-order DOM traversal. |
| 138 | // This ensures that the indicators are in document textual order. |
| 139 | // Given that, the for-loop below implements "last-one-wins" semantics |
| 140 | // for indicators that use the same name key. |
| 141 | foreach ( $indicators as $meta ) { |
| 142 | $dmw = DOMDataUtils::getDataMw( $meta ); |
| 143 | $name = $dmw->attrs->name; |
| 144 | $iData[$name] = $dmw->html; |
| 145 | } |
| 146 | |
| 147 | // set indicator metadata for unique keys |
| 148 | foreach ( $iData as $name => $html ) { |
| 149 | $extApi->getMetadata()->setIndicator( (string)$name, $html ); |
| 150 | } |
| 151 | } |
| 152 | |
| 153 | /** |
| 154 | * @inheritDoc |
| 155 | */ |
| 156 | public function toDOM( |
| 157 | ParsoidExtensionAPI $extApi, ?SelectiveUpdateData $selectiveUpdateData = null |
| 158 | ): Document { |
| 159 | $env = $this->env; |
| 160 | $pipelineFactory = $env->getPipelineFactory(); |
| 161 | |
| 162 | if ( $selectiveUpdateData ) { |
| 163 | $doc = ContentUtils::createDocument( $selectiveUpdateData->revHTML, true ); |
| 164 | $env->setupTopLevelDoc( $doc ); |
| 165 | $this->canonicalizeDOM( $env, $env->getTopLevelDoc(), true ); |
| 166 | $selectiveUpdateData->revDOM = $doc; |
| 167 | $doc = $pipelineFactory->selectiveDOMUpdate( $selectiveUpdateData ); |
| 168 | } else { |
| 169 | $doc = $pipelineFactory->parse( |
| 170 | // @phan-suppress-next-line PhanDeprecatedFunction not ready for topFrame yet |
| 171 | $env->getPageConfig()->getPageMainContent() |
| 172 | ); |
| 173 | } |
| 174 | |
| 175 | // Hardcoded support for indicators |
| 176 | // TODO: Eventually we'll want to apply this to selective updates as well |
| 177 | if ( !$selectiveUpdateData ) { |
| 178 | $this->processIndicators( $doc, $extApi ); |
| 179 | } |
| 180 | |
| 181 | return $doc; |
| 182 | } |
| 183 | |
| 184 | /** |
| 185 | * Preprocess the edited DOM as required before attempting to convert it to wikitext |
| 186 | * 1. The edited DOM (represented by body) might not be in canonical form |
| 187 | * because Parsoid might be providing server-side management of global state |
| 188 | * for extensions. To address this and bring the DOM back to canonical form, |
| 189 | * we run extension-provided handlers. The original DOM isn't subject to this problem. |
| 190 | * FIXME: But, this is not the only reason an extension might register a preprocessor. |
| 191 | * How do we know when to run a preprocessor on both original & edited DOMs? |
| 192 | * 2. We need to do this after all data attributes have been loaded. |
| 193 | * 3. We need to do this before we run dom-diffs to eliminate spurious diffs. |
| 194 | * |
| 195 | * @param Env $env |
| 196 | * @param Document $doc |
| 197 | */ |
| 198 | private function preprocessEditedDOM( Env $env, Document $doc ): void { |
| 199 | $siteConfig = $env->getSiteConfig(); |
| 200 | |
| 201 | // Run any registered DOM preprocessors |
| 202 | foreach ( $siteConfig->getExtDOMProcessors() as $extName => $domProcs ) { |
| 203 | foreach ( $domProcs as $i => $classNameOrSpec ) { |
| 204 | $c = $siteConfig->getObjectFactory()->createObject( $classNameOrSpec, [ |
| 205 | 'allowClassName' => true, |
| 206 | 'assertClass' => ExtDOMProcessor::class, |
| 207 | ] ); |
| 208 | $c->htmlPreprocess( |
| 209 | new ParsoidExtensionAPI( $env ), DOMCompat::getBody( $doc ) |
| 210 | ); |
| 211 | } |
| 212 | } |
| 213 | } |
| 214 | |
| 215 | /** |
| 216 | * @inheritDoc |
| 217 | */ |
| 218 | public function fromDOM( |
| 219 | ParsoidExtensionAPI $extApi, ?SelectiveUpdateData $selserData = null |
| 220 | ): string { |
| 221 | $env = $this->env; |
| 222 | $siteConfig = $env->getSiteConfig(); |
| 223 | $setupTiming = Timing::start( $siteConfig ); |
| 224 | |
| 225 | $this->canonicalizeDOM( $env, $env->getTopLevelDoc(), false ); |
| 226 | |
| 227 | $serializerOpts = [ 'selserData' => $selserData ]; |
| 228 | if ( $selserData ) { |
| 229 | $serializer = new SelectiveSerializer( $env, $serializerOpts ); |
| 230 | $this->setupSelser( $extApi, $selserData ); |
| 231 | $wtsType = 'selser'; |
| 232 | } else { |
| 233 | // Fallback |
| 234 | $serializer = new WikitextSerializer( $env, $serializerOpts ); |
| 235 | $wtsType = 'noselser'; |
| 236 | } |
| 237 | |
| 238 | $setupTiming->end( 'html2wt.setup', 'html2wt_setup_seconds', [] ); |
| 239 | |
| 240 | $preprocTiming = Timing::start( $siteConfig ); |
| 241 | $this->preprocessEditedDOM( $env, $env->getTopLevelDoc() ); |
| 242 | $preprocTiming->end( 'html2wt.preprocess', 'html2wt_preprocess_seconds', [] ); |
| 243 | |
| 244 | $serializeTiming = Timing::start( $siteConfig ); |
| 245 | $res = $serializer->serializeDOM( $env->getTopLevelDoc() ); |
| 246 | $serializeTiming->end( |
| 247 | "html2wt.{$wtsType}.serialize", |
| 248 | "html2wt_serialize_seconds", |
| 249 | [ 'wts' => $wtsType ] |
| 250 | ); |
| 251 | |
| 252 | return $res; |
| 253 | } |
| 254 | |
| 255 | } |