Doc #78252 [Com]: Report a miss information in `Return Values` section of getElementsByTagName
| From: | dangtu dot work at gmail dot com | Date: | Sat, 06 Jul 2019 11:52:13 +0000 |
| Subject: | Doc #78252 [Com]: Report a miss information in `Return Values` section of getElementsByTagName | ||
| References: | 1 | Groups: | php.doc.bugs |
| Request: | Send a blank email to doc-bugs+get-16804@lists.php.net to get a copy of this message | ||
Edit report at https://bugs.php.net/bug.php?id=78252&edit=1
ID: 78252
Comment by: dangtu dot work at gmail dot com
Reported by: dangtu dot work at gmail dot com
Summary: Report a miss information in
Return Values section
of getElementsByTagName
Status: Not a bug
Type: Documentation Problem
Package: DOM XML related
Operating System: Windows 10
PHP Version: 7.3.7
Block user comment: N
Private report: N
New Comment:
My bad, I was accidentally pass it with item() method without realize it. Sorry.
Previous Comments:
------------------------------------------------------------------------
[2019-07-06 10:50:25] requinix@php.net
> it will be considered as falsy values in conditional statement
No, an empty DOMNodeList is not considered to be falsy. https://3v4l.org/sVuiD
------------------------------------------------------------------------
[2019-07-06 10:12:06] dangtu dot work at gmail dot com
Thanks for you explanation, @cmb and @requinix.
But don't you think we should clarify the Return Values section? Let me rephrase
the change:
> The function always returns DOMNodeList object. However, if no elements found, DOMNodeList will
> be returned with zero item and it will be considered as falsy values in conditional statement.
------------------------------------------------------------------------
[2019-07-05 11:55:14] cmb@php.net
> If nothing found, a DOMDocument itself will be returned.
No. If no element is found, ::getElementsByTagName() returns a
DOMNodeList with zero items, see <https://3v4l.org/Pluib>.
------------------------------------------------------------------------
[2019-07-05 09:04:48] requinix@php.net
->item(0) is null so saveHTML() will export the entire document.
------------------------------------------------------------------------
[2019-07-05 08:45:44] dangtu dot work at gmail dot com
Description:
------------
---
From manual page: https://php.net/domdocument.getelementsbytagname
---
There is a miss information in Return Values section of
DOMDocument::getElementsByTagName. In the section, it only said:
> A new DOMNodeList object containing all the matched elements
But no info about what will return if no matched elements found!
A sandbox come with result:
http://sandbox.onlinephpfunctions.com/code/3b0f001e462a223188defd42554c8401b3626f8b
Test script:
---------------
<?php
$html = <<< HTML
<article id="p73" class="p-quote">
Albert Einsteinâs Quotes Collection
<blockquote><p>Life is like riding a bicycle. To keep your balance, you must keep
moving.</p></blockquote>
<blockquote><p>Pure mathematics is, in its way, the poetry of logical
ideas.</p></blockquote>
<blockquote><p>Education is what remains after one has forgotten what one has learned in
school.</p></blockquote>
<blockquote><p>Learn from yesterday, live for today, hope for tomorrow. The important
thing is not to stop questioning.</p></blockquote>
<blockquote><p>Logic will get you from A to B. Imagination will take you
everywhere.</p></blockquote>
<blockquote><p>If you canât explain it simply, you donât understand it well
enough.</p></blockquote>
<blockquote><p>The difference between stupidity and genius is that genius has its
limits.</p></blockquote>
</article>
HTML;
class ExtractTag {
private $doc = null;
public function __construct($html) {
$this->doc = new DomDocument();
$content = mb_convert_encoding(
$html,
'HTML-ENTITIES',
'UTF-8'
);
@$this->doc->loadHTML($content);
}
private function getFirstTag($tag) {
return $this->doc->getElementsByTagName($tag)->item(0);
}
private function printFirstTag($tag) {
$firstTag = $this->getFirstTag($tag);
echo $this->doc->saveHTML($firstTag);
}
public function print_image() {
$this->printFirstTag('img');
}
public function print_quote() {
$this->printFirstTag('blockquote');
}
}
$dom = new ExtractTag($html);
echo $dom->print_quote(); #Expect to see a <blockquote>
echo $dom->print_image(); #Expect to see nothing since there is no <img> tag in the html!
Expected result:
----------------
The Return Values should be wrote like this:
If matched elements found, the method will return a new DOMNodeList object containing all the
matched elements. If nothing found, a DOMDocument itself will be returned.
------------------------------------------------------------------------
--
Edit this bug report at https://bugs.php.net/bug.php?id=78252&edit=1