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

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

psr/log(PSR-3) extensions for PHPStan

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 .

📌 error identifier
sfp-psr-log.placeholderCharactersInvalidChar

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

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

📌 error identifier
sfp-psr-log.placeholderCharactersDoubleBraces

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

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

PlaceholderCorrespondToKeysRule

Placeholder names MUST correspond to keys in the context array.

📌 error identifier
sfp-psr-log.placeholderCorrespondToKeysMissedContext

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

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

📌 error identifier
sfp-psr-log.placeholderCorrespondToKeysMissedKey

• 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.

📌 error identifier
sfp-psr-log.contextKeyNonEmptyString

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

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

📌 error identifier
sfp-psr-log.contextKeyOriginalPattern

• 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.

📌 error identifier
sfp-psr-log.contextRequireExceptionKey

• 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

📌 error identifier
sfp-psr-log.messageNotStaticString

• 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

sfp-phpstan-psr-log's Issues

Error on analyse reported in struggle-for-php/sfp-stubs-psr-log/stubs-for-throwable/LoggerInterface.phpstub

Hello

I'm currently encountering an error when trying to run the phpstan analysis. This problem occurs on two different projects.

Has anyone had this problem before?

I don't have a repo to share yet, but I'll do it soon to provide a reproducible repo.

phpstan version: 1.10.67
php: 8.3
Installed with phpstan/extension-installer

Feature Request - Check placeholder & context key

Rules for context array should be get values with `->getConstantArrays()`

• ContextKeyRule
• ContextRequireExceptionKeyRule
  • seems useless. currently already variable array is supported, and union type is not supported. union type support is meaningless for this rule.
• also PlaceholderCorrespondToKeysRule

current implementations only checks dynamic parameter $logger->info('foo', ['key' => 'bar']);.
Rules should be checked with phpdoc parameter, method scope array variable( $context = ['key' => 'bar']; $logger->info('foo', $context); )

Support `treatPhpDocTypesAsCertain` parameter

refs. https://github.com/phpstan/phpstan-src/blob/1.11.x/src/Rules/Functions/ArrayFilterRule.php

Add `.editorconfig`

[Idea]New Rule -$context is only Constant Array

Do not allow non-key array (non array-shapes $context)

// bad

/**
 * @param array $param
 */
function foo(array $param) {
   $logger->info('message', ['user_id' => $userId] + $param);
}

optional support for usage of `sprintf` on MessageStaticStringRule

To be consider these cases.

// allow
$logger->info(sprintf('got %d some', $number));
$logger->info(sprintf('got %s some', $literalString));
$logger->info(sprintf('got %s some', $nonTaintString));

ContextRequireExceptionKeyRule - when it is below a certain level, an exception is not required.

As a practical case, when logging with 'info' level is done during retry processing.
In that case, I don't want to make it mandatory to pass an exception.

Feature Request - Validate Placeholder name

Placeholder names SHOULD be composed only of the characters A-Z, a-z, 0-9, underscore _, and period .. The use of other characters is reserved for future modifications of the placeholders specification.

https://www.php-fig.org/psr/psr-3/#12-message

[Idea] Support Google Big Query Schema as context's array type

for cloud logging sink.

• To avoid "Errors routing"
  https://cloud.google.com/logging/docs/export/troubleshoot?hl=en

If the key name is the same but the type is different, an error will occur.

ContextRequireExceptionKeyRule should support `non-capturing catches`

Also see refs. phpstan/phpstan#8663 ( Catching exception without capturing on PHP 7.4 is not allowed )
https://wiki.php.net/rfc/non-capturing_catches

Currently, would not be detected by ContextRequireExceptionKeyRule below case.

try {
  print 'Lets do something nasty here.';
  throw new Exception('This is nasty');
} catch (Exception) {
  print 'Exception occured';
  $this->logger->error('error happend'); // should be reported as requires \'exception\' key. 

Because, ContextRequireExceptionKeyRule does detects with findCurrentScopeThrowableVariable.