Repository navigation
Expand file tree
/
Copy pathclass-xmlprocessor.php
More file actions
4372 lines (3930 loc) · 138 KB
/
Copy pathclass-xmlprocessor.php
File metadata and controls
4372 lines (3930 loc) · 138 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?php
namespace WordPress\XML;
use WP_HTML_Span;
use WP_HTML_Text_Replacement;
use function WordPress\Encoding\compat\_wp_scan_utf8;
use function WordPress\Encoding\utf8_ord;
/**
* XML API: XMLProcessor class
*
* Scans through an XML document to find specific tags, then
* transforms those tags by adding, removing, or updating the
* values of the XML attributes within that tag (opener).
*
* It implements a subset of the XML 1.0 specification (https://www.w3.org/TR/xml/)
* and supports XML documents with the following characteristics:
*
* – XML 1.0
* – Well-formed
* – UTF-8 encoded
* – Not standalone (so can use external entities)
* – No DTD, DOCTYPE, ATTLIST, ENTITY, or conditional sections (will fail on them)
*
* XML 1.1 is explicitly not a design goal here. Version 1.1 is
* more complex specification and not so widely supported.
*
* ### Possible future direction for this module
*
* XMLProcessor only aims to support XML 1.0, which is mostly well-defined and
* supported across the web. There are no plans to extend the parsing logic to XML 1.1,
* which is a more complex specification and not so widely supported.
*
* @TODO: Include the cursor string in internal bookmarks and use it for seeking.
*
* @TODO: Track specific error states, expose informative messages, line
* numbers, indexes, and other debugging info.
*
* @TODO: Skip over the following syntax elements instead of failing:
* * <!DOCTYPE, see https://www.w3.org/TR/xml/#sec-prolog-dtd
* * <!ATTLIST, see https://www.w3.org/TR/xml/#attdecls
* * <!ENTITY, see https://www.w3.org/TR/xml/#sec-entity-decl
* * <!NOTATION, see https://www.w3.org/TR/xml/#sec-entity-decl
* * Conditional sections, see https://www.w3.org/TR/xml/#sec-condition-sect
*
* @package WordPress
* @subpackage HTML-API
* @since WP_VERSION
*/
/**
* Core class used to modify attributes in an XML document for tags matching a query.
*
* ## Usage
*
* Use of this class requires three steps:
*
* 1. Create a new class instance with your input XML document.
* 2. Find the tag(s) you are looking for.
* 3. Request changes to the attributes in those tag(s).
*
* Example:
*
* $processor = XMLProcessor::create_from_string( $xml );
* if ( $processor->next_tag( 'option' ) ) {
* $processor->set_attribute( '', 'selected', 'yes' );
* }
*
* ### Finding tags
*
* The `next_tag()` function moves the internal cursor through
* your input XML document until it finds a tag meeting any of
* the supplied restrictions in the optional query argument. If
* no argument is provided then it will find the next XML tag,
* regardless of what kind it is.
*
* If you want to _find whatever the next tag is_:
*
* $processor->next_tag();
*
* | Goal | Query |
* |----------------------------------------------------------|----------------------------------------------------------|
* | Find any tag. | `$processor->next_tag();` |
* | Find next image tag. | `$processor->next_tag( array( 'tag_name' => 'image' ) );`|
* | Find next image tag (shorthand). | `$processor->next_tag( 'image' );` |
* | Find next image tag in the "wp.org" namespace name. | `$processor->next_tag( array( 'wp.org', 'image' ) );` |
*
* #### Namespace Examples
*
* To work with namespaces, pass a tuple of (namespace name, local name):
*
* $xml = '<root xmlns:wp="http://wordpress.org/export/1.2/"><wp:image wp:src="cat.jpg" /></root>';
* $processor = XMLProcessor::create_from_string( $xml );
* // Find the <wp:image> tag
* if ( $processor->next_tag( array( 'http://wordpress.org/export/1.2/', 'image' ) ) ) {
* // Get the namespace name of the matched tag
* $ns = $processor->get_tag_namespace(); // 'http://wordpress.org/export/1.2/'
* // Get the value of the wp:src attribute
* $src = $processor->get_attribute( $ns, 'src' );
* // Set a new attribute in the same namespace
* $processor->set_attribute( $ns, 'alt', 'A cat' );
* }
*
* If a tag was found meeting your criteria then `next_tag()`
* will return `true` and you can proceed to modify it. If it
* returns `false`, it failed to find the tag and moved the cursor to the end of the file.
*
* Once the cursor reaches the end of the file the processor
* is done and if you want to reach an earlier tag you will
* need to recreate the processor and start over, as it's
* unable to back up or move in reverse (except via bookmarks).
*
* #### Custom queries
*
* Sometimes it's necessary to further inspect an XML tag than
* the query syntax here permits. In these cases one may further
* inspect the search results using the read-only functions
* provided by the processor or external state or variables.
*
* Example:
*
* // Paint up to the first five `musician` or `actor` tags marked with the "jazzy" style.
* $remaining_count = 5;
* while ( $remaining_count > 0 && $processor->next_tag() ) {
* $tag = $processor->get_tag_local_name();
* if (
* ( 'musician' === $tag || 'actor' === $tag ) &&
* 'jazzy' === $processor->get_attribute( '', 'data-style' )
* ) {
* $processor->set_attribute( '', 'theme-style', 'theme-style-everest-jazz' );
* $remaining_count--;
* }
* }
*
* `get_attribute()` will return `null` if the attribute wasn't present
* on the tag when it was called. It may return `""` (the empty string)
* in cases where the attribute was present but its value was empty.
* For boolean attributes, those whose name is present but no value is
* given, it will return `true` (the only way to set `false` for an
* attribute is to remove it).
*
* #### When matching fails
*
* When `next_tag()` returns `false` it could mean different things:
*
* - The requested tag wasn't found in the input document.
* - The input document ended in the middle of an XML syntax element.
*
* When a document ends in the middle of a syntax element it will pause
* the processor. This is to make it possible in the future to extend the
* input document and proceed - an important requirement for chunked
* streaming parsing of a document.
*
* Example:
*
* $processor = XMLProcessor::create_from_string( 'This <content is="a" partial="token' );
* false === $processor->next_tag();
*
* If a special element (see next section) is encountered but no closing tag
* is found it will count as an incomplete tag. The parser will pause as if
* the opening tag were incomplete.
*
* Example:
*
* $processor = XMLProcessor::create_from_string( '<style>// there could be more styling to come' );
* false === $processor->next_tag();
*
* $processor = XMLProcessor::create_from_string( '<style>// this is everything</style><content>' );
* true === $processor->next_tag( 'content' );
*
*
* ### Modifying XML attributes for a found tag
*
* Once you've found the start of an opening tag you can modify
* any number of the attributes on that tag. You can set a new
* value for an attribute, remove the entire attribute, or do
* nothing and move on to the next opening tag.
*
* Example:
*
* if ( $processor->next_tag( 'user-group' ) ) {
* $processor->set_attribute( '', 'name', 'Content editors' );
* $processor->remove_attribute( '', 'data-test-id' );
* }
*
* If `set_attribute()` is called for an existing attribute it will
* overwrite the existing value. Similarly, calling `remove_attribute()`
* for a non-existing attribute has no effect on the document. Both
* of these methods are safe to call without knowing if a given attribute
* exists beforehand.
*
* #### Namespaced attribute example
*
* $processor = XMLProcessor::from_string( '<root xmlns:wp="http://wordpress.org/export/1.2/"><image /></root>' );
*
* $ns = 'http://wordpress.org/export/1.2/';
* if ( $processor->next_tag( 'image' ) ) {
* $processor->set_attribute( $ns, 'src', 'cat.jpg' );
* }
*
* echo $processor->get_modifiable_text();
* // <root xmlns:wp="http://wordpress.org/export/1.2/"><image wp:src="cat.jpg" /></root>
*
* ### Bookmarks
*
* While scanning through the input XML document it's possible to set
* a named bookmark when a particular tag is found. Later on, after
* continuing to scan other tags, it's possible to `seek` to one of
* the set bookmarks and then proceed again from that point forward.
*
* Because bookmarks create processing overhead one should avoid
* creating too many of them. As a rule, create only bookmarks
* of known string literal names; avoid creating "mark_{$index}"
* and so on. It's fine from a performance standpoint to create a
* bookmark and update it frequently, such as within a loop.
*
* $total_todos = 0;
* while ( $processor->next_tag( array( 'tag_name' => 'todo-list' ) ) ) {
* $processor->set_bookmark( 'list-start' );
* while ( $processor->next_tag() ) {
* if ( 'todo' === $processor->get_tag_local_name() && $processor->is_tag_closer() ) {
* $processor->set_bookmark( 'list-end' );
* $processor->seek( 'list-start' );
* $processor->set_attribute( '', 'data-contained-todos', (string) $total_todos );
* $total_todos = 0;
* $processor->seek( 'list-end' );
* break;
* }
* if ( 'todo-item' === $processor->get_tag_local_name() && ! $processor->is_tag_closer() ) {
* $total_todos++;
* }
* }
* }
*
* ## Tokens and finer-grained processing
*
* It's possible to scan through every lexical token in the
* XML document using the `next_token()` function. This
* alternative form takes no argument and provides no built-in
* query syntax.
*
* Example:
*
* $title = '(untitled)';
* $text = '';
* while ( $processor->next_token() ) {
* switch ( $processor->get_token_name() ) {
* case '#text':
* $text .= $processor->get_modifiable_text();
* break;
* case 'new-line':
* $text .= "\n";
* break;
* case 'title':
* $title = $processor->get_modifiable_text();
* break;
* }
* }
* return trim( "# {$title}\n\n{$text}" );
*
* ### Tokens and _modifiable text_
*
* There are also non-elements which are void/self-closing in nature and contain
* modifiable text that is part of that individual syntax token itself.
*
* - `#text` nodes, whose entire token _is_ the modifiable text.
* - XML comments and tokens that become comments due to some syntax error. The
* text for these tokens is the portion of the comment inside of the syntax.
* E.g. for `<!-- comment -->` the text is `" comment "` (note the spaces are included).
* - `CDATA` sections, whose text is the content inside of the section itself. E.g. for
* `<![CDATA[some content]]>` the text is `"some content"`.
* - XML Processing instruction nodes like `<?xml __( "Like" ); ?>` (with restrictions [1]).
*
* [1]: XML requires "xml" as a processing instruction name. The Tag Processor captures the entire
* processing instruction as a single token up to the closing `?>`.
*
* ## Design and limitations
*
* The XMLProcessor is designed to linearly scan XML documents and tokenize
* XML tags and their attributes. It's designed to do this as efficiently as
* possible without compromising parsing integrity. Therefore it will be
* slower than some methods of modifying XML, such as those incorporating
* over-simplified PCRE patterns, but will not introduce the defects and
* failures that those methods bring in, which lead to broken page renders
* and often to security vulnerabilities. On the other hand, it will be faster
* than full-blown XML parsers such as DOMDocument and use considerably
* less memory. It requires a negligible memory overhead, enough to consider
* it a zero-overhead system.
*
* The performance characteristics are maintained by avoiding tree construction.
*
* The XMLProcessor checks the most important aspects of XML integrity as it scans
* through the document. It verifies that a single root element exists, that there are
* no unclosed tags, and that each opener tag has a corresponding closer. It also
* ensures no duplicate attributes exist on a single tag.
*
* At the same time, the XMLProcessor also skips expensive validation of XML entities
* in the document. The processor will initially pass through invalid entity references
* and only fail when the developer attempts to read their value. If that doesn't happen,
* the invalid values will be left untouched in the final document.
*
* Most operations within the XMLProcessor are designed to minimize the difference
* between an input and output document for any given change. For example, the
* `set_attribute` and `remove_attribute` methods preserve whitespace and the attribute
* ordering within the element definition. An exception to this rule is that all attribute
* updates store their values as double-quoted strings, meaning that attributes on input with
* single-quoted or unquoted values will appear in the output with double-quotes.
*
* ### Text Encoding
*
* The XMLProcessor assumes that the input XML document is encoded with a
* UTF-8 encoding and will refuse to process documents that declare other encodings.
*
* ### Namespaces
*
* Namespaces are first-class citizens in the XMLProcessor. Namespace-aware methods such as
* `set_attribute()` and `remove_attribute()` require the expanded namespace name from the
* matching `xmlns` declaration, not the prefix written in the tag.
* The actual matching is done on the expanded namespace name plus the local name.
*
* Example:
*
* $processor = XMLProcessor::from_string( '<root xmlns:wp="http://wordpress.org/export/1.2/"><wp:image src="cat.jpg" /></root>' );
* $processor->next_tag( 'image' );
* $local_name = $processor->get_tag_local_name(); // 'image'
* $ns = $processor->get_tag_namespace(); // 'http://wordpress.org/export/1.2/'
* echo $processor->get_tag_namespace_and_local_name(); // '{http://wordpress.org/export/1.2/}image'
*
* #### Internal representation of names
*
* Internally, the XMLProcessor stores names using the following format:
*
* {namespace}local_name
*
* It's safe, because the "{" and "}" bytes cannot be used in tag names or attribute names:
*
* [4] NameStartChar ::= ":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | [#x370-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
* [4a] NameChar ::= NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
*
* @since WP_VERSION
*/
class XMLProcessor {
/**
* The maximum number of bookmarks allowed to exist at
* any given time.
*
* @since WP_VERSION
* @var int
*
* @see XMLProcessor::set_bookmark()
*/
const MAX_BOOKMARKS = 10;
/**
* Maximum number of times seek() can be called.
* Prevents accidental infinite loops.
*
* @since WP_VERSION
* @var int
*
* @see XMLProcessor::seek()
*/
const MAX_SEEK_OPS = 1000;
/**
* The XML document to parse.
*
* @since WP_VERSION
* @var string
*/
public $xml;
/**
* Specifies mode of operation of the parser at any given time.
*
* | State | Meaning |
* | ------------------|----------------------------------------------------------------------|
* | *Ready* | The parser is ready to run. |
* | *Complete* | There is nothing left to parse. |
* | *Incomplete* | The XML ended in the middle of a token; nothing more can be parsed. |
* | *Matched tag* | Found an XML tag; it's possible to modify its attributes. |
* | *Text node* | Found a #text node; this is plaintext and modifiable. |
* | *CDATA node* | Found a CDATA section; this is modifiable. |
* | *PI node* | Found a processing instruction; this is modifiable. |
* | *XML declaration* | Found an XML declaration; this is modifiable. |
* | *Comment* | Found a comment or bogus comment; this is modifiable. |
*
* @since WP_VERSION
*
* @see XMLProcessor::STATE_READY
* @see XMLProcessor::STATE_COMPLETE
* @see XMLProcessor::STATE_INCOMPLETE_INPUT
* @see XMLProcessor::STATE_MATCHED_TAG
* @see XMLProcessor::STATE_TEXT_NODE
* @see XMLProcessor::STATE_CDATA_NODE
* @see XMLProcessor::STATE_PI_NODE
* @see XMLProcessor::STATE_XML_DECLARATION
* @see XMLProcessor::STATE_COMMENT
*
* @var string
*/
protected $parser_state = self::STATE_READY;
/**
* Whether the input has been finished.
*
* @var bool
*/
protected $expecting_more_input = true;
/**
* How many bytes from the current XML chunk have been read and parsed.
*
* This value points to the latest byte offset in the input document which
* has been already parsed. It is the internal cursor for the Tag Processor
* and updates while scanning through the XML tokens.
*
* @since WP_VERSION
* @var int
*/
public $bytes_already_parsed = 0;
/**
* How many XML bytes from the original stream have already been removed
* from the memory.
*
* @since WP_VERSION
* @var int
*/
public $upstream_bytes_forgotten = 0;
/**
* Byte offset in the current `$xml` string where the currently recognized token starts.
* `null` if no token is currently active.
*
* Example:
*
* <content id="test">...
* ^-- token_starts_at = 0
*
* @since WP_VERSION
*
* @var int|null
*/
protected $token_starts_at;
/**
* Byte length of current token.
*
* Example:
*
* <content id="test">...
* 012345678901234
* - token length is 14 - 0 = 14
*
* a <!-- comment --> is a token.
* 0123456789 123456789 123456789
* - token length is 17 - 2 = 15
*
* @since WP_VERSION
*
* @var int|null
*/
private $token_length;
/**
* Currently matched XML element object.
*
* @var XMLElement|null
*/
private $element;
/**
* Byte offset in input document where current tag name starts.
*
* Example:
*
* <content id="test">...
* 01234
* - tag name starts at 1
*
* @since WP_VERSION
*
* @var int|null
*/
private $tag_name_starts_at;
/**
* Byte length of current tag name.
*
* Example:
*
* <content id="test">...
* 01234
* --- tag name length is 3
*
* @since WP_VERSION
*
* @var int|null
*/
private $tag_name_length;
/**
* Byte offset into input document where current modifiable text starts.
*
* @since WP_VERSION
*
* @var int
*/
private $text_starts_at;
/**
* Byte length of modifiable text.
*
* @since WP_VERSION
*
* @var string
*/
private $text_length;
/**
* Whether the current tag is an opening tag, e.g. <content>, or a closing tag, e.g. </content>.
*
* @var bool
*/
private $is_closing_tag;
/**
* Stores the error for why something failed, if it did.
*
* @see self::get_last_error
*
* @since WP_VERSION
*
* @var string|null
*/
protected $last_error = null;
/**
* Stores context for why the parser bailed on unsupported XML, if it did.
*
* @see self::get_exception
*
* @var XMLUnsupportedException|null
*/
private $exception = null;
/**
* Temporary index of attributes found within an XML tag, keyed by the qualified
* attribute name. It is only used during the initial attributes parsing phase and
* discarded once all the attributes have been parsed.
*
* @since WP_VERSION
* @var XMLAttributeToken[]
*/
private $qualified_attributes = array();
/**
* Stores the attributes found within an XML tag, keyed by their namespace
* and local name combination.
*
* Example:
*
* // Supposing the parser just finished parsing the wp:content tag:
* // <channel xmlns:wp="http://wordpress.org/export/1.2/">
* // <wp:content wp:id="test-4" class="outline">
* // </channel>
* //
* // Then, the attributes array would be:
* $this->attributes = array(
* '{http://wordpress.org/export/1.2/}id' => new XMLAttributeToken( 9, 6, 5, 14, 'wp', 'id' ),
* 'class' => new XMLAttributeToken( 23, 7, 17, 13, '', 'class', '' )
* );
*
* @since WP_VERSION
* @var XMLAttributeToken[]
*/
private $attributes = array();
/**
* Tracks a semantic location in the original XML which
* shifts with updates as they are applied to the document.
*
* @since WP_VERSION
* @var WP_HTML_Span[]
*/
protected $bookmarks = array();
/**
* Lexical replacements to apply to input XML document.
*
* "Lexical" in this class refers to the part of this class which
* operates on pure text _as text_ and not as XML. There's a line
* between the public interface, with XML-semantic methods like
* `set_attribute` and `add_class`, and an internal state that tracks
* text offsets in the input document.
*
* When higher-level XML methods are called, those have to transform their
* operations (such as setting an attribute's value) into text diffing
* operations (such as replacing the sub-string from indices A to B with
* some given new string). These text-diffing operations are the lexical
* updates.
*
* As new higher-level methods are added they need to collapse their
* operations into these lower-level lexical updates since that's the
* Tag Processor's internal language of change. Any code which creates
* these lexical updates must ensure that they do not cross XML syntax
* boundaries, however, so these should never be exposed outside of this
* class or any classes which intentionally expand its functionality.
*
* These are enqueued while editing the document instead of being immediately
* applied to avoid processing overhead, string allocations, and string
* copies when applying many updates to a single document.
*
* Example:
*
* // Replace an attribute stored with a new value, indices
* // sourced from the lazily-parsed XML recognizer.
* $start = $attributes['src']->start;
* $length = $attributes['src']->length;
* $modifications[] = new WP_HTML_Text_Replacement( $start, $length, $new_value );
*
* // Correspondingly, something like this will appear in this array.
* $lexical_updates = array(
* WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
* );
*
* @since WP_VERSION
* @var WP_HTML_Text_Replacement[]
*/
protected $lexical_updates = array();
/**
* The Name from the DOCTYPE declaration.
*
* ```
* doctypedecl ::= '<!DOCTYPE' S Name (S ExternalID)? S? ('[' intSubset ']' S?)? '>'
* ^^^^
* ```
*
* @since WP_VERSION
* @var WP_HTML_Span|null
*/
protected $doctype_name = null;
/**
* The system literal value from the DOCTYPE declaration.
*
* ```
* doctypedecl ::= '<!DOCTYPE' S Name (S ExternalID)? S? ('[' intSubset ']' S?)? '>'
* ExternalID ::= 'SYSTEM' S SystemLiteral | 'PUBLIC' S PubidLiteral
* ^^^^^^^^^^^^^
* ```
*
* Example:
*
* <!DOCTYPE html SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
*
* In this example, the system_literal would be:
* "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
*
* @since WP_VERSION
* @var WP_HTML_Span|null
*/
protected $system_literal = null;
/**
* The public identifier value from the DOCTYPE declaration.
*
* ```
* doctypedecl ::= '<!DOCTYPE' S Name (S ExternalID)? S? ('[' intSubset ']' S?)? '>'
* ExternalID ::= 'SYSTEM' S SystemLiteral | 'PUBLIC' S PubidLiteral
* ```
* ^^^^^^^^^^^^
* Example:
*
* ```
* <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
* ```
*
* In this example, the publid_literal would be:
* "-//W3C//DTD XHTML 1.0 Strict//EN"
*
* @since WP_VERSION
* @var WP_HTML_Span|null
*/
protected $pubid_literal = null;
/**
* Memory budget for the processed XML.
*
* `append_bytes()` will flush the processed bytes whenever the XML buffer
* exceeds this budget. The lexical updates will be applied and the bookmarks
* will be reset.
*
* @var int
*/
protected $memory_budget = 1024 * 1024 * 1024;
/**
* Tracks and limits `seek()` calls to prevent accidental infinite loops.
*
* @since WP_VERSION
* @var int
*
* @see XMLProcessor::seek()
*/
protected $seek_count = 0;
/**
* Indicates the current parsing stage.
*
* A well-formed XML document has the following structure:
*
* document ::= prolog element Misc*
* prolog ::= XMLDecl? Misc* (doctypedecl Misc*)?
* Misc ::= Comment | PI | S
*
* There is exactly one element, called the root. No elements or text nodes may
* precede or follow it.
*
* See https://www.w3.org/TR/xml/#NT-document.
*
* | Stage | Meaning |
* | ----------------|---------------------------------------------------------------------|
* | *Prolog* | The parser is parsing the prolog. |
* | *Element* | The parser is parsing the root element. |
* | *Misc* | The parser is parsing miscellaneous content. |
*
* @see XMLProcessor::IN_PROLOG_CONTEXT
* @see XMLProcessor::IN_ELEMENT_CONTEXT
* @see XMLProcessor::IN_MISC_CONTEXT
*
* @since WP_VERSION
* @var bool
*/
protected $parser_context = self::IN_PROLOG_CONTEXT;
/**
* Top-level namespaces for the currently parsed document.
*
* @var array
*/
private $document_namespaces;
/**
* Tracks open elements and their namespaces while scanning XML.
*
* @var array
*/
private $stack_of_open_elements = array();
public static function create_from_string( $xml, $cursor = null, $known_definite_encoding = 'UTF-8', $document_namespaces = array() ) {
$processor = static::create_for_streaming( $xml, $cursor, $known_definite_encoding, $document_namespaces );
if ( null === $processor ) {
return false;
}
$processor->input_finished();
return $processor;
}
public static function create_for_streaming( $xml = '', $cursor = null, $known_definite_encoding = 'UTF-8', $document_namespaces = array() ) {
if ( 'UTF-8' !== $known_definite_encoding ) {
return false;
}
$processor = new XMLProcessor( $xml, $document_namespaces, self::CONSTRUCTOR_UNLOCK_CODE );
if ( null !== $cursor && true !== $processor->initialize_from_cursor( $cursor ) ) {
return false;
}
return $processor;
}
/**
* Returns a re-entrancy cursor – it's a string that can instruct a new XML
* Processor instance to continue parsing from the current location in the
* document.
*
* The only stable part of this API is the return type of string. The consumer
* of this method MUST NOT assume any specific structure of the returned
* string. It will change without a warning between WordPress releases.
*
* This is not a tell() API. No XML Processor method will accept the cursor
* to move to another location. The only way to use this cursor is creating
* a new XML Processor instance. If you need to move around the document, use
* `set_bookmark()` and `seek()`.
*/
public function get_reentrancy_cursor() {
$stack_of_open_elements = array();
foreach ( $this->stack_of_open_elements as $element ) {
$stack_of_open_elements[] = $element->to_array();
}
return base64_encode( // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
json_encode(
array(
'is_finished' => $this->is_finished(),
'upstream_bytes_forgotten' => $this->upstream_bytes_forgotten,
'parser_context' => $this->parser_context,
'stack_of_open_elements' => $stack_of_open_elements,
'expecting_more_input' => $this->expecting_more_input,
'document_namespaces' => $this->document_namespaces,
)
)
);
}
/**
* Returns the byte offset in the input stream where the current token starts.
*
* You should probably not use this method.
*
* It's only exists to allow resuming the input stream at the same offset where
* the XML parsing was finished. It will never expose any attribute's byte
* offset and no method in the XML processor API will ever accept the byte offset
* to move to another location. If you need to move around the document, use
* `set_bookmark()` and `seek()` instead.
*/
public function get_token_byte_offset_in_the_input_stream() {
return $this->token_starts_at + $this->upstream_bytes_forgotten;
}
protected function initialize_from_cursor( $cursor ) {
if ( ! is_string( $cursor ) ) {
_doing_it_wrong( __METHOD__, 'Cursor must be a JSON-encoded string.', '1.0.0' );
return false;
}
$cursor = base64_decode( $cursor ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode
if ( false === $cursor ) {
_doing_it_wrong( __METHOD__, 'Invalid cursor provided to initialize_from_cursor().', '1.0.0' );
return false;
}
$cursor = json_decode( $cursor, true );
if ( false === $cursor ) {
_doing_it_wrong( __METHOD__, 'Invalid cursor provided to initialize_from_cursor().', '1.0.0' );
return false;
}
if ( $cursor['is_finished'] ) {
$this->parser_state = self::STATE_COMPLETE;
}
// Assume the input stream will start from the last known byte offset.
$this->bytes_already_parsed = 0;
$this->upstream_bytes_forgotten = $cursor['upstream_bytes_forgotten'];
$this->stack_of_open_elements = array();
foreach ( $cursor['stack_of_open_elements'] as $element ) {
array_push( $this->stack_of_open_elements, XMLElement::from_array( $element ) );
}
$this->document_namespaces = $cursor['document_namespaces'];
$this->parser_context = $cursor['parser_context'];
$this->expecting_more_input = $cursor['expecting_more_input'];
return true;
}
/**
* Constructor.
*
* Do not use this method. Use the static creator methods instead.
*
* @access private
*
* @param string $xml XML to process.
* @param array $document_namespaces Document namespaces.
* @param string|null $use_the_static_create_methods_instead This constructor should not be called manually.
*
* @see XMLProcessor::create_stream()
*
* @since 6.4.0
*
* @see XMLProcessor::create_fragment()
*/
protected function __construct( $xml, $document_namespaces = array(), $use_the_static_create_methods_instead = null ) {
if ( self::CONSTRUCTOR_UNLOCK_CODE !== $use_the_static_create_methods_instead ) {
_doing_it_wrong(
__METHOD__,
sprintf(
/* translators: %s: XMLProcessor::create_fragment(). */
__( 'Call %s to create an XML Processor instead of calling the constructor directly.' ),
'<code>XMLProcessor::create_fragment()</code>'
),
'6.4.0'
);
}
$this->xml = isset( $xml ) ? $xml : '';
$this->document_namespaces = array_merge(
$document_namespaces,
// These initial namespaces cannot be overridden.
array(
'xml' => 'http://www.w3.org/XML/1998/namespace', // Predefined, cannot be unbound or changed.
'xmlns' => 'http://www.w3.org/2000/xmlns/', // Reserved for xmlns attributes, not a real namespace for elements/attributes.
'' => '', // Default namespace is initially empty (no namespace).
)
);
}
/**
* Wipes out the processed XML and appends the next chunk of XML to
* any remaining unprocessed XML.
*
* @param string $next_chunk XML to append.
*/
public function append_bytes( $next_chunk ) {
if ( ! $this->expecting_more_input ) {
_doing_it_wrong(
__METHOD__,
__( 'Cannot append bytes after the last input chunk was provided and input_finished() was called.' ),
'WP_VERSION'
);
return false;
}
$this->xml .= $next_chunk;
if ( self::STATE_INCOMPLETE_INPUT === $this->parser_state ) {
$this->parser_state = self::STATE_READY;
}
// Periodically flush the processed bytes to avoid high memory usage.
if (
null !== $this->memory_budget &&
strlen( $this->xml ) > $this->memory_budget
) {
$this->flush_processed_xml();
}
return true;
}
/**
* Forgets the XML bytes that have been processed and are no longer needed to
* avoid high memory usage.
*
* @return string The flushed bytes.
*/
private function flush_processed_xml() {
// Flush updates.
$this->get_updated_xml();
$unreferenced_bytes = $this->bytes_already_parsed;
if ( null !== $this->token_starts_at ) {
$unreferenced_bytes = min( $unreferenced_bytes, $this->token_starts_at );
}
$flushed_bytes = substr( $this->xml, 0, $unreferenced_bytes );
$this->xml = substr( $this->xml, $unreferenced_bytes );
$this->bookmarks = array();
$this->lexical_updates = array();
$this->seek_count = 0;
$this->bytes_already_parsed -= $unreferenced_bytes;
if ( null !== $this->token_starts_at ) {
$this->token_starts_at -= $unreferenced_bytes;
}
if ( null !== $this->tag_name_starts_at ) {
$this->tag_name_starts_at -= $unreferenced_bytes;
}
if ( null !== $this->text_starts_at ) {
$this->text_starts_at -= $unreferenced_bytes;
}
$this->upstream_bytes_forgotten += $unreferenced_bytes;
return $flushed_bytes;
}
/**
* Indicates that all the XML document bytes have been provided.
*
* After calling this method, the processor will emit errors where
* previously it would have entered the STATE_INCOMPLETE_INPUT state.
*/
public function input_finished() {
$this->expecting_more_input = false;
$this->parser_state = self::STATE_READY;
}
/**
* Indicates if the processor is expecting more data bytes.
* If not, the processor will expect the remaining XML bytes to form
* a valid document and will not stop on incomplete input.
*
* @return bool Whether the processor is expecting more data bytes.
*/
public function is_expecting_more_input() {
return $this->expecting_more_input;
}
/**
* Internal method which finds the next token in the XML document.
*
* This method is a protected internal function which implements the logic for
* finding the next token in a document. It exists so that the parser can update
* its state without affecting the location of the cursor in the document and
* without triggering subclass methods for things like `next_token()`, e.g. when
* applying patches before searching for the next token.
*
* @return bool Whether a token was parsed.