README

struggle-for-php/sfp-phpstan-psr-log 为PHPStan提供额外严格且具有观点的psr/log (psr-3) 规则。

• PHPStan
• PSR-3: 日志接口 - PHP-FIG
• PSR-3 元文档

重要

从 0.20.0 版本开始，改变了默认规则设置。

• 默认启用 MessageStaticStringRule。
• 默认禁用 ContextRequireExceptionKeyRule。
• [建议] 将以下参数写入项目的 phpstan.neon 文件。

parameters:
    sfpPsrLog:
        enableMessageStaticStringRule: true
        enableContextRequireExceptionKeyRule: true
        reportContextExceptionLogLevel: 'info'
        contextKeyOriginalPattern: '#\A[A-Za-z0-9-_]+\z#'

存根

此扩展依赖于我们提供的 psr/log 存根以提供严格性。

• 例如。
  • @param LogLevel::* $level 在 log() 方法中
  • @param array{exception?: \Throwable} $context

请参阅 psr/log 存根 仓库页面以获取更多详细信息。

规则

此包提供以下规则。

PlaceholderCharactersRule

占位符名称应仅由字符 A-Z、a-z、0-9、下划线 _ 和点 . 组成。

• 当 $message 中的占位符字符不是 A-Z、a-z、0-9、下划线 _ 和点 . 时，会报告。

// bad
$logger->info('message are {foo-hyphen}');

• 当使用双大括号对 {{ }} 时，会报告。

// bad
$logger->info('message are {{foo}}');

PlaceholderCorrespondToKeysRule

占位符名称必须对应于上下文数组中的键。

• 当消息中存在占位符，但缺少 $context 参数时，会报告。

// bad
$logger->info('message has {nonContext} .');

• 当消息中存在占位符，但 $context 中的键与它们不匹配时，会报告。

// bad
$logger->info('user {user_id} gets an error {error} .', ['user_id' => $user_id]);

ContextKeyRule

注意

PSR-3 没有针对数组键的规定，但在许多情况下很有用。

• 当上下文键不是非空字符串时，会报告。

// bad
[123 => 'foo']`, `['' => 'bar']`, `['baz']

• 当上下文键不匹配您定义的模式时，会报告。
  • 如果未设置 contextKeyOriginalPattern 参数，则此检查将被忽略。

配置

• 您可以使用正则表达式（preg_match()）设置特定的键模式。

parameters:
    sfpPsrLog:
        contextKeyOriginalPattern: '#\A[A-Za-z0-9-]+\z#'

ContextRequireExceptionKeyRule

注意

这不是与 PSR-3 规范一起的规则，但提供了最佳实践。

• 当当前作用域具有 \Throwable 对象时，它将强制将 exception 键放入上下文参数中。

示例

<?php
/** @var \Psr\Log\LoggerInterface $logger */
try {
    //
} catch (LogicException $exception) {
    $logger->warning("foo");
}

$ ../vendor/bin/phpstan analyse
Note: Using configuration file /tmp/your-project/phpstan.neon.
 2/2 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ -------------------------------------------------------------
  Line   Demo.php
 ------ -------------------------------------------------------------
  6      Parameter $context of logger method Psr\Log\LoggerInterface::warning() requires \'exception\' key. Current scope has Throwable variable - $exception
 ------ -------------------------------------------------------------


 [ERROR] Found 1 error

配置

• 您可以设置最低要求级别以报告。 (默认级别是 debug)

parameters:
    sfpPsrLog:
        reportContextExceptionLogLevel: 'warning'

然后，debug| info | notice LogLevel 被忽略。

} catch (\Exception $e) {
  $logger->info('more info'); // allow
  $logger->warning($e->getMessage(), ['exception' => $e]);
}

• 如果您想启用此规则，请添加 enableContextRequireExceptionKeyRule 并将其设置为 true。

parameters:
    sfpPsrLog:
        enableContextRequireExceptionKeyRule: true

MessageStaticStringRule

• 报告当 $message 不是静态字符串值时。

// bad
$logger->info(sprintf('Message contains %s variable', $var));

配置

• 如果您想禁用此规则，请添加 enableMessageStaticStringRule 并将其设置为 false。

parameters:
    sfpPsrLog:
        enableMessageStaticStringRule: false

安装

要使用此扩展，请通过 Composer 引入它

composer require --dev struggle-for-php/sfp-phpstan-psr-log

如果您还安装了 phpstan/extension-installer，则已设置完毕。

手动安装

如果您不想使用 phpstan/extension-installer，请将 extension.neon 和 rules.neon 包含在项目 PHPStan 配置中

includes:
    - vendor/struggle-for-php/sfp-phpstan-psr-log/extension.neon
    - vendor/struggle-for-php/sfp-phpstan-psr-log/rules.neon