Jetpack_Sitemap_Buffer::is_full() - Code Metrics - Inspection of "Merge pull request #7747 from Automattic/cleanup/5..." - Automattic/jetpack - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Push — update/improve-api-docs ( 94dfd5 )

unknown

created 2017-09-16 15:16 UTC

Jetpack_Sitemap_Buffer::is_full() A

↳ Parent: Jetpack_Sitemap_Buffer

Complexity

Conditions	1
Paths	1

Size

Total Lines	3
Code Lines	2

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
cc	1
dl	0
loc	3
rs	10
c	0
b	0
f	0
eloc	2
nc	1
nop	0

<?php
/**
 * Sitemaps (per the protocol) are essentially lists of XML fragments;
 * lists which are subject to size constraints. The Jetpack_Sitemap_Buffer
 * class abstracts the details of constructing these lists while
 * maintaining the constraints.
 *
 * @since 4.8.0
 * @package Jetpack
 */

/**
 * A buffer for constructing sitemap xml files.
 *
 * Models a list of strings such that
 *
 * 1. the list must have a bounded number of entries,
 * 2. the concatenation of the strings must have bounded
 *      length (including some header and footer strings), and
 * 3. each item has a timestamp, and we need to keep track
 *      of the most recent timestamp of the items in the list.
 *
 * @since 4.8.0
 */
abstract class Jetpack_Sitemap_Buffer {

	/**
	 * Largest number of items the buffer can hold.
	 *
	 * @access protected
	 * @since 4.8.0
	 * @var int $item_capacity The item capacity.
	 */
	protected $item_capacity;

	/**
	 * Largest number of bytes the buffer can hold.
	 *
	 * @access protected
	 * @since 4.8.0
	 * @var int $byte_capacity The byte capacity.
	 */
	protected $byte_capacity;

	/**
	 * Flag which detects when the buffer is full.
	 *
	 * @access protected
	 * @since 4.8.0
	 * @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.
	 */
	protected $is_full_flag;

	/**
	 * Flag which detects when the buffer is empty.
	 *
	 * @access protected
	 * @since 4.8.0
	 * @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.
	 */
	protected $is_empty_flag;

	/**
	 * The most recent timestamp seen by the buffer.
	 *
	 * @access protected
	 * @since 4.8.0
	 * @var string $timestamp Must be in 'YYYY-MM-DD hh:mm:ss' format.
	 */
	protected $timestamp;

	/**
	 * The DOM document object that is currently being used to construct the XML doc.
	 *
	 * @access protected
	 * @since 5.3.0
	 * @var DOMDocument $doc
	 */
	protected $doc = null;

	/**
	 * The root DOM element object that holds everything inside. Do not use directly, call
	 * the get_root_element getter method instead.
	 *
	 * @access protected
	 * @since 5.3.0
	 * @var DOMElement $doc
	 */
	protected $root = null;

	/**
	 * Helper class to construct sitemap paths.
	 *
	 * @since 5.3.0
	 * @protected
	 * @var Jetpack_Sitemap_Finder
	 */
	protected $finder;

	/**
	 * Construct a new Jetpack_Sitemap_Buffer.
	 *
	 * @since 4.8.0
	 *
	 * @param int    $item_limit The maximum size of the buffer in items.
	 * @param int    $byte_limit The maximum size of the buffer in bytes.
	 * @param string $time The initial datetime of the buffer. Must be in 'YYYY-MM-DD hh:mm:ss' format.
	 */
	public function __construct( $item_limit, $byte_limit, $time ) {
		$this->is_full_flag = false;
		$this->timestamp = $time;

		$this->finder = new Jetpack_Sitemap_Finder();
		$this->doc = new DOMDocument( '1.0', 'UTF-8' );

		$this->item_capacity = max( 1, intval( $item_limit ) );
		$this->byte_capacity = max( 1, intval( $byte_limit ) ) - strlen( $this->doc->saveXML() );
	}

	/**
	 * Returns a DOM element that contains all sitemap elements.
	 *
	 * @access protected
	 * @since 5.3.0
	 * @return DOMElement $root
	 */
	abstract protected function get_root_element();

	/**
	 * Append an item to the buffer, if there is room for it,
	 * and set is_empty_flag to false. If there is no room,
	 * we set is_full_flag to true. If $item is null,
	 * don't do anything and report success.
	 *
	 * @since 4.8.0
	 *
	 * @param string $item The item to be added.
	 *
	 * @return bool True if the append succeeded, False if not.
	 */
	public function try_to_add_item( $item ) {
		_deprecated_function(
			'Jetpack_Sitemap_Buffer::try_to_add_item',
			'5.3.0',
			'Jetpack_Sitemap_Buffer::append'
		);
		$this->append( $item );
function acceptsInteger($int) { }

$x = '123'; // string "123"

// Instead of
acceptsInteger($x);

// we recommend to use
acceptsInteger((integer) $x);
	}

	/**
	 * Append an item to the buffer, if there is room for it,
	 * and set is_empty_flag to false. If there is no room,
	 * we set is_full_flag to true. If $item is null,
	 * don't do anything and report success.
	 *
	 * @since 5.3.0
	 *
	 * @param array $array The item to be added.
	 *
	 * @return bool True if the append succeeded, False if not.
	 */
	public function append( $array ) {
		if ( is_null( $array ) ) {
			return true;
		}

		if ( $this->is_full_flag ) {
			return false;
		}

		if ( 0 >= $this->item_capacity || 0 >= $this->byte_capacity ) {
			$this->is_full_flag = true;
			return false;
		} else {
			$this->item_capacity -= 1;
			$added_element = $this->array_to_xml_string( $array, $this->get_root_element(), $this->doc );

			$this->byte_capacity -= strlen( $this->doc->saveXML( $added_element ) );

			return true;
		}
	}

	/**
	 * Retrieve the contents of the buffer.
	 *
	 * @since 4.8.0
	 *
	 * @return string The contents of the buffer (with the footer included).
	 */
	public function contents() {
		if( $this->is_empty() ) {
			// The sitemap should have at least the root element added to the DOM
			$this->get_root_element();
		}
		return $this->doc->saveXML();
	}

	/**
	 * Retrieve the document object.
	 *
	 * @since 5.3.0
	 * @return DOMDocument $doc
	 */
	public function get_document() {
		return $this->doc;
	}

	/**
	 * Detect whether the buffer is full.
	 *
	 * @since 4.8.0
	 *
	 * @return bool True if the buffer is full, false otherwise.
	 */
	public function is_full() {
		return $this->is_full_flag;
	}

	/**
	 * Detect whether the buffer is empty.
	 *
	 * @since 4.8.0
	 *
	 * @return bool True if the buffer is empty, false otherwise.
	 */
	public function is_empty() {
		return (
			! isset( $this->root )
			|| ! $this->root->hasChildNodes()
		);
	}

	/**
	 * Update the timestamp of the buffer.
	 *
	 * @since 4.8.0
	 *
	 * @param string $new_time A datetime string in 'YYYY-MM-DD hh:mm:ss' format.
	 */
	public function view_time( $new_time ) {
		$this->timestamp = max( $this->timestamp, $new_time );
	}

	/**
	 * Retrieve the timestamp of the buffer.
	 *
	 * @since 4.8.0
	 *
	 * @return string A datetime string in 'YYYY-MM-DD hh:mm:ss' format.
	 */
	public function last_modified() {
		return $this->timestamp;
	}

	/**
	 * Render an associative array as an XML string. This is needed because
	 * SimpleXMLElement only handles valid XML, but we sometimes want to
	 * pass around (possibly invalid) fragments. Note that 'null' values make
	 * a tag self-closing; this is only sometimes correct (depending on the
	 * version of HTML/XML); see the list of 'void tags'.
	 *
	 * Example:
	 *
	 * array(
	 *   'html' => array(                    |<html xmlns="foo">
	 *     'head' => array(                  |  <head>
	 *       'title' => 'Woo!',              |    <title>Woo!</title>
	 *     ),                                |  </head>
	 *     'body' => array(             ==>  |  <body>
	 *       'h2' => 'Some thing',           |    <h2>Some thing</h2>
	 *       'p'  => 'it's all up ons',      |    <p>it's all up ons</p>
	 *       'br' => null,                   |    <br />
	 *     ),                                |  </body>
	 *   ),                                  |</html>
	 * )
	 *
	 * @access protected
	 * @since 3.9.0
	 * @since 4.8.0 Rename, add $depth parameter, and change return type.
	 * @since 5.3.0 Refactor, remove $depth parameter, add $parent and $root, make access protected.
	 *
	 * @param array  $array A recursive associative array of tag/child relationships.
	 * @param DOMElement $parent (optional) an element to which new children should be added.

	 * @param DOMDocument $root (optional) the parent document.

	 *
	 * @return string|DOMDocument The rendered XML string or an object if root element is specified.
	 */
	protected function array_to_xml_string( $array, $parent = null, $root = null ) {
		$return_string = false;

		if ( null === $parent ) {
			$return_string = true;
			$parent = $root = new DOMDocument();
		}

		if ( is_array( $array ) ) {

			foreach ( $array as $key => $value ) {
				$element = $root->createElement( $key );
function someFunction(A $objectMaybe = null)
{
    if ($objectMaybe instanceof A) {
        $objectMaybe->doSomething();
    }
}
				$parent->appendChild( $element );

				if ( is_array( $value ) ) {
					foreach ( $value as $child_key => $child_value ) {
						$child = $root->createElement( $child_key );
						$element->appendChild( $child );
						$child->appendChild( self::array_to_xml_string( $child_value, $child, $root ) );
					}
				} else {
					$element->appendChild(
						$root->createTextNode( $value )
					);
				}
			}
		} else {
			$element = $root->createTextNode( $array );
			$parent->appendChild( $element );
		}

		if ( $return_string ) {
			return $root->saveHTML();
		} else {
			return $element;
function myFunction($a) {
    switch ($a) {
        case 'foo':
            $x = 1;
            break;

        case 'bar':
            $x = 2;
            break;
    }

    // $x is potentially undefined here.
    echo $x;
}
		}
	}
}


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	View Code Duplication	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		*
137		* @param string $item The item to be added.
138		*
139		* @return bool True if the append succeeded, False if not.
140		*/
141		public function try_to_add_item( $item ) {
142		_deprecated_function(
143		'Jetpack_Sitemap_Buffer::try_to_add_item',
144		'5.3.0',
145		'Jetpack_Sitemap_Buffer::append'
146		);
147		$this->append( $item );
		0 ignored issues – show Documentation introduced 2017-06-13 14:15 UTC by Report Bug Copy Issue Report `$item` is of type `string`, but the function expects a `array`. It seems like the type of the argument is not accepted by the function/method which you are calling. In some cases, in particular if PHP’s automatic type-juggling kicks in this might be fine. In other cases, however this might be a bug. We suggest to add an explicit type cast like in the following example: function acceptsInteger($int) { } $x = '123'; // string "123" // Instead of acceptsInteger($x); // we recommend to use acceptsInteger((integer) $x); Loading history...
148		}
149
150		/**
151		* Append an item to the buffer, if there is room for it,
152		* and set is_empty_flag to false. If there is no room,
153		* we set is_full_flag to true. If $item is null,
154		* don't do anything and report success.
155		*
156		* @since 5.3.0
157		*
158		* @param array $array The item to be added.
159		*
160		* @return bool True if the append succeeded, False if not.
161		*/
162		public function append( $array ) {
163		if ( is_null( $array ) ) {
164		return true;
165		}
166
167		if ( $this->is_full_flag ) {
168		return false;
169		}
170
171		if ( 0 >= $this->item_capacity \|\| 0 >= $this->byte_capacity ) {
172		$this->is_full_flag = true;
173		return false;
174		} else {
175		$this->item_capacity -= 1;
176		$added_element = $this->array_to_xml_string( $array, $this->get_root_element(), $this->doc );
177
178		$this->byte_capacity -= strlen( $this->doc->saveXML( $added_element ) );
179
180		return true;
181		}
182		}
183
184		/**
185		* Retrieve the contents of the buffer.
186		*
187		* @since 4.8.0
188		*
189		* @return string The contents of the buffer (with the footer included).
190		*/
191		public function contents() {
192		if( $this->is_empty() ) {
193		// The sitemap should have at least the root element added to the DOM
194		$this->get_root_element();
195		}
196		return $this->doc->saveXML();
197		}
198
199		/**
200		* Retrieve the document object.
201		*
202		* @since 5.3.0
203		* @return DOMDocument $doc
204		*/
205		public function get_document() {
206		return $this->doc;
207		}
208
209		/**
210		* Detect whether the buffer is full.
211		*
212		* @since 4.8.0
213		*
214		* @return bool True if the buffer is full, false otherwise.
215		*/
216		public function is_full() {
217		return $this->is_full_flag;
218		}
219
220		/**
221		* Detect whether the buffer is empty.
222		*
223		* @since 4.8.0
224		*
225		* @return bool True if the buffer is empty, false otherwise.
226		*/
227		public function is_empty() {
228		return (
229		! isset( $this->root )
230		\|\| ! $this->root->hasChildNodes()
231		);
232		}
233
234		/**
235		* Update the timestamp of the buffer.
236		*
237		* @since 4.8.0
238		*
239		* @param string $new_time A datetime string in 'YYYY-MM-DD hh:mm:ss' format.
240		*/
241		public function view_time( $new_time ) {
242		$this->timestamp = max( $this->timestamp, $new_time );
243		}
244
245		/**
246		* Retrieve the timestamp of the buffer.
247		*
248		* @since 4.8.0
249		*
250		* @return string A datetime string in 'YYYY-MM-DD hh:mm:ss' format.
251		*/
252		public function last_modified() {
253		return $this->timestamp;
254		}
255
256		/**
257		* Render an associative array as an XML string. This is needed because
258		* SimpleXMLElement only handles valid XML, but we sometimes want to
259		* pass around (possibly invalid) fragments. Note that 'null' values make
260		* a tag self-closing; this is only sometimes correct (depending on the
261		* version of HTML/XML); see the list of 'void tags'.
262		*
263		* Example:
264		*
265		* array(
266		* 'html' => array( \|<html xmlns="foo">
267		* 'head' => array( \| <head>
268		* 'title' => 'Woo!', \| <title>Woo!</title>
269		* ), \| </head>
270		* 'body' => array( ==> \| <body>
271		* 'h2' => 'Some thing', \| <h2>Some thing</h2>
272		* 'p' => 'it's all up ons', \| <p>it's all up ons</p>
273		* 'br' => null, \| <br />
274		* ), \| </body>
275		* ), \|</html>
276		* )
277		*
278		* @access protected
279		* @since 3.9.0
280		* @since 4.8.0 Rename, add $depth parameter, and change return type.
281		* @since 5.3.0 Refactor, remove $depth parameter, add $parent and $root, make access protected.
282		*
283		* @param array $array A recursive associative array of tag/child relationships.
284		* @param DOMElement $parent (optional) an element to which new children should be added.
		0 ignored issues – show Documentation introduced 2017-06-12 18:00 UTC by Report Bug Copy Issue Report Should the type for parameter `$parent` not be `DOMElement\|null`? This check looks for `@param` annotations where the type inferred by our type inference engine differs from the declared type. It makes a suggestion as to what type it considers more descriptive. Most often this is a case of a parameter that can be null in addition to its declared types. Loading history...
285		* @param DOMDocument $root (optional) the parent document.
		0 ignored issues – show Documentation introduced 2017-06-12 18:00 UTC by Report Bug Copy Issue Report Should the type for parameter `$root` not be `DOMDocument\|null`? This check looks for `@param` annotations where the type inferred by our type inference engine differs from the declared type. It makes a suggestion as to what type it considers more descriptive. Most often this is a case of a parameter that can be null in addition to its declared types. Loading history...
286		*
287		* @return string\|DOMDocument The rendered XML string or an object if root element is specified.
288		*/
289		protected function array_to_xml_string( $array, $parent = null, $root = null ) {
290		$return_string = false;
291
292		if ( null === $parent ) {
293		$return_string = true;
294		$parent = $root = new DOMDocument();
295		}
296
297		if ( is_array( $array ) ) {
298
299		foreach ( $array as $key => $value ) {
300		$element = $root->createElement( $key );
		0 ignored issues – show Bug introduced 2017-06-12 18:00 UTC by Report Bug Copy Issue Report It seems like `$root` is not always an object, but can also be of type `null`. Maybe add an additional type check? If a variable is not always an object, we recommend to add an additional type check to ensure your method call is safe: function someFunction(A $objectMaybe = null) { if ($objectMaybe instanceof A) { $objectMaybe->doSomething(); } } Loading history...
301		$parent->appendChild( $element );
302
303		if ( is_array( $value ) ) {
304		foreach ( $value as $child_key => $child_value ) {
305		$child = $root->createElement( $child_key );
306		$element->appendChild( $child );
307		$child->appendChild( self::array_to_xml_string( $child_value, $child, $root ) );
308		}
309		} else {
310		$element->appendChild(
311		$root->createTextNode( $value )
312		);
313		}
314		}
315		} else {
316		$element = $root->createTextNode( $array );
317		$parent->appendChild( $element );
318		}
319
320		if ( $return_string ) {
321		return $root->saveHTML();
322		} else {
323		return $element;
		0 ignored issues – show Bug introduced 2017-06-13 14:15 UTC by Report Bug Copy Issue Report The variable `$element` does not seem to be defined for all execution paths leading up to this point. If you define a variable conditionally, it can happen that it is not defined for all execution paths. Let’s take a look at an example: function myFunction($a) { switch ($a) { case 'foo': $x = 1; break; case 'bar': $x = 2; break; } // $x is potentially undefined here. echo $x; } In the above example, the variable `$x` is defined if you pass “foo” or “bar” as argument for `$a`. However, since the `switch` statement has no default case statement, if you pass any other value, the variable `$x` would be undefined. Available Fixes Check for existence of the variable explicitly: function myFunction($a) { switch ($a) { case 'foo': $x = 1; break; case 'bar': $x = 2; break; } if (isset($x)) { // Make sure it's always set. echo $x; } } Define a default value for the variable: function myFunction($a) { $x = ''; // Set a default which gets overridden for certain paths. switch ($a) { case 'foo': $x = 1; break; case 'bar': $x = 2; break; } echo $x; } Add a value for the missing path: function myFunction($a) { switch ($a) { case 'foo': $x = 1; break; case 'bar': $x = 2; break; // We add support for the missing case. default: $x = ''; break; } echo $x; } Loading history...
324		}
325		}
326		}
327

Automattic / jetpack

Push — update/improve-api-docs ( 94dfd5 )

Jetpack_Sitemap_Buffer::is_full() A

Complexity

Size

Duplication

Importance

Available Fixes

Duplication Side-by-Side

Filter issues like