<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.xml-parser-set-option" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>xml_parser_set_option</refname>

<refpurpose>在 XML 解析器中设置选项</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>bool</type><methodname>xml_parser_set_option</methodname>

<methodparam><type>XMLParser</type><parameter>parser</parameter></methodparam>

<methodparam><type>int</type><parameter>option</parameter></methodparam>

<methodparam><type class="union"><type>string</type><type>int</type><type>bool</type></type><parameter>value</parameter></methodparam>

</methodsynopsis>

<para>

在 XML 解析器中设置选项。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>parser</parameter></term>

<listitem>

<para>

指向要设置选项的 XML 解析器。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>option</parameter></term>

<listitem>

<para>

要设置的选项。见下文。

</para>

<para>

以下选项可用：

<table>

<title>XML 解析器选项</title>

<tgroup cols="3">

<thead>

<row>

<entry>选项常量</entry>

<entry>数据类型</entry>

<entry>说明</entry>

</row>

</thead>

<tbody>

<row>

<entry><constant>XML_OPTION_CASE_FOLDING</constant></entry>

<entry>bool</entry>

<entry>

控制是否为此 XML 解析器启用<link linkend="xml.case-folding">大写转换</link>。默认启用。

</entry>

</row>

<row>

<entry><constant>XML_OPTION_PARSE_HUGE</constant></entry>

<entry>bool</entry>

<entry>

允许解析大于 10 MB 的文档。

仅当文档大小有限时才应启用此选项，否则可能导致 DoS。

仅在使用 libxml2 时才可用。

</entry>

</row>

<row>

<entry><constant>XML_OPTION_SKIP_TAGSTART</constant></entry>

<entry>integer</entry>

<entry>

指定在标记名称的开头应略过多少个字符。

</entry>

</row>

<row>

<entry><constant>XML_OPTION_SKIP_WHITE</constant></entry>

<entry>bool</entry>

<entry>

是否略过由空白字符组成的值。

</entry>

</row>

<row>

<entry><constant>XML_OPTION_TARGET_ENCODING</constant></entry>

<entry>string</entry>

<entry>

设置要在此 XML 解析器中使用的<link linkend="xml.encoding">目标编码</link>。默认情况下，设置的编码与 <function>xml_parser_create</function>

使用的源编码相同。支持的目标编码有 <literal>ISO-8859-1</literal>、<literal>US-ASCII</literal> 和 <literal>UTF-8</literal>。

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>value</parameter></term>

<listitem>

<para>

选项的新值。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

成功时返回 &true;，失败时返回 &false;。

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

当传递到 <parameter>option</parameter> 的值无效时抛出 <classname>ValueError</classname>。

</para>

<para>

在 PHP 8.0.0 之前，向 <parameter>option</parameter> 传递的值无效时会生成

<constant>E_WARNING</constant> 并使函数返回 &false;。

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

添加了选项 <constant>XML_OPTION_PARSE_HUGE</constant>。

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

<parameter>value</parameter> 参数现在也接受 bool。选项 <constant>XML_OPTION_CASE_FOLDING</constant> 和

<constant>XML_OPTION_SKIP_WHITE</constant> 现在是 bool 选项。

</entry>

</row>

&xml.changelog.parser-param;

<row>

<entry>8.0.0</entry>

<entry>

如果 <parameter>option</parameter> 无效，现在抛出 <classname>ValueError</classname>。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

</refentry>