README.md — Jetpack – WP Security, Backup, Speed, & Growth 16.1-beta.2

jetpack / vendor / wp-php-toolkit / xml / README.md

jetpack / vendor / wp-php-toolkit / xml Last commit date

PHP 6 days ago LICENSE.md 6 days ago README.md 6 days ago class-xmlattributetoken.php 6 days ago class-xmldecoder.php 6 days ago class-xmlelement.php 6 days ago class-xmlnativecursorprocessor.php 6 days ago class-xmlprocessor.php 6 days ago class-xmlunsupportedexception.php 6 days ago composer.json 6 days ago

README.md

207 lines

1	---
2	slug: xml
3	title: XML
4	install: wp-php-toolkit/xml
5
6	see_also:
7	- dataliberation \| DataLiberation \| Read and write WXR-sized WordPress exports as entities.
8	- encoding \| Encoding \| Validate and scrub text before strict XML processing.
9	- bytestream \| ByteStream \| Keep large XML reads incremental.
10	---
11
12	A streaming, namespace-aware XML processor in pure PHP. Read and modify huge feeds, WXR exports, ePub manifests, and Office Open XML parts without ever loading the document into memory and without depending on <code>libxml2</code>.
13
14	When the native API extension is loaded, <code>XMLProcessor</code> can use a
15	native delegate by default while preserving PHP fallback behavior. Define
16	<code>WP_NATIVE_APIS_DISABLE_DEFAULTS</code> before loading the component to
17	force the pure PHP fallback.
18
19	## Why this exists
20
21	<p><code>SimpleXMLElement</code> and <code>DOMDocument</code> both need <code>libxml2</code> and both build a complete in-memory tree. <code>XMLProcessor</code> walks the document forward as a cursor, keeps modifications in a side buffer, and emits the full updated XML with <code>get_updated_xml()</code> only when you ask for it.</p>
22
23	<p>This design came from WordPress-scale documents such as WXR exports. A migration may only need to rewrite <code>wp:attachment_url</code> values or bump a feed attribute, so the processor optimizes for targeted cursor edits instead of a full validating XML stack.</p>
24
25	<p>Footgun: <strong>Namespace-aware methods use the namespace URI, not the prefix written in the tag.</strong> In WXR, <code>get_attribute( 'wp', 'status' )</code> looks for a namespace literally named <code>wp</code>; for the usual WXR declaration you want <code>get_attribute( 'http://wordpress.org/export/1.2/', 'status' )</code>.</p>
26
27	<p>Footgun: <strong>In streaming mode <code>next_tag()</code> can return false because input ran out, not because the document ended.</strong> Check <code>is_paused_at_incomplete_input()</code> before assuming you're done.</p>
28
29	## Bump every price in a catalog
30
31	<p>Find each <code><book></code>, read its price, write a new one, emit the updated document.</p>
32
33	<!-- snippet:
34	filename: bump-prices.php
35	runnable: true
36	-->
37	```php
38	<?php
39	require '/php-toolkit/vendor/autoload.php';
40
41	use WordPress\XML\XMLProcessor;
42
43	$xml = <<<'XML'
44	<catalog>
45	<book sku="A1" price="29.99"><title>PHP Internals</title></book>
46	<book sku="A2" price="14.50"><title>WordPress at Scale</title></book>
47	</catalog>
48	XML;
49
50	$p = XMLProcessor::create_from_string( $xml );
51	while ( $p->next_tag( 'book' ) ) {
52	$old = (float) $p->get_attribute( '', 'price' );
53	$new = number_format( $old * 1.10, 2, '.', '' );
54	$p->set_attribute( '', 'price', $new );
55	}
56
57	echo $p->get_updated_xml();
58	```
59
60	<!-- expected-output -->
61	```
62	<catalog>
63	<book sku="A1" price="32.99"><title>PHP Internals</title></book>
64	<book sku="A2" price="15.95"><title>WordPress at Scale</title></book>
65	</catalog>
66	```
67
68	## Read namespaced attributes from a WXR export
69
70	<p>WordPress's WXR commonly uses <code>wp:</code>, <code>dc:</code>, and <code>content:</code> prefixes bound to namespace names such as <code>http://wordpress.org/export/1.2/</code>. Pass that expanded namespace name, not the prefix; the processor handles whichever prefix the document actually uses.</p>
71
72	<!-- snippet:
73	filename: wxr-namespaces.php
74	runnable: true
75	-->
76	```php
77	<?php
78	require '/php-toolkit/vendor/autoload.php';
79
80	use WordPress\XML\XMLProcessor;
81
82	$wxr = <<<'XML'
83	<?xml version="1.0"?>
84	<rss xmlns:wp="http://wordpress.org/export/1.2/" xmlns:dc="http://purl.org/dc/elements/1.1/">
85	<channel><item>
86	<title>Hello World</title>
87	<dc:creator>admin</dc:creator>
88	<wp:post_id>42</wp:post_id>
89	<wp:status>publish</wp:status>
90	</item></channel></rss>
91	XML;
92
93	$WP = 'http://wordpress.org/export/1.2/';
94	$DC = 'http://purl.org/dc/elements/1.1/';
95
96	$p = XMLProcessor::create_from_string( $wxr );
97	while ( $p->next_tag( 'item' ) ) {
98	while ( $p->next_token() ) {
99	if ( $p->is_tag_closer() && 'item' === $p->get_tag_local_name() ) break;
100	if ( ! $p->is_tag_opener() ) continue;
101	$ns = $p->get_tag_namespace();
102	$local = $p->get_tag_local_name();
103	$prefix = ( $WP === $ns ) ? 'wp/' : ( ( $DC === $ns ) ? 'dc/' : '' );
104	echo "{$prefix}{$local}: ";
105	while ( $p->next_token() && '#text' !== $p->get_token_name() ) {}
106	echo trim( $p->get_modifiable_text() ) . "\n";
107	}
108	}
109	```
110
111	<!-- expected-output -->
112	```
113	title: Hello World
114	dc/creator: admin
115	wp/post_id: 42
116	wp/status: publish
117	```
118
119	## Rewrite URLs across an entire WXR export
120
121	<p>Large WXR exports can hold many URLs in <code><link></code>, <code><guid></code>, and post content. Streaming the file lets you rewrite large exports without loading the whole XML document into memory.</p>
122
123	<!-- snippet:
124	filename: rewrite-wxr-urls.php
125	runnable: true
126	-->
127	```php
128	<?php
129	require '/php-toolkit/vendor/autoload.php';
130
131	use WordPress\XML\XMLProcessor;
132
133	$wxr = <<<'XML'
134	<?xml version="1.0"?><rss xmlns:wp="http://wordpress.org/export/1.2/"><channel>
135	<wp:base_site_url>https://old.example.com</wp:base_site_url>
136	<item><link>https://old.example.com/2024/post-1</link>
137	<guid>https://old.example.com/?p=1</guid></item>
138	</channel></rss>
139	XML;
140
141	$from = 'https://old.example.com';
142	$to = 'https://new.example.com';
143
144	$p = XMLProcessor::create_from_string( $wxr );
145	$rewritten = 0;
146
147	while ( $p->next_token() ) {
148	if ( '#text' !== $p->get_token_name() ) continue;
149	$text = $p->get_modifiable_text();
150	if ( false === strpos( $text, $from ) ) continue;
151	$p->set_modifiable_text( str_replace( $from, $to, $text ) );
152	$rewritten++;
153	}
154
155	echo "rewrote {$rewritten} text nodes\n\n";
156	echo $p->get_updated_xml();
157	```
158
159	<!-- expected-output -->
160	```
161	rewrote 3 text nodes
162
163	<?xml version="1.0"?><rss xmlns:wp="http://wordpress.org/export/1.2/"><channel>
164	<wp:base_site_url>https://new.example.com</wp:base_site_url>
165	<item><link>https://new.example.com/2024/post-1</link>
166	<guid>https://new.example.com/?p=1</guid></item>
167	</channel></rss>
168	```
169
170	## Parse OPML to extract feed URLs
171
172	<p>OPML is the format Feedly and many readers use to import/export feed lists. Flat, attribute-heavy XML — exactly what a tag processor handles best.</p>
173
174	<!-- snippet:
175	filename: opml.php
176	runnable: true
177	-->
178	```php
179	<?php
180	require '/php-toolkit/vendor/autoload.php';
181
182	use WordPress\XML\XMLProcessor;
183
184	$opml = <<<'XML'
185	<?xml version="1.0"?><opml version="2.0"><head><title>My Feeds</title></head>
186	<body>
187	<outline text="Tech"><outline text="Hacker News" type="rss" xmlUrl="https://news.ycombinator.com/rss"/>
188	<outline text="LWN" type="rss" xmlUrl="https://lwn.net/headlines/rss"/></outline>
189	<outline text="WordPress" type="rss" xmlUrl="https://wordpress.org/news/feed/"/>
190	</body></opml>
191	XML;
192
193	$p = XMLProcessor::create_from_string( $opml );
194	while ( $p->next_tag( 'outline' ) ) {
195	$url = $p->get_attribute( '', 'xmlUrl' );
196	if ( null === $url ) continue;
197	echo $p->get_attribute( '', 'text' ) . "\t" . $url . "\n";
198	}
199	```
200
201	<!-- expected-output -->
202	```
203	Hacker News https://news.ycombinator.com/rss
204	LWN https://lwn.net/headlines/rss
205	WordPress https://wordpress.org/news/feed/
206	```
207