README

Patchwork UTF-8 为 PHP 开发者提供了广泛的、便携式且高效的 UTF-8 和 图形簇 处理。

它提供了以下功能：

• 为 mbstring、iconv 和 intl 的 Normalizer 以及 grapheme_* 函数提供了一个可移植层，
• 一个对原生字符串函数的 UTF-8 图形簇感知副本。

它还可以作为参考资料，用于解决在 PHP 中处理 UTF-8 时出现的实际问题：Unicode 概念、相关算法、PHP 核心的错误、解决方案等。

版本 1.2 添加了 UTF-8 到 代码页 近似的最优映射。它还添加了在 Windows 下的 Unicode 文件系统访问，优先使用 wfio 或基于 COM 的后备方案。

可移植性

在 PHP 中，最好使用 mbstring、iconv、intl 和 pcre（启用 u 标志）的组合来处理 Unicode。但是，当应用程序预期将在许多服务器上运行时，应意识到这四个扩展并不总是被启用。

Patchwork UTF-8 为这四个扩展中的三个提供了纯 PHP 实现。需要使用支持 Unicode 的 pcre，这是广泛可用的。以下一组可移植性后备方案允许应用程序在没有启用这些扩展之一的服务器上运行。

• utf8_encode, utf8_decode,
• mbstring: mb_check_encoding, mb_convert_case, mb_convert_encoding, mb_decode_mimeheader, mb_detect_encoding, mb_detect_order, mb_encode_mimeheader, mb_encoding_aliases, mb_get_info, mb_http_input, mb_http_output, mb_internal_encoding, mb_language, mb_list_encodings, mb_output_handler, mb_strlen, mb_strpos, mb_strrpos, mb_strtolower, mb_strtoupper, mb_stripos, mb_stristr, mb_strrchr, mb_strrichr, mb_strripos, mb_strstr, mb_strwidth, mb_substitute_character, mb_substr, mb_substr_count,
• iconv: iconv, iconv_mime_decode, iconv_mime_decode_headers, iconv_get_encoding, iconv_set_encoding, iconv_mime_encode, ob_iconv_handler, iconv_strlen, iconv_strpos, iconv_strrpos, iconv_substr,
• intl: Normalizer, grapheme_extract, grapheme_stripos, grapheme_stristr, grapheme_strlen, grapheme_strpos, grapheme_strripos, grapheme_strrpos, grapheme_strstr, grapheme_substr, normalizer_is_normalized, normalizer_normalize.

Patchwork\Utf8

在处理通用 Unicode 字符串时，应始终考虑 图形簇。Patchwork\Utf8 类实现了需要 UTF-8 图形簇感知的本地字符串函数的近似完整集合。函数名称、参数和行为仔细地复制了本地 PHP 字符串函数。

还提供了一些额外的函数来帮助处理 UTF-8 字符串

• filter(): 标准化为 UTF-8 NFC，当需要时从 CP-1252 转换，
• isUtf8(): 检查字符串是否包含良好形成的 UTF-8 数据，
• toAscii(): 通用 UTF-8 到 ASCII 转写，
• strtocasefold(): 用于无大小写匹配的 Unicode 转换，
• strtonatfold(): 用于校对匹配的通用大小写敏感转换，
• strwidth(): 计算字符串在终端上打印时的宽度，
• wrapPath(): Windows 和其他操作系统下的 Unicode 文件系统访问。

镜像字符串函数包括：strlen, substr, strpos, stripos, strrpos, strripos, strstr, stristr, strrchr, strrichr, strtolower, strtoupper, wordwrap, chr, count_chars, ltrim, ord, rtrim, trim, str_ireplace, str_pad, str_shuffle, str_split, str_word_count, strcmp, strnatcmp, strcasecmp, strnatcasecmp, strncasecmp, strncmp, strcspn, strpbrk, strrev, strspn, strtr, substr_compare, substr_count, substr_replace, ucfirst, lcfirst, ucwords, number_format, utf8_encode, utf8_decode, json_decode, filter_input, filter_input_array。

特别缺失的是（但难以复制的）printf家族函数。

实现优先考虑性能而非全面处理边缘情况。它通常适用于UTF-8规范化字符串，并提供过滤器来获取它们。

由于土耳其地区需要特别注意，因此提供了一个Patchwork\TurkishUtf8类来处理这个地区。它克隆了Patchwork\Utf8的所有功能，但了解土耳其的具体情况。

使用方法

推荐通过composer安装Patchwork UTF-8。只需创建一个composer.json文件，然后运行php composer.phar install命令即可安装。

{
    "require": {
        "patchwork/utf8": "~1.2"
    }
}

然后，在引导序列的早期，您必须配置您的环境

\Patchwork\Utf8\Bootup::initAll(); // Enables the portablity layer and configures PHP for UTF-8
\Patchwork\Utf8\Bootup::filterRequestUri(); // Redirects to an UTF-8 encoded URL if it's not already the case
\Patchwork\Utf8\Bootup::filterRequestInputs(); // Normalizes HTTP inputs to UTF-8 NFC

运行phpunit以查看代码的实际应用。

请通过阅读字符集/字符编码问题和使用PHP处理UTF-8（针对法语读者），或者PHP et UTF-8来确保您对使用UTF-8有信心。

您还应熟悉Unicode规范化和图形集群的概念。

不要盲目替换所有PHP字符串函数的使用。大多数时候您不需要这样做，并且您将给您的应用程序引入显著的性能开销。

在外围对输入进行筛选，以确保只有良好形成的UTF-8通过。当处理不良形成的UTF-8时，您不应尝试修复它（参见Unicode安全考虑）。相反，将其视为CP-1252，并使用Patchwork\Utf8::utf8_encode()获取UTF-8字符串。别忘了还要选择一个Unicode规范化形式并坚持使用。NFC现在是事实上的标准。Patchwork\Utf8::filter()实现了此行为：它从CP1252转换为NFC。

此库与mbstring.func_overload正交，如果php.ini设置启用，则不会工作。

许可

Patchwork\Utf8是免费软件；您可以在（根据您的选择）以下条款下重新分发和/或修改它

• Apache License v2.0，或
• GNU通用公共许可证v2.0.

Unicode处理需要在长期运行中实施和维护繁琐的工作。因此，欢迎像单元测试、错误报告、评论或许可证下都允许的补丁这样的贡献。

希望许多项目可以采用此代码，并共同帮助解决PHP的Unicode问题。