-
Notifications
You must be signed in to change notification settings - Fork 105
/
Copy pathmb-detect-encoding.xml
235 lines (222 loc) · 7.4 KB
/
mb-detect-encoding.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 2c17cef6e71c3d85011319cde128cc4edf89a053 Maintainer: daijie Status: ready -->
<!-- CREDITS: mowangjuanzi -->
<refentry xml:id="function.mb-detect-encoding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mb_detect_encoding</refname>
<refpurpose>检测字符的编码</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>string</type><type>false</type></type><methodname>mb_detect_encoding</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>array</type><type>string</type><type>null</type></type><parameter>encodings</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>strict</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
<para>
从有序的候选列表中检测 <type>string</type> <parameter>string</parameter> 最可能的字符编码。
</para>
<para>
对预期（intended）字符编码的自动检测不可能永远完全可靠；没有额外的信息，就类似于在没有密钥的情况下解码已编码的字符串。最好使用与数据一起存储或传输的字符编码表示，例如“Content-Type” HTTP 头。
</para>
<para>
此函数适用于多字节编码，但并非所有字节顺序都构成有效字符串。如果输入字符串包含这样的顺序，则将会拒绝该编码，并检查下一个编码。
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
<para>
要检测的 <type>string</type>。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>encodings</parameter></term>
<listitem>
<para>
按顺序尝试的字符编码列表。该列表可以指定为字符串数组，或以逗号分隔的单个字符串。
</para>
<para>
如果省略 <parameter>encodings</parameter> 被或为 &null;，则将使用当前的 detect_order（使用
<link linkend="ini.mbstring.detect-order">mbstring.detect_order</link> 配置选项或
<function>mb_detect_order</function> 函数设置）。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>strict</parameter></term>
<listitem>
<para>
控制 <parameter>string</parameter> 在列出的所有 <parameter>encodings</parameter> 中无效时的行为。如果
<parameter>strict</parameter> 设置为 &false;，将返回最接近的匹配编码；如果 <parameter>strict</parameter>
设置为 &true;，将返回 &false;。
</para>
<para>
可以使用 <link linkend="ini.mbstring.strict-detection">mbstring.strict_detection</link> 配置选项设置 <parameter>strict</parameter> 的默认值。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
检测到的字符编码，如果字符串在任何列出的编码中均无效，则返回 &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.2.0</entry>
<entry>
<function>mb_detect_encoding</function>
将不再返回以下非文本编码：<literal>"Base64"</literal>、<literal>"QPrint"</literal>、<literal>"UUencode"</literal>、<literal>"HTML entities"</literal>、<literal>"7 bit"</literal> 和 <literal>"8 bit"</literal>。
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mb_detect_encoding</function> 示例</title>
<programlisting role="php">
<![CDATA[
<?php
// 使用当前的 detect_order 来检测字符编码
echo mb_detect_encoding($str);
// "auto" 将根据 mbstring.language 来扩展
echo mb_detect_encoding($str, "auto");
// 通过以逗号分隔的列表指定“encodings”参数
echo mb_detect_encoding($str, "JIS, eucjp-win, sjis-win");
// 使用数组指定“encodings”参数
$encodings = [
"ASCII",
"JIS",
"EUC-JP"
];
echo mb_detect_encoding($str, $encodings);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title><parameter>strict</parameter> 参数的影响</title>
<programlisting role="php">
<![CDATA[
<?php
// 'áéóú' 在 ISO-8859-1 中的编码
$str = "\xE1\xE9\xF3\xFA";
// 该字符串不是有效的 ASCII 或 UTF-8，但 UTF-8 被认为是更接近的匹配
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));
// 如果找到有效编码，则严格参数不会更改结果
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(5) "UTF-8"
bool(false)
string(10) "ISO-8859-1"
string(10) "ISO-8859-1"
]]>
</screen>
</example>
</para>
<para>
在某些情况下，相同的字节顺序可能会在多种字符编码中形成有效的字符串，并且无法知道其意图是哪种解释。例如，在众多字符编码中，字节序列“\xC4\xA2”可能是：
</para>
<para>
<simplelist>
<member>
"Ä¢" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS followed by U+00A2 CENT SIGN)
encoded in any of ISO-8859-1, ISO-8859-15, or Windows-1252
</member>
<member>
"ФЂ" (U+0424 CYRILLIC CAPITAL LETTER EF followed by U+0402 CYRILLIC CAPITAL LETTER
DJE) encoded in ISO-8859-5
</member>
<member>
"Ģ" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) encoded in UTF-8
</member>
</simplelist>
</para>
<para>
<example>
<title>匹配多个编码时顺序的影响</title>
<programlisting role="php">
<![CDATA[
<?php
$str = "\xC4\xA2";
// 该字符串在所有三种编码中均有效，因此将返回列出的第一个
var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5']));
var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(5) "UTF-8"
string(10) "ISO-8859-1"
string(10) "ISO-8859-5"
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>mb_detect_order</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->