Doc #55264 [Opn->Bgs]: Example does nothing

Edit report at https://bugs.php.net/bug.php?id=55264&edit=1 ID: 55264 Updated by: salathe@php.net Reported by: jeremybotto at gmail dot com Summary: Example does nothing -Status: Open +Status: Bogus Type: Documentation Problem Package: Documentation problem Operating System: php PHP Version: Irrelevant Block user comment: N Private report: N New Comment: Thank you for getting down to some numbered points, Jeremy. Bug reports are not the place at all for general rambling comments; they're for reporting deficiencies to get fixed. Point number 2 (Use all of the parameters and switches in at least one example.) should be mostly covered in the documentation pages covering those parameters. If you find a page without a sufficient example then please do create a new, concise, report for each separate defect. I would also encourage you, should you wish, to take steps towards rectifying this sort of thing yourself by submitting a patch in the Online Documentation Editor (https://edit.php.net) which allows anyone to make changes to the documentation sources. As for this particular bug report, the initial comment was that the example for SimpleXMLElement::addAttribute() was expected, and failed, to add an attribute to an XML file. This is not the expected result of that example so the report will be marked as "bogus". P.S. mfonda, asXML() handles writing to files too, as documented, $sxe- >asXML("my_xml_file.xml") Previous Comments: ------------------------------------------------------------------------ [2011-07-27 17:04:22] mfonda@php.net All pages including 'example.php' note that it is a file containing an XML string, and that it can be found on the basic usage page, and they link to the basic usage page. I think you're misunderstanding how SimpleXMLElement::addAttribute works. In the description, it states "Adds an attribute to the SimpleXML element." addAttribute doesn't modify any file, it modifies the SimpleXMLElement object. If you wish to output the XML represented by a SimpleXMLElement object, you can use the SimpleXMLElement::asXML() method, as is done in the examples. If you look at the XML output in the example versus the original string in example.php, you'll see that attributes were indeed added. If you want to write to a file, you could do something like file_put_contents('my_xml_file.xml', $sxe->asXML()); ------------------------------------------------------------------------ [2011-07-27 16:42:12] jeremybotto at gmail dot com The recommendations I receive from PHP developers is to not use SimpleXML because it is too difficult and complicated. Instead, use domdocument, which is also complicated. Also, don't use the php manual to learn it. I'm sure that you are already well aware of the flaws in the documentation. I seriously doubt anyone is going to take action. However, I'll entertain you, against my will and better judgment: 1) Include xml files, not php files, in the examples. 2) Use all of the parameters and switches in at least one example. 3) Use xml for the output unless another output format is specified, in which case, use xml output and the specified output where applicable. ------------------------------------------------------------------------ [2011-07-27 13:47:22] salathe@php.net Your comments make no sense in the context of a documentation bug report. If you feel something is missing from the documentation, or something documented is incorrect, please outline what you want to see changed. ------------------------------------------------------------------------ [2011-07-27 12:31:05] jeremybotto at gmail dot com That doesn't help at all. The output is in php, even though I use asXML();, and it doesn't change the file. It just changes the source code of the page. All of the examples change one file and output to the same file, and that doesn't leave any room for version control. Also, at http://www.php.net/manual/en/simplexml.examples-basic.php, if you look at the examples, they all output in plain text for this same reason. This doesn't say anything about how the nesting is manipulated by SimpleXML, which is crucial to understanding SimpleXML and makes the manual impossible to understand. Look at a specific example: <?php include 'example.php'; $xml = new SimpleXMLElement($xmlstr); foreach ($xml->xpath('//character') as $character) { echo $character->name, 'played by ', $character->actor, PHP_EOL; } ?> '//' serves as a wildcard. To specify absolute paths, omit one of the slashes. The above example will output: Ms. Coder played by Onlivia Actora Mr. Coder played by El ActÓr Fortunately for us, they've followed the example of php.net and not included the XML file, so we can't tell what they're manipulating, but it looks like this: <characters><character><name>text</name><actor>text</actor></character>. The output doesn't include the element nodes, so there's no way to tell if they have been stripped, if new ones have been added, or just what. Because the document doesn't actually come across as XML, it appears that SimpleXML acts to convert XML into plain text, but everyone knows that isn't its intended use. It's supposed to allow people to manipulate XML. So, it should give XML output from XML input unless otherwise specified, rather than giving raw text. ------------------------------------------------------------------------ [2011-07-22 04:52:23] salathe@php.net Can you clarify a few things, please? When you say "there is no visible change", where did you expect anything to be changed (the example should print the manipulated XML to the screen, terminal, wherever)? What do you mean by "verifies that a translation of the input matches the input", there is no translation of any kind going on. For what it's worth, here's an include-less version of that example showing the expected output: http://codepad.org/gwx8oJpw Finally, with regards to the SimpleXML examples requiring the example.php file, this was done to avoid clogging up the examples with 28 lines of code again and again. Requiring external files is not something we usually ask for examples, which should be able to run "standalone" ideally. ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at https://bugs.php.net/bug.php?id=55264 -- Edit this bug report at https://bugs.php.net/bug.php?id=55264&edit=1