XML 해석기 함수

소개

XML(eXtensible Markup Language)은 웹에서 구조화된 문서 교환을 위한 데이터 형식입니다. The World Wide Web consortium(W3C)에서 정의한 표준입니다. XML과 관련 기술에 대한 정보는 » https://www.w3.org/XML/에서 볼 수 있습니다.

PHP 확장은 James Clark의 expat를 사용합니다. 이 툴킷은 XML 문서를 처리할 수 있게 하지만, 유효성을 검증하지는 않습니다. PHP에서도 지원하는 세가지 문자 인코딩을 지원합니다: US_ASCII, ISO-8859-1, UTF-8. UTF-16은 지원하지 않습니다.

이 확장은 XML 파서를 작성하고 여러가지 XML 이벤트에 대한 핸들러를 정의할 수 있게 합니다. 각각의 XML 파서는 조절할 수 있는 약간의 인자를 가집니다.

요구 조건

이 확장은 » https://www.jclark.com/xml/expat.html에서 찾을 수 있는 expat를 사용합니다. expat에 들어있는 Makefile은 기본값으로 라이브러리를 생성하지 않기 때문에, 다음의 make 규칙을 사용할 수 있습니다:

libexpat.a: $(OBJS)
    ar -rc $@ $(OBJS)
    ranlib $@

expat의 소스 RPM 패키지는 » https://sourceforge.net/projects/expat/에서 찾을 수 있습니다.

설치

이 함수들은 번들된 expat 라이브러리를 이용하여 기본값으로 활성화되어 있습니다. XML 지원을 비활성화 하려면 --disable-xml을 사용하십시오. PHP를 아파치 1.3.9 이상의 모듈로 컴파일한다면, PHP는 자동적으로 아파치에 번들된 expat를 사용합니다. 번들된 expat 라이브러리를 사용하지 않으려면, PHP 설정에 --with-expat-dir=DIR을 지정하십시오. DIR은 expat를 설치한 베이스 디렉토리를 지정해야 합니다.

PHP 윈도우 버전에서는 이 확장에 대한 지원이 포함되어 있습니다. 이 함수들을 이용하기 위해서 추가로 확장을 읽어들일 필요가 없습니다.

실행시 설정

이 확장은 php.ini 설정이 존재하지 않습니다.

자원형

xml

xml_parser_create()와 xml_parser_create_ns()가 반환하는 xml 자원은 xml 파서 인스탠스를 참조하고, 이 확장이 제공하는 함수들이 사용합니다.

예약 상수

이 확장은 다음의 상수들을 정의합니다. 이 확장을 PHP에 내장했거나, 실행시에 동적으로 읽어들일 경우에만 사용할 수 있습니다.

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)

이벤트 핸들러

정의된 XML 이벤트 핸들러는:

**지원하는 XML 핸들러**
핸들러를 설정하는 PHP 함수	이벤트 설명
xml_set_element_handler()	엘레멘트 이벤트는 XML 파서가 시작과 끝 태그에 도달했을 때 발생합니다. 시작 태그와 끝 태그에 별도의 핸들러가 존재합니다.
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 프로그래머는 이미 프로세싱 인스트럭션(PIs)에 익숙할 것입니다. <?php ?>는 프로세싱 인스트럭션이고, php은 "PI 타겟"이라 불립니다. 예약된 "XML"로 시작하는 PI 타겟들을 제외하면, 이들에 대한 핸들링은 어플리케이션 특화입니다.
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()	이 핸들러는 unparsed (NDATA) 엔트리의 정의를 호출합니다.
xml_set_notation_decl_handler()	이 핸들러는 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.

케이스 폴딩

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.

오류 코드

다음 상수들이 XML 오류 코드로 정의되어 있습니다 (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

문자 인코딩

PHP의 XML 확장은 » 유니코드 문자셋을 통해 서로 다른 문자 인코딩을 지원합니다. 문자 인코딩에는 소스 인코딩과 타겟 인코딩의 두 종류가 존재합니다. PHP 내부에서 문서 표현은 항상 UTF-8로 인코드되어 있습니다.

소스 인코딩은 XML 문서가 parse되었을 때 이루어집니다. XML 파서를 작성할 때, 소스 인코딩을 지정할 수 있습니다. (이 인코딩은 XML 파서가 종료될때까지 변경할 수 없습니다) 지원하는 소스 인코딩은 ISO-8859-1, US-ASCII, UTF-8입니다. 앞쪽의 두개는 싱글-바이트 인코딩이기에, 각각의 문자는 하나의 바이트로 표현됩니다. UTF-8은 1에서 4바이트 사이에서 다양한 수의 비트(21까지)를 조합하여 인코드할 수 있습니다. PHP에서 사용하는 기본 소스 인코딩은 ISO-8859-1입니다.

타겟 인코딩은 PHP가 XML 핸들러 함수에 데이터를 넘길 때 이루어집니다. XML 파서를 작성하면, 타겟 인코딩을 소스 인코딩과 동일하게 설정하지만, 이는 언제라도 변경할 수 있습니다. 타켓 인코딩은 문자 데이터뿐만 아니라 태그 이름과 프로세싱 인스트럭션 타겟에도 영향을 미칩니다.

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.

예제

XML 문서를 파싱하는 몇몇 예제 PHP 스크립트입니다.

XML 엘레멘트 구조 예제

This first example displays the structure of the start elements in a document with indentation.

Example#1 XML 엘레멘트 구조 보기


<?php
$file = "data.xml";
$depth = array();

function startElement($parser, $name, $attrs)
{
    global $depth;
    for ($i = 0; $i < $depth[$parser]; $i++) {
        echo "  ";
    }
    echo "$name\n";
    $depth[$parser]++;
}

function endElement($parser, $name)
{
    global $depth;
    $depth[$parser]--;
}

$xml_parser = xml_parser_create();
xml_set_element_handler($xml_parser, "startElement", "endElement");
if (!($fp = fopen($file, "r"))) {
    die("XML 입력을 열 수 없습니다.");
}

while ($data = fread($fp, 4096)) {
    if (!xml_parse($xml_parser, $data, feof($fp))) {
        die(sprintf("XML 에러: %s at line %d",
                    xml_error_string(xml_get_error_code($xml_parser)),
                    xml_get_current_line_number($xml_parser)));
    }
}
xml_parser_free($xml_parser);
?>

XML 태그 매핑 예제

Example#2 XML을 HTML로 맵

이 예제는 XML 문서의 태그를 직접 HTML 태그로 매핑합니다. "맵 배열"에 존재하지 않는 요소는 무시합니다. 물론, 이 예제는 특정한 XML 문서형에만 작동합니다.


<?php
$file = "data.xml";
$map_array = array(
    "BOLD"     => "B",
    "EMPHASIS" => "I",
    "LITERAL"  => "TT"
);

function startElement($parser, $name, $attrs)
{
    global $map_array;
    if (isset($map_array[$name])) {
        echo "<$map_array[$name]>";
    }
}

function endElement($parser, $name)
{
    global $map_array;
    if (isset($map_array[$name])) {
        echo "</$map_array[$name]>";
    }
}

function characterData($parser, $data)
{
    echo $data;
}

$xml_parser = xml_parser_create();
// use case-folding so we are sure to find the tag in $map_array
xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true);
xml_set_element_handler($xml_parser, "startElement", "endElement");
xml_set_character_data_handler($xml_parser, "characterData");
if (!($fp = fopen($file, "r"))) {
    die("XML 입력을 열 수 없습니다.");
}

while ($data = fread($fp, 4096)) {
    if (!xml_parse($xml_parser, $data, feof($fp))) {
        die(sprintf("XML 에러: %s at line %d",
                    xml_error_string(xml_get_error_code($xml_parser)),
                    xml_get_current_line_number($xml_parser)));
    }
}
xml_parser_free($xml_parser);
?>

XML 외부 엔티티 예제

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.)

Example#3 External Entity Example


<?php
$file = "xmltest.xml";

function trustedFile($file)
{
    // only trust local files owned by ourselves
    if (!eregi("^([a-z]+)://", $file) 
        && fileowner($file) == getmyuid()) {
            return true;
    }
    return false;
}

function startElement($parser, $name, $attribs)
{
    echo "&lt;<font color=\"#0000cc\">$name</font>";
    if (sizeof($attribs)) {
        while (list($k, $v) = each($attribs)) {
            echo " <font color=\"#009900\">$k</font>=\"<font 
                   color=\"#990000\">$v</font>\"";
        }
    }
    echo "&gt;";
}

function endElement($parser, $name)
{
    echo "&lt;/<font color=\"#0000cc\">$name</font>&gt;";
}

function characterData($parser, $data)
{
    echo "<b>$data</b>";
}

function PIHandler($parser, $target, $data)
{
    switch (strtolower($target)) {
        case "php":
            global $parser_file;
            // If the parsed document is "trusted", we say it is safe
            // to execute PHP code inside it.  If not, display the code
            // instead.
            if (trustedFile($parser_file[$parser])) {
                eval($data);
            } else {
                printf("Untrusted PHP code: <i>%s</i>", 
                        htmlspecialchars($data));
            }
            break;
    }
}

function defaultHandler($parser, $data)
{
    if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") {
        printf('<font color="#aa00aa">%s</font>', 
                htmlspecialchars($data));
    } else {
        printf('<font size="-1">%s</font>', 
                htmlspecialchars($data));
    }
}

function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId,
                                  $publicId) {
    if ($systemId) {
        if (!list($parser, $fp) = new_xml_parser($systemId)) {
            printf("Could not open entity %s at %s\n", $openEntityNames,
                   $systemId);
            return false;
        }
        while ($data = fread($fp, 4096)) {
            if (!xml_parse($parser, $data, feof($fp))) {
                printf("XML error: %s at line %d while parsing entity %s\n",
                       xml_error_string(xml_get_error_code($parser)),
                       xml_get_current_line_number($parser), $openEntityNames);
                xml_parser_free($parser);
                return false;
            }
        }
        xml_parser_free($parser);
        return true;
    }
    return false;
}

function new_xml_parser($file)
{
    global $parser_file;

    $xml_parser = xml_parser_create();
    xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1);
    xml_set_element_handler($xml_parser, "startElement", "endElement");
    xml_set_character_data_handler($xml_parser, "characterData");
    xml_set_processing_instruction_handler($xml_parser, "PIHandler");
    xml_set_default_handler($xml_parser, "defaultHandler");
    xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler");
    
    if (!($fp = @fopen($file, "r"))) {
        return false;
    }
    if (!is_array($parser_file)) {
        settype($parser_file, "array");
    }
    $parser_file[$xml_parser] = $file;
    return array($xml_parser, $fp);
}

if (!(list($xml_parser, $fp) = new_xml_parser($file))) {
    die("could not open XML input");
}

echo "<pre>";
while ($data = fread($fp, 4096)) {
    if (!xml_parse($xml_parser, $data, feof($fp))) {
        die(sprintf("XML error: %s at line %d\n",
                    xml_error_string(xml_get_error_code($xml_parser)),
                    xml_get_current_line_number($xml_parser)));
    }
}
echo "</pre>";
echo "parse complete\n";
xml_parser_free($xml_parser);

?>

Example#4 xmltest.xml

<?xml version='1.0'?>
<!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [
<!ENTITY plainEntity "FOO entity">
<!ENTITY systemEntity SYSTEM "xmltest2.xml">
]>
<chapter>
 <TITLE>Title &plainEntity;</TITLE>
 <para>
  <informaltable>
   <tgroup cols="3">
    <tbody>
     <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row>
     <row><entry>a2</entry><entry>c2</entry></row>
     <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row>
    </tbody>
   </tgroup>
  </informaltable>
 </para>
 &systemEntity;
 <section xml:id="about">
  <title>About this Document</title>
  <para>
   <!-- this is a comment -->
   <?php echo 'Hi!  This is PHP version '.phpversion(); ?>
  </para>
 </section>
</chapter>

이 파일은 xmltest.xml에서 포함합니다:

Example#5 xmltest2.xml

<?xml version="1.0"?>
<!DOCTYPE foo [
<!ENTITY testEnt "test entity">
]>
<foo>
   <element attrib="value"/>
   &testEnt;
   <?php echo "This is some more PHP code being executed."; ?>
</foo>

utf8_decode — Converts a string with ISO-8859-1 characters encoded with UTF-8 to single-byte ISO-8859-1
utf8_encode — Encodes an ISO-8859-1 string to UTF-8
xml_error_string — Get XML parser error string
xml_get_current_byte_index — Get current byte index for an XML parser
xml_get_current_column_number — Get current column number for an XML parser
xml_get_current_line_number — Get current line number for an XML parser
xml_get_error_code — Get XML parser error code
xml_parse_into_struct — Parse XML data into an array structure
xml_parse — Start parsing an XML document
xml_parser_create_ns — Create an XML parser with namespace support
xml_parser_create — Create an XML parser
xml_parser_free — Free an XML parser
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 — Set up start and end element handlers
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