README

Safe PHP

📌 弃用通知

此仓库已弃用，The Coding Machine将不再进行任何工作。您可以使用safe v2进行相同的操作。

工作进度

重写了核心PHP函数，当遇到错误时抛出异常而不是返回false。

问题

大多数PHP核心函数都是在添加异常处理之前编写的。因此，大多数PHP函数不会抛出异常。相反，它们在出错时返回false。

但我们大多数人太懒了，懒得为每个核心PHP函数的每个返回值都进行显式检查。

// This code is incorrect. Twice.
// "file_get_contents" can return false if the file does not exists
// "json_decode" can return false if the file content is not valid JSON
$content = file_get_contents('foobar.json');
$foobar = json_decode($content);

此代码的正确版本应该是

$content = file_get_contents('foobar.json');
if ($content === false) {
    throw new FileLoadingException('Could not load file foobar.json');
}
$foobar = json_decode($content);
if (json_last_error() !== JSON_ERROR_NONE) {
    throw new FileLoadingException('foobar.json does not contain valid JSON: '.json_last_error_msg());
}

显然，虽然这个片段是正确的，但它更难阅读。

解决方案

欢迎使用thecodingmachine/safe，也称为Safe-PHP。

Safe-PHP重新声明了所有核心PHP函数。新的PHP函数的行为与旧函数完全相同，只是在遇到错误时正确地抛出异常。安全的函数与核心PHP函数具有相同的名称，但它们位于Safe命名空间中。

use function Safe\file_get_contents;
use function Safe\json_decode;

// This code is both safe and simple!
$content = file_get_contents('foobar.json');
$foobar = json_decode($content);

所有可能返回false的错误PHP函数都是Safe的一部分。此外，Safe还提供了2个'Safe'类：Safe\DateTime和Safe\DateTimeImmutable，其方法将抛出异常而不是返回false。

PHPStan集成

是的...但我必须明确为每个应用文件的函数导入“安全”版本。我肯定我会忘记一些“use function”语句！

不用担心！thecodingmachine/safe附带了一个PHPStan规则。

以前没听说过PHPStan？去看看吧，它是一个出色的PHP代码分析器。

只需在PHPStan设置中安装Safe规则（在“安装”部分中解释），PHPStan就会在每次使用“不安全”函数时通知您。

以下代码将触发此警告

$content = file_get_contents('foobar.json');

函数file_get_contents不安全使用。它可能返回FALSE而不是抛出异常。请在此文件的开始处添加 'use function Safe\file_get_contents;' 以使用 'thecodingmachine/safe' 库提供的版本。

安装

使用composer安装Safe-PHP

$ composer require thecodingmachine/safe

强烈推荐：安装PHPStan和PHPStan扩展

$ composer require --dev thecodingmachine/phpstan-safe-rule

现在，编辑您的phpstan.neon文件并添加以下规则

includes:
    - vendor/thecodingmachine/phpstan-safe-rule/phpstan-safe-rule.neon

自动重构

您有一个庞大的遗留代码库，并希望在整个项目中使用“Safe-PHP”函数？PHPStan可以帮助您找到这些函数，但逐个更改函数的命名空间可能是一项繁琐的任务。

幸运的是，Safe附带了一个“Rector”配置文件。Rector是一个命令行工具，可以对您的应用程序进行即时重构。

运行

$ composer require --dev rector/rector:^0.7

rector/rector进行安装。

运行

vendor/bin/rector process src/ --config vendor/thecodingmachine/safe/rector-migrate-0.7.php

运行rector/rector。

注意：不要忘记将“src/”替换为您源目录的路径。

重要：重构只会执行函数的“愚蠢”替换。它不会修改处理“false”返回值的方式。因此，如果您的代码已经执行了错误处理，您将需要手动处理它。

特别是，您应该寻找已经执行的错误处理，例如

if (!mkdir($dirPath)) {
    // Do something on error
}

此代码将由Rector重构为

if (!\Safe\mkdir($dirPath)) {
    // Do something on error
}

然后您应该（手动）重构它为

try {
    \Safe\mkdir($dirPath));
} catch (\Safe\FilesystemException $e) {
    // Do something on error
}

性能影响

Safe在每次请求中从约85个文件加载1000+个函数。然而，这种加载的性能影响相当低。

如果您担心，使用Safe会在每次请求上“花费”约700µs。性能部分包含有关我们测试Safe性能影响方式的信息。

了解更多信息

如果您想了解更多关于Safe-PHP开发触发因素的信息，请阅读TheCodingMachine博客上的发布文章。

贡献

包含所有函数的文件是从PHP文档自动生成的。阅读CONTRIBUTING.md文件，了解如何重新生成这些文件以及如何为此库做出贡献。