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

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

Installs: 73 011

Dependents: 12

Suggesters: 0

Security: 0

Stars: 36

Watchers: 2

Forks: 2

Open Issues: 6

Type:phpstan-extension


README

Latest Stable Version License Psalm coverage

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

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