CLXXVII. XML Parser Functions
Wstęp
XML (eXtensible Markup Language) is a data format for structured document interchange on the Web. It is a standard defined by The World Wide Web consortium (W3C). Information about XML and related technologies can be found at https://www.w3.org/XML/.
This PHP extension implements support for James Clark's expat in PHP. This toolkit lets you parse, but not validate, XML documents. It supports three source character encodings also provided by PHP: US-ASCII, ISO-8859-1 and UTF-8. UTF-16 is not supported.
This extension lets you create XML parsers and then define handlers for different XML events. Each XML parser also has a few parameters you can adjust.
Wymagania
This extension uses an expat compat layer by default. It can use also expat, which can be found at https://www.jclark.com/xml/expat.html. The Makefile that comes with expat does not build a library by default, you can use this make rule for that:
libexpat.a: $(OBJS) ar -rc $@ $(OBJS) ranlib $@ |
Instalacja
Domyślnie te funkcje są włączone i używają dołączonej biblioteki expat.
Możesz wyłączyć wsparcie dla XML za pomocą
--disable-xml
.
Jeżeli kompilujesz PHP jako moduł do Apache w wersji 1.3.9 lub późniejszej, wówczas
PHP automatycznie użyje biblioteki expat
dołączonej do Apache. Jeśli nie chcesz używać dołączonej wersji biblioteki
expat to skonfiguruj PHP z --with-expat-dir=KATALOG
gdzie KATALOG powinien wskazywać na katalog gdzie zainstalowano expat.
PHP w wersji dla systemów Windows posiada wbudowaną obsługę dla tego rozszerzenia. Nie trzeba ładować żadnych dodatkowych rozszerzeń aby korzystać z tych funkcji.
Konfiguracja uruchomieniowa
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
xml
The xml resource as returned by xml_parser_create() and xml_parser_create_ns() references an xml parser instance to be used with the functions provided by this extension.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane do PHP, lub załadowane dynamicznie przy starcie.
- XML_ERROR_NONE (integer)
- XML_ERROR_NO_MEMORY (integer)
- XML_ERROR_SYNTAX (integer)
- XML_ERROR_NO_ELEMENTS (integer)
- XML_ERROR_INVALID_TOKEN (integer)
- XML_ERROR_UNCLOSED_TOKEN (integer)
- XML_ERROR_PARTIAL_CHAR (integer)
- XML_ERROR_TAG_MISMATCH (integer)
- XML_ERROR_DUPLICATE_ATTRIBUTE (integer)
- XML_ERROR_JUNK_AFTER_DOC_ELEMENT (integer)
- XML_ERROR_PARAM_ENTITY_REF (integer)
- XML_ERROR_UNDEFINED_ENTITY (integer)
- XML_ERROR_RECURSIVE_ENTITY_REF (integer)
- XML_ERROR_ASYNC_ENTITY (integer)
- XML_ERROR_BAD_CHAR_REF (integer)
- XML_ERROR_BINARY_ENTITY_REF (integer)
- XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF (integer)
- XML_ERROR_MISPLACED_XML_PI (integer)
- XML_ERROR_UNKNOWN_ENCODING (integer)
- XML_ERROR_INCORRECT_ENCODING (integer)
- XML_ERROR_UNCLOSED_CDATA_SECTION (integer)
- XML_ERROR_EXTERNAL_ENTITY_HANDLING (integer)
- XML_OPTION_CASE_FOLDING (integer)
- XML_OPTION_TARGET_ENCODING (integer)
- XML_OPTION_SKIP_TAGSTART (integer)
- XML_OPTION_SKIP_WHITE (integer)
Event Handlers
The XML event handlers defined are:
Tabela 1. Supported XML handlers
PHP function to set handler | Event description |
---|---|
xml_set_element_handler() | Element events are issued whenever the XML parser encounters start or end tags. There are separate handlers for start tags and end tags. |
xml_set_character_data_handler() | Character data is roughly all the non-markup contents of XML documents, including whitespace between tags. Note that the XML parser does not add or remove any whitespace, it is up to the application (you) to decide whether whitespace is significant. |
xml_set_processing_instruction_handler() | PHP programmers should be familiar with processing instructions (PIs) already. <?php ?> is a processing instruction, where php is called the "PI target". The handling of these are application-specific, except that all PI targets starting with "XML" are reserved. |
xml_set_default_handler() | What goes not to another handler goes to the default handler. You will get things like the XML and document type declarations in the default handler. |
xml_set_unparsed_entity_decl_handler() | This handler will be called for declaration of an unparsed (NDATA) entity. |
xml_set_notation_decl_handler() | This handler is called for declaration of a notation. |
xml_set_external_entity_ref_handler() | This handler is called when the XML parser finds a reference to an external parsed general entity. This can be a reference to a file or URL, for example. See the external entity example for a demonstration. |
Case Folding
The element handler functions may get their element names case-folded. Case-folding is defined by the XML standard as "a process applied to a sequence of characters, in which those identified as non-uppercase are replaced by their uppercase equivalents". In other words, when it comes to XML, case-folding simply means uppercasing.
By default, all the element names that are passed to the handler functions are case-folded. This behaviour can be queried and controlled per XML parser with the xml_parser_get_option() and xml_parser_set_option() functions, respectively.
Error Codes
The following constants are defined for XML error codes (as returned by xml_parse()):
XML_ERROR_NONE |
XML_ERROR_NO_MEMORY |
XML_ERROR_SYNTAX |
XML_ERROR_NO_ELEMENTS |
XML_ERROR_INVALID_TOKEN |
XML_ERROR_UNCLOSED_TOKEN |
XML_ERROR_PARTIAL_CHAR |
XML_ERROR_TAG_MISMATCH |
XML_ERROR_DUPLICATE_ATTRIBUTE |
XML_ERROR_JUNK_AFTER_DOC_ELEMENT |
XML_ERROR_PARAM_ENTITY_REF |
XML_ERROR_UNDEFINED_ENTITY |
XML_ERROR_RECURSIVE_ENTITY_REF |
XML_ERROR_ASYNC_ENTITY |
XML_ERROR_BAD_CHAR_REF |
XML_ERROR_BINARY_ENTITY_REF |
XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF |
XML_ERROR_MISPLACED_XML_PI |
XML_ERROR_UNKNOWN_ENCODING |
XML_ERROR_INCORRECT_ENCODING |
XML_ERROR_UNCLOSED_CDATA_SECTION |
XML_ERROR_EXTERNAL_ENTITY_HANDLING |
Character Encoding
PHP's XML extension supports the Unicode character set through different character encodings. There are two types of character encodings, source encoding and target encoding. PHP's internal representation of the document is always encoded with UTF-8.
Source encoding is done when an XML document is parsed. Upon creating an XML parser, a source encoding can be specified (this encoding can not be changed later in the XML parser's lifetime). The supported source encodings are ISO-8859-1, US-ASCII and UTF-8. The former two are single-byte encodings, which means that each character is represented by a single byte. UTF-8 can encode characters composed by a variable number of bits (up to 21) in one to four bytes. The default source encoding used by PHP is ISO-8859-1.
Target encoding is done when PHP passes data to XML handler functions. When an XML parser is created, the target encoding is set to the same as the source encoding, but this may be changed at any point. The target encoding will affect character data as well as tag names and processing instruction targets.
If the XML parser encounters characters outside the range that its source encoding is capable of representing, it will return an error.
If PHP encounters characters in the parsed XML document that can not be represented in the chosen target encoding, the problem characters will be "demoted". Currently, this means that such characters are replaced by a question mark.
Przykłady
Here are some example PHP scripts parsing XML documents.
XML Element Structure Example
This first example displays the structure of the start elements in a document with indentation.
XML Tag Mapping Example
Przykład 2. Map XML to HTML This example maps tags in an XML document directly to HTML tags. Elements not found in the "map array" are ignored. Of course, this example will only work with a specific XML document type.
|
XML External Entity Example
This example highlights XML code. It illustrates how to use an external entity reference handler to include and parse other documents, as well as how PIs can be processed, and a way of determining "trust" for PIs containing code.
XML documents that can be used for this example are found below the example (xmltest.xml and xmltest2.xml.)
Przykład 3. External Entity Example
|
Przykład 4. xmltest.xml
|
This file is included from xmltest.xml:
- Spis treści
- utf8_decode -- Konwertuje ciąg znaków w ISO-8859-1 zakodowany w UTF-8 do jednobajtowego ISO-8859-1
- utf8_encode -- Koduje ciąg znaków w ISO-8859-1 do UTF-8
- xml_error_string -- Pobiera łańcuch znaków zawierający błąd parsera XML
- xml_get_current_byte_index -- Pobiera aktualny indeks bajtu parsera XML
- xml_get_current_column_number -- Pobiera aktualny numer kolumny dla parsera XML
- xml_get_current_line_number -- Pobiera aktualny numer linii dla parsera XML
- xml_get_error_code -- Pobiera kod błędu parsera XML
- xml_parse_into_struct -- Parse XML data into an array structure
- xml_parse -- rozpoczyna parsowanie dokumentu XML
- xml_parser_create_ns -- Create an XML parser with namespace support
- xml_parser_create -- tworzy parser XML
- xml_parser_free -- Zwalnia parser XML
- xml_parser_get_option -- Get options from an XML parser
- xml_parser_set_option -- Set options in an XML parser
- xml_set_character_data_handler -- Set up character data handler
- xml_set_default_handler -- Set up default handler
- xml_set_element_handler -- Ustawia początkową i końcową procedurę obsługi elementu
- xml_set_end_namespace_decl_handler -- Set up end namespace declaration handler
- xml_set_external_entity_ref_handler -- Set up external entity reference handler
- xml_set_notation_decl_handler -- Set up notation declaration handler
- xml_set_object -- Use XML Parser within an object
- xml_set_processing_instruction_handler -- Set up processing instruction (PI) handler
- xml_set_start_namespace_decl_handler -- Set up start namespace declaration handler
- xml_set_unparsed_entity_decl_handler -- Set up unparsed entity declaration handler
Poprzedni | Spis treści | Następny |
xdiff_string_patch | Początek rozdziału |