README

提供PHP（临时）迁移所需的兼容性函数。

警告

此扩展仅限临时使用。换句话说，生产环境中的代码应尽可能不依赖此实现，并且应在安全的情况下逐步淘汰。

支持的版本

• 扩展：PHP >= 8.0, 8.3 >= PHP
• 库：PHP >= 7.4, 8.3 >= PHP

库是为了使用相同代码库迁移到PHP 8.x而引入的。如果您不需要使用相同的代码库，则可以仅使用扩展。

使用方法

安装

此存储库包含一个提供主要兼容性的扩展和一个辅助库，每个都必须单独安装。

扩展可以按照以下步骤安装。请注意，需要PHP公共构建工具链。

$ cd "ext"
$ phpize
$ ./configure
$ make -j$(nproc)
$ make test
$ sudo make install

不要忘记启用扩展。（可能需要创建*.ini文件或使用docker-php-ext-enable）

$ echo "extension=colopl_bc" | sudo tee "$(php-config --ini-dir)/10-colopl_bc.ini"
$ php -m | grep "colopl_bc"
colopl_bc

库的安装步骤如下。

$ composer require "colopl/colopl_bc"

确保扩展和库版本相同。

使用Rector进行代码转换

colopl/colopl_bc包包含Rector规则，用于将您的代码转换为现有ext-colopl_bc提供的函数。这可以用于处理大型代码库时节省时间。

对于每个规则，检查规则定义文件src/Rector。从PHP 7.x迁移到8.x的最常见配置如下

<?php
/* ~~~ */
    $rectorConfig->rules([
        SwitchCaseToEqualRector::class,
        ArrayFuncToBCMigrateRector::class,
        SortToBCMigrateRector::class,
        EqualToBCMigrateRector::class,
        GreaterToBCMigrateRector::class,
        GreaterOrEqualToBCMigrateRector::class,
        NotEqualToBCMigrateRector::class,
        SmallerToBCMigrateRector::class,
        SmallerOrEqualToBCMigrateRector::class,
        SpaceshipToBCMigrateRector::class
    ]);
/* ~~~ */

API参考

INI指令

colopl_bc.php74.compare_mode（默认：0）

设置各种比较运算符的兼容性检查模式（例如==）。

• 0（COLOPL_BC_PHP74_COMPARE_MODE_SILENT）

不执行兼容性检查，始终使用旧行为的结果。适用于生产环境。

• 1（COLOPL_BC_PHP74_COMPARE_MODE_DEPRECATED）

将结果与原生PHP运算符的结果进行比较，如果结果不同，则引发相当于E_DEPRECATED的错误。

• 2（COLOPL_BC_PHP74_COMPARE_MODE_LOG）

将原生PHP运算符的结果进行比较，如果结果不同，则将日志发送到正在运行的SAPI。

colopl_bc.php74.sort_mode（默认：0）

设置各种不稳定排序算法的兼容性检查模式。

• 0（COLOPL_BC_PHP74_COMPARE_MODE_SILENT）

不执行兼容性检查，始终使用旧行为的结果。适用于生产环境。

• 1（COLOPL_BC_PHP74_COMPARE_MODE_DEPRECATED）

将结果与原生PHP函数的结果进行比较，如果结果不同，则引发相当于E_DEPRECATED的错误。

• 2（COLOPL_BC_PHP74_COMPARE_MODE_LOG）

将原生PHP函数的结果进行比较，如果结果不同，则将日志发送到正在运行的SAPI。

常量

请检查相应的ini指令的设置。

• COLOPL_BC_PHP74_COMPARE_MODE_SILENT = 0
• COLOPL_BC_PHP74_COMPARE_MODE_DEPRECATED = 1
• COLOPL_BC_PHP75_COMPARE_MODE_LOG = 2
• COLOPL_BC_PHP74_SORT_MODE_SILENT = 0
• COLOPL_BC_PHP74_SORT_MODE_DEPRECATED = 1
• COLOPL_BC_PHP75_SORT_MODE_LOG = 2

函数

• Colopl\ColoplBc\Php74\ksort()
• Colopl\ColoplBc\Php74\krsort()
• Colopl\ColoplBc\Php74\asort()
• Colopl\ColoplBc\Php74\arsort()
• Colopl\ColoplBc\Php74\sort()
• Colopl\ColoplBc\Php74\rsort()
• Colopl\ColoplBc\Php74\usort()
• Colopl\ColoplBc\Php74\uasort()
• Colopl\ColoplBc\Php74\uksort()
• Colopl\ColoplBc\Php74\array_multisort()

使用先前的不稳定排序算法进行排序。

这些兼容性也可以在运行时进行检查。有关详细信息，请参阅colopl_bc.php74.sort_mode INI指令。

• Colopl\ColoplBc\Php74\in_array()
• Colopl\ColoplBc\Php74\array_search()
• Colopl\ColoplBc\Php74\array_keys()

这些函数使用比PHP 8.0更旧的比较算法进行内部使用。

这些兼容性也可以在运行时进行检查。有关详细信息，请参阅colopl_bc.php74.compare_mode INI指令。

• Colopl\ColoplBc\Php74\eq() (==)
• Colopl\ColoplBc\Php74\neq() (!=)
• Colopl\ColoplBc\Php74\lt() (<)
• Colopl\ColoplBc\Php74\lte() (<=)
• Colopl\ColoplBc\Php74\gt() (>)
• Colopl\ColoplBc\Php74\gte() (>=)
• Colopl\ColoplBc\Php74\spaceship() (<=>)

对于相应的比较运算符，返回的结果将重现旧的行为。

这些兼容性也可以在运行时进行检查。有关详细信息，请参阅colopl_bc.php74.compare_mode INI指令。

• Colopl\ColoplBc\Php70\srand()

播种随机数。

警告

colopl_bc提供的srand()基于glibc的srand() / rand()算法。结果可能与非glibc环境的那些不同，例如Alpine Linux。

• Colopl\ColoplBc\Php70\rand()

生成随机数。

警告

colopl_bc提供的rand()基于glibc的srand() / rand()算法。结果可能与非glibc环境的那些不同，例如Alpine Linux。

• Colopl\ColoplBc\Php70\getrandmax()

返回调用Colopl\ColoplBc\Php70\rand()时可以返回的最大值。

警告

colopl_bc提供的rand()基于glibc的srand() / rand()算法。结果可能与非glibc环境的那些不同，例如Alpine Linux。

• Colopl\ColoplBc\Php70\shuffle()

此函数将数组中的元素顺序随机化。

警告

shuffle()内部使用Colopl\ColoplBc\Php70\rand()算法，由colopl_bc基于glibc的srand() / rand()算法。结果可能与非glibc环境的那些不同，例如Alpine Linux。

• Colopl\ColoplBc\Php70\str_shuffle()

str_shuffle()随机化字符串。创建所有可能的排列之一。

警告

str_shuffle()内部使用Colopl\ColoplBc\Php70\rand()算法，由colopl_bc基于glibc的srand() / rand()算法。结果可能与非glibc环境的那些不同，例如Alpine Linux。

• Colopl\ColoplBc\Php70\array_rand()

从数组中随机选择一个或多个条目，并返回随机条目的键（或键）。

警告

array_rand()内部使用Colopl\ColoplBc\Php70\rand()算法，由colopl_bc基于glibc的srand() / rand()算法。结果可能与非glibc环境的那些不同，例如Alpine Linux。

• Colopl\ColoplBc\Php70\mt_srand()

始终使用一个损坏的梅森旋转器初始化状态。

• Colopl\ColoplBc\Php70\mt_rand()

生成随机数。

警告

此函数以前导致未定义的行为，并返回取决于CPU架构的不同结果。当前行为被强制模仿gcc + amd64的结果，并且对于其他环境中的PHP可能返回不同的结果。

• Colopl\ColoplBc\Php70\date_create()
• Colopl\ColoplBc\Php70\date_create_immutable()

始终实例化DateTime而不包含毫秒。