Doc #78252 [Com]: Report a miss information in `Return Values` section of getElementsByTagName

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: 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. Previous Comments: ------------------------------------------------------------------------ [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