README

Patchwork UTF-8 为 PHP 开发者提供了广泛、便携和高效的 UTF-8 和 grapheme clusters 处理。

它提供以下两种功能

• 为 mbstring、iconv 和 intl 的 Normalizer 和 grapheme_* 函数提供可移植层，
• 一个 UTF-8 grapheme clusters 感知的本地字符串函数的副本。

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

版本 1.2 增加了 UTF-8 到 Code Page 近似的最适合映射。它还增加了 Windows 下的 Unicode 文件系统访问，首选使用 wfio 或其他基于 COM 的备用方案。

可移植性

最好使用 mbstring、iconv、intl 和 pcre 与启用 u 标志的组合来执行 PHP 中的 Unicode 处理。但当应用程序预期在许多服务器上运行时，应知道这 4 个扩展并不总是启用。

Patchwork UTF-8 为其中 3 个扩展提供了纯 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

Grapheme clusters 应始终在处理通用 Unicode 字符串时考虑。Patchwork\Utf8 类实现了需要 UTF-8 grapheme clusters 感知的本地字符串函数的近完整集合。函数名称、参数和行为仔细地复制了本地 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的所有功能，但了解土耳其的特定情况。

用法

安装Patchwork UTF-8的推荐方法是通过composer。只需创建一个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以查看代码的实际效果。

请确保您了解UTF-8的使用，通过阅读字符集/字符编码问题和用PHP处理UTF-8，或者PHP et 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问题。