struggle-for-php/sfp-phpstan-psr-log

Extra strict and opinionated psr/log (psr-3) rules for PHPStan

0.23.0 2024-11-11 12:09 UTC

Requires

• php: ^7.2.0 || ~8.0.0 || ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0
• phpstan/phpstan: ^1.12 || ^2.0
• struggle-for-php/sfp-stubs-psr-log: ^1.0.1 || ^2 || ^3.0.1

Requires (Dev)

• laminas/laminas-coding-standard: ^2.0.0
• maglnet/composer-require-checker: ^2|^3|^4
• phpstan/phpstan-phpunit: ^1.3 || ^2.0
• phpstan/phpstan-strict-rules: ^1.5 || ^2.0
• phpunit/phpunit: ^8.5.31 || ^9.5.10 || ^10.5.35
• roave/security-advisories: dev-master
• squizlabs/php_codesniffer: ^3.7
• vimeo/psalm: ^4 || ^5.26

Conflicts

• nikic/php-parser: <4.13.0

MIT

• logging
• static analysis
• psr-3
• PSR3
• PHPStan

README

struggle-for-php/sfp-phpstan-psr-log is extra strict and opinionated psr/log (psr-3) rules for PHPStan.

• PHPStan
• PSR-3: Logger Interface - PHP-FIG
• PSR-3 Meta Document

Important

Since 0.20.0, changed default rule settings.

• MessageStaticStringRule is enabled by default.
• ContextRequireExceptionKeyRule is disabled by default.
• [Recommendation] write these parameters to your project's phpstan.neon.

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

Stubs

This extension depends on our psr/log stub to serve strictness.

• eg.
  • @param LogLevel::* $level at log() method
  • @param array{exception?: \Throwable} $context

See psr/log stub repository page to get more detail.

Rules

This package provides the following rules.

PlaceholderCharactersRule

Placeholder names SHOULD be composed only of the characters A-Z, a-z, 0-9, underscore _, and period .

• reports when placeholder in $message characters are not, A-Z, a-z, 0-9, underscore _, and period .

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

• reports when double braces pair {{ }} are used.

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

PlaceholderCorrespondToKeysRule

Placeholder names MUST correspond to keys in the context array.

• reports when placeholder exists in message, but $context parameter is missed.

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

• reports when placeholder exists in message, but key in $context does not exist against them.

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

ContextKeyRule

Note

PSR-3 has no provisions for array keys, but this is useful in many cases.

• reports when context key is not non-empty-string.

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

• reports when context key is not matched you defined pattern.
  • if contextKeyOriginalPattern parameter is not set, this check would be ignored.

Configuration

• You can set specific key pattern by regex.(preg_match())

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

ContextRequireExceptionKeyRule

Note

This is not a rule for along with PSR-3 specification, but provides best practices.

• It forces exception key into context parameter when current scope has \Throwable object.

Example

<?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

Configuration

• You can set the minimum required level to report. (default level is debug)

parameters:
    sfpPsrLog:
        reportContextExceptionLogLevel: 'warning'

Then, debug| info | notice LogLevel is ignored for report.

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

• If you want to enable this rule, please add enableContextRequireExceptionKeyRule as true.

parameters:
    sfpPsrLog:
        enableContextRequireExceptionKeyRule: true

MessageStaticStringRule

• reports when $message is not static string value.

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

Configuration

• If you want to disable this rule, please add enableMessageStaticStringRule as false.

parameters:
    sfpPsrLog:
        enableMessageStaticStringRule: false

Installation

To use this extension, require it in Composer:

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

If you also install phpstan/extension-installer then you're all set.

Manual installation

If you don't want to use phpstan/extension-installer, include extension.neon & rules.neon in your project's PHPStan config:

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