<<css mode="next" class="sidebar"></css>> (((
- '''<a href="/docs/fXML">Class Documentation</a>''' - <a href="/api/fXML">API Reference</a> - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fXML.php" target="_blank">Source Code</a>
<<toc></toc>> )))
The fXML class provides functionality to read and create XML. An fXML object represents an XML string for reading/traversing, but does not allow modification. The static methods ::encode() and ::sendHeader() are useful when creating XML.
The fXML constructor will accept four different types of sources for the XML to represent:
1. An fFile object 2. A file path 3. A URL 4. An XML string
XML files with invalid data will cause an fValidationException to be thrown.
When fetching XML from a URL, an optional second parameter, `$timeout`, can be specified. If not specified, the `default_socket_timeout` ini setting is used.
Two of the most common errors when creating XML are encoding characters as HTML entities for XML and delivering `ISO-8859-1` (or `Windows-1252`) encoded XML as `UTF-8`. An optional boolean parameter, `$fix_entities_encoding` can fix both of these problems.
In XML, there are only five pre-defined named entities: `&`, `>`, `<`, `"` and `'`. All other named entities from HTML will cause a parse error if included in XML without further encoding. For instance, `’` is invalid, but `’` or `’` is valid.
`$fix_entities_encoding` will take
and convert it to
before passing the XML to the parser.
If no encoding is specified for an XML document, the encoded is assumed to be UTF-8. Many developers not familiar with XML and issues related to encoding will omit the encoding attribute of the `` tag and will insert `ISO-8859-1` or `Windows-1252` (also called Latin or Latin 1) content.
fXML will throw an exception when such an XML document is parsed, since the parser being used will find invalid UTF-8 characters and give up encoding. The `$fix_entities_encoding` parameter will detect non-UTF-8 characters for documents defined as UTF-8 (whether explicitly or by omission of the encoding attribute) and convert the content.
Information about the root XML element that was passed into the constructor can be accessed by the following methods:
|| Method || Description || || ::getName() || Returns the name of the element without any preceding namespace prefix || || ::getNamespace() || Returns the full namespace URI for the element, if any || || ::getPrefix() || Returns the namespace prefix for the element, if any || || ::getText() || Returns the text content of the element ||
The raw XML being modeled by the fXML object can be retrieved by calling the method ::toXML().
Attributes of the XML element can be accessed using array notation.
The text content of children of the XML element can be accessed by requesting object memebers.
For anything beyond attribute and child element text content of the root XML element, the ::xpath() method will need to be used. This method returns an array of all matching parts of the XML file.
If you aren't familiar with XPath, the Wikipedia page about XPath 1.0 is a good place to start. XPath allow traversal of the XML file using element names combined with predicates and functions.
- xpath() accepts two parameter, the XPath `$path`, and optionally a boolean flag, `$first_only`, to return only the first match.
- '''XML Element:''' an fXML object with an integer array key - '''Attribute:''' a string with the array key being the attribute name - '''Text Content:''' a string with an integer array key
It is also possible to pull back just the first matched element by passing the second parameter as `TRUE`.
When using XPath, array-style attribute access or child element text content access, it can be useful to set a custom namespace prefix to allow for compatibility with various XML sources. The method ::addCustomPrefix() accepts two parameters, the `$ns_prefix` to register and its corresponding `$namespace`. One registered, this prefix will be available throughout fXML.
When creating XML documents, such as RSS feeds, it is necessary to create properly encoded XML, otherwise strict XML parsers will not be able to parse the document. The ::encode() method will ensure that all content is properly encoded for including in a UTF-8 XML file.
Here is an example of usage:
When sending XML files over HTTP, the method ::sendHeader() should be called ensure that the `Content-Type` header is set to the correct value of `text/xml; charset=utf-8`. The `utf-8` character set encoding is specified since all of Flourish is built to work with UTF-8 and all XML parsers must support that character set.