jetpack / modules / sitemaps / sitemap-buffer.php

sitemap-buffer.php in Jetpack – WP Security, Backup, Speed, & Growth 7.2.2, at modules/sitemaps/sitemap-buffer.php

326 lines 8.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Sitemaps (per the protocol) are essentially lists of XML fragments;
4	* lists which are subject to size constraints. The Jetpack_Sitemap_Buffer
5	* class abstracts the details of constructing these lists while
6	* maintaining the constraints.
7	*
8	* @since 4.8.0
9	* @package Jetpack
10	*/
11
12	/**
13	* A buffer for constructing sitemap xml files.
14	*
15	* Models a list of strings such that
16	*
17	* 1. the list must have a bounded number of entries,
18	* 2. the concatenation of the strings must have bounded
19	* length (including some header and footer strings), and
20	* 3. each item has a timestamp, and we need to keep track
21	* of the most recent timestamp of the items in the list.
22	*
23	* @since 4.8.0
24	*/
25	abstract class Jetpack_Sitemap_Buffer {
26
27	/**
28	* Largest number of items the buffer can hold.
29	*
30	* @access protected
31	* @since 4.8.0
32	* @var int $item_capacity The item capacity.
33	*/
34	protected $item_capacity;
35
36	/**
37	* Largest number of bytes the buffer can hold.
38	*
39	* @access protected
40	* @since 4.8.0
41	* @var int $byte_capacity The byte capacity.
42	*/
43	protected $byte_capacity;
44
45	/**
46	* Flag which detects when the buffer is full.
47	*
48	* @access protected
49	* @since 4.8.0
50	* @var bool $is_full_flag The flag value. This flag is set to false on construction and only flipped to true if we've tried to add something and failed.
51	*/
52	protected $is_full_flag;
53
54	/**
55	* Flag which detects when the buffer is empty.
56	*
57	* @access protected
58	* @since 4.8.0
59	* @var bool $is_empty_flag The flag value. This flag is set to true on construction and only flipped to false if we've tried to add something and succeeded.
60	*/
61	protected $is_empty_flag;
62
63	/**
64	* The most recent timestamp seen by the buffer.
65	*
66	* @access protected
67	* @since 4.8.0
68	* @var string $timestamp Must be in 'YYYY-MM-DD hh:mm:ss' format.
69	*/
70	protected $timestamp;
71
72	/**
73	* The DOM document object that is currently being used to construct the XML doc.
74	*
75	* @access protected
76	* @since 5.3.0
77	* @var DOMDocument $doc
78	*/
79	protected $doc = null;
80
81	/**
82	* The root DOM element object that holds everything inside. Do not use directly, call
83	* the get_root_element getter method instead.
84	*
85	* @access protected
86	* @since 5.3.0
87	* @var DOMElement $doc
88	*/
89	protected $root = null;
90
91	/**
92	* Helper class to construct sitemap paths.
93	*
94	* @since 5.3.0
95	* @protected
96	* @var Jetpack_Sitemap_Finder
97	*/
98	protected $finder;
99
100	/**
101	* Construct a new Jetpack_Sitemap_Buffer.
102	*
103	* @since 4.8.0
104	*
105	* @param int $item_limit The maximum size of the buffer in items.
106	* @param int $byte_limit The maximum size of the buffer in bytes.
107	* @param string $time The initial datetime of the buffer. Must be in 'YYYY-MM-DD hh:mm:ss' format.
108	*/
109	public function __construct( $item_limit, $byte_limit, $time ) {
110	$this->is_full_flag = false;
111	$this->timestamp = $time;
112
113	$this->finder = new Jetpack_Sitemap_Finder();
114	$this->doc = new DOMDocument( '1.0', 'UTF-8' );
115
116	$this->item_capacity = max( 1, intval( $item_limit ) );
117	$this->byte_capacity = max( 1, intval( $byte_limit ) ) - strlen( $this->doc->saveXML() );
118	}
119
120	/**
121	* Returns a DOM element that contains all sitemap elements.
122	*
123	* @access protected
124	* @since 5.3.0
125	* @return DOMElement $root
126	*/
127	abstract protected function get_root_element();
128
129	/**
130	* Append an item to the buffer, if there is room for it,
131	* and set is_empty_flag to false. If there is no room,
132	* we set is_full_flag to true. If $item is null,
133	* don't do anything and report success.
134	*
135	* @since 4.8.0
136	* @deprecated 5.3.0 Use Jetpack_Sitemap_Buffer::append.
137	*
138	* @param string $item The item to be added.
139	*/
140	public function try_to_add_item( $item ) {
141	_deprecated_function(
142	'Jetpack_Sitemap_Buffer::try_to_add_item',
143	'5.3.0',
144	'Jetpack_Sitemap_Buffer::append'
145	);
146	$this->append( $item );
147	}
148
149	/**
150	* Append an item to the buffer, if there is room for it,
151	* and set is_empty_flag to false. If there is no room,
152	* we set is_full_flag to true. If $item is null,
153	* don't do anything and report success.
154	*
155	* @since 5.3.0
156	*
157	* @param array $array The item to be added.
158	*
159	* @return bool True if the append succeeded, False if not.
160	*/
161	public function append( $array ) {
162	if ( is_null( $array ) ) {
163	return true;
164	}
165
166	if ( $this->is_full_flag ) {
167	return false;
168	}
169
170	if ( 0 >= $this->item_capacity \|\| 0 >= $this->byte_capacity ) {
171	$this->is_full_flag = true;
172	return false;
173	} else {
174	$this->item_capacity -= 1;
175	$added_element = $this->array_to_xml_string( $array, $this->get_root_element(), $this->doc );
176
177	$this->byte_capacity -= strlen( $this->doc->saveXML( $added_element ) );
178
179	return true;
180	}
181	}
182
183	/**
184	* Retrieve the contents of the buffer.
185	*
186	* @since 4.8.0
187	*
188	* @return string The contents of the buffer (with the footer included).
189	*/
190	public function contents() {
191	if ( $this->is_empty() ) {
192	// The sitemap should have at least the root element added to the DOM.
193	$this->get_root_element();
194	}
195	return $this->doc->saveXML();
196	}
197
198	/**
199	* Retrieve the document object.
200	*
201	* @since 5.3.0
202	* @return DOMDocument $doc
203	*/
204	public function get_document() {
205	return $this->doc;
206	}
207
208	/**
209	* Detect whether the buffer is full.
210	*
211	* @since 4.8.0
212	*
213	* @return bool True if the buffer is full, false otherwise.
214	*/
215	public function is_full() {
216	return $this->is_full_flag;
217	}
218
219	/**
220	* Detect whether the buffer is empty.
221	*
222	* @since 4.8.0
223	*
224	* @return bool True if the buffer is empty, false otherwise.
225	*/
226	public function is_empty() {
227	return (
228	! isset( $this->root )
229	\|\| ! $this->root->hasChildNodes()
230	);
231	}
232
233	/**
234	* Update the timestamp of the buffer.
235	*
236	* @since 4.8.0
237	*
238	* @param string $new_time A datetime string in 'YYYY-MM-DD hh:mm:ss' format.
239	*/
240	public function view_time( $new_time ) {
241	$this->timestamp = max( $this->timestamp, $new_time );
242	}
243
244	/**
245	* Retrieve the timestamp of the buffer.
246	*
247	* @since 4.8.0
248	*
249	* @return string A datetime string in 'YYYY-MM-DD hh:mm:ss' format.
250	*/
251	public function last_modified() {
252	return $this->timestamp;
253	}
254
255	/**
256	* Render an associative array as an XML string. This is needed because
257	* SimpleXMLElement only handles valid XML, but we sometimes want to
258	* pass around (possibly invalid) fragments. Note that 'null' values make
259	* a tag self-closing; this is only sometimes correct (depending on the
260	* version of HTML/XML); see the list of 'void tags'.
261	*
262	* Example:
263	*
264	* array(
265	* 'html' => array( \|<html xmlns="foo">
266	* 'head' => array( \| <head>
267	* 'title' => 'Woo!', \| <title>Woo!</title>
268	* ), \| </head>
269	* 'body' => array( ==> \| <body>
270	* 'h2' => 'Some thing', \| <h2>Some thing</h2>
271	* 'p' => 'it's all up ons', \| <p>it's all up ons</p>
272	* 'br' => null, \| <br />
273	* ), \| </body>
274	* ), \|</html>
275	* )
276	*
277	* @access protected
278	* @since 3.9.0
279	* @since 4.8.0 Rename, add $depth parameter, and change return type.
280	* @since 5.3.0 Refactor, remove $depth parameter, add $parent and $root, make access protected.
281	*
282	* @param array $array A recursive associative array of tag/child relationships.
283	* @param DOMElement $parent (optional) an element to which new children should be added.
284	* @param DOMDocument $root (optional) the parent document.
285	*
286	* @return string\|DOMDocument The rendered XML string or an object if root element is specified.
287	*/
288	protected function array_to_xml_string( $array, $parent = null, $root = null ) {
289	$return_string = false;
290
291	if ( null === $parent ) {
292	$return_string = true;
293	$parent = $root = new DOMDocument();
294	}
295
296	if ( is_array( $array ) ) {
297
298	foreach ( $array as $key => $value ) {
299	$element = $root->createElement( $key );
300	$parent->appendChild( $element );
301
302	if ( is_array( $value ) ) {
303	foreach ( $value as $child_key => $child_value ) {
304	$child = $root->createElement( $child_key );
305	$element->appendChild( $child );
306	$child->appendChild( self::array_to_xml_string( $child_value, $child, $root ) );
307	}
308	} else {
309	$element->appendChild(
310	$root->createTextNode( $value )
311	);
312	}
313	}
314	} else {
315	$element = $root->createTextNode( $array );
316	$parent->appendChild( $element );
317	}
318
319	if ( $return_string ) {
320	return $root->saveHTML();
321	} else {
322	return $element;
323	}
324	}
325	}
326