Download the PHP package shipmonk/phpstan-rules without Composer
On this page you can find all versions of the php package shipmonk/phpstan-rules. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download shipmonk/phpstan-rules
More information about shipmonk/phpstan-rules
Files in shipmonk/phpstan-rules
Package phpstan-rules
Short Description Various extra strict PHPStan rules we found useful in ShipMonk.
License MIT
Informations about the package phpstan-rules
ShipMonk PHPStan strict rules
About 40 super-strict rules we found useful in ShipMonk. We tend to have PHPStan set up as strict as possible, but that still was not strict enough for us. This set of rules should fill the missing gaps we found.
If you find some rules opinionated, you can easily disable them.
Installation:
Use official extension-installer or enable all rules manually by:
Configuration:
You can easily disable or reconfigure any rule, for example:
Or you can disable all rules and enable only those you want:
When you try to configure any default array, PHPStan config is merged by default, so if you want to enforce only your values and not to include our defaults, use exclamation mark:
Few rules are enabled, but do nothing unless configured, those are marked with *
.
Rules:
allowComparingOnlyComparableTypes
- Denies using comparison operators
>,<,<=,>=,<=>
over anything other thanint|string|float|DateTimeInterface
or same size tuples containing comparable types. Null is not allowed. - Mixing different types in those operators is also forbidden, only exception is comparing floats with integers
- Mainly targets to accidental comparisons of objects, enums or arrays which is valid in PHP, but very tricky
backedEnumGenerics *
- Ensures that every BackedEnum child defines generic type
- This rule makes sense only when BackedEnum was hacked to be generic by stub as described in this article
- This rule does nothing if BackedEnum is not set to be generic, which is a default setup. Use following config to really start using it:
classSuffixNaming *
- Allows you to enforce class name suffix for subclasses of configured superclass
- Checks nothing by default, configure it by passing
superclass => suffix
mapping - Passed superclass is not expected to have such suffix, only subclasses are
- You can use interface as superclass
enforceClosureParamNativeTypehint
- Enforces usage of native typehints for closure & arrow function parameters
- Does nothing on PHP 7.4 and below as native
mixed
is not available there - Can be configured by
allowMissingTypeWhenInferred: true
to allow missing typehint when it can be inferred from the context
enforceEnumMatchRule
- Enforces usage of
match ($enum)
instead of exhaustive conditions likeif ($enum === Enum::One) elseif ($enum === Enum::Two)
- This rule aims to "fix" a bit problematic behaviour of PHPStan (introduced at 1.10.0 and fixed in 1.10.34). It understands enum cases very well and forces you to adjust following code:
Which someone might fix as:
Or even worse as:
We believe that this leads to more error-prone code since adding new enum case may not fail in tests.
Very good approach within similar cases is to use match
construct so that (ideally with forbidMatchDefaultArmForEnums
enabled) phpstan fails once new case is added.
PHPStan even adds tip about match
in those cases since 1.10.11
.
For those reasons, this rule detects any always-true/false enum comparisons and forces you to rewrite it to match ($enum)
.
Since PHPStan 1.10.34, the behaviour is much better as it does not report error on the last elseif in case that it is followed by else with thrown exception. Such case raises exception in your tests if you add new enum case, but it is still silent in PHPStan. This leaves space for error being deployed to production. So we still believe this rule makes sense even in latest PHPStan.
enforceIteratorToArrayPreserveKeys
- Enforces presence of second parameter in iterator_to_array call (
$preserve_keys
) as the default valuetrue
is generally dangerous (risk of data loss / failure) - You can use both
true
andfalse
there, but doing so is intentional choice now
enforceListReturn
- Enforces usage of
list<T>
when list is always returned from a class method or function - When only single return with empty array is present in the method, it is not considered as list
- Does nothing when list types are disabled in PHPStan
- Consider enabling also reportAnyTypeWideningInVarTag in native PHPStan as it mostly affects lists
enforceNativeReturnTypehint
- Enforces usage of native return typehints if supported by your PHP version
- If PHPDoc is present, it deduces needed typehint from that, if not, deduction is performed based on real types returned
- Applies to class methods, closures and functions
- Is disabled, if you have PHPStan set up with
treatPhpDocTypesAsCertain: false
- Limitations:
- Does not suggest parent typehint
- Ignores trait methods
enforceReadonlyPublicProperty
- Ensures immutability of all public properties by enforcing
readonly
modifier - No modifier needed for readonly classes in PHP 8.2
- Does nothing if PHP version does not support readonly properties (PHP 8.0 and below)
forbidArithmeticOperationOnNonNumber
- Disallows using arithmetic operators with non-numeric types (only float and int is allowed)
- You can allow numeric-string by using
allowNumericString: true
configuration - Modulo operator (
%
) allows only integers as it emits deprecation otherwise - Plus operator is allowed for merging arrays
forbidCast
- Deny casting you configure
- Possible values to use:
(array)
- denied by default(object)
- denied by default(unset)
- denied by default(bool)
(int)
(string)
(float)
- forbids using also(double)
and(real)
forbidCheckedExceptionInCallable
- Denies throwing checked exception in callables (Closures, Arrow functions and First class callables) as those cannot be tracked as checked by PHPStan analysis, because it is unknown when the callable is about to be called
- It is allowed to throw checked exceptions in immediately called callables (e.g. params marked by
@param-immediately-invoked-callable
, see docs) - It allows configuration of functions/methods, where the callable is handling all thrown exceptions and it is safe to throw anything from there; this basically makes such calls ignored by this rule
- It ignores implicitly thrown Throwable
-
Learn more in π¨πΏ talk about checked exceptions in general (πΊπΈ slides)
- We recommend using following config for checked exceptions:
- Also, bleedingEdge enables proper analysis of dead types in multi-catch, so we recommend enabling even that
forbidCheckedExceptionInYieldingMethod
- Denies throwing checked exception within yielding methods as those exceptions are not throw upon method call, but when generator gets iterated.
- This behaviour cannot be easily reflected within PHPStan exception analysis and may cause false negatives.
- Make sure you have enabled checked exceptions, otherwise, this rule does nothing
forbidCustomFunctions *
- Allows you to easily deny some approaches within your codebase by denying classes, methods and functions
- Configuration syntax is array where key is method name and value is reason used in error message
- Works even with interfaces, constructors and some dynamic class/method names like
$fn = 'sleep'; $fn();
forbidEnumInFunctionArguments
- Guards passing native enums to native functions where it fails / produces warning or does unexpected behaviour
- Most of the array manipulation functions does not work with enums as they do implicit __toString conversion inside, but that is not possible to do with enums
- See test for all functions and their problems
forbidFetchOnMixed
- Denies constant/property fetch on unknown type.
- Any property fetch assumes the caller is an object with such property and therefore, the typehint/phpdoc should be fixed.
- Similar to
forbidMethodCallOnMixed
- Makes sense only on PHPStan level 8 or below, gets autodisabled on level 9
forbidIdenticalClassComparison
- Denies comparing configured classes by
===
or!==
- Default configuration contains only
DateTimeInterface
- You may want to add more classes from your codebase or vendor
forbidIncrementDecrementOnNonInteger
- Denies using
$i++
,$i--
,++$i
,--$i
with any non-integer - PHP itself is leading towards stricter behaviour here and soft-deprecated some non-integer usages in 8.3, see RFC
forbidMatchDefaultArmForEnums
- Denies using default arm in
match()
construct when native enum is passed as subject - This rules makes sense only as a complement of native phpstan rule that guards that all enum cases are handled in match arms
- As a result, you are forced to add new arm when new enum case is added. That brings up all the places in your codebase that needs new handling.
forbidMethodCallOnMixed
- Denies calling methods on unknown type.
- Any method call assumes the caller is an object with such method and therefore, the typehint/phpdoc should be fixed.
- Similar to
forbidFetchOnMixed
- Makes sense only on PHPStan level 8 or below, gets autodisabled on level 9
forbidNotNormalizedType
- Reports PhpDoc or native type that is not normalized, which can be:
- when child and parent appears in its union or intersection
- when same type appears multiple times in its union or intersection
- when DNF is not used
- configurable by
checkDisjunctiveNormalForm
- supports:
- parameter typehints &
@param
phpdoc - return typehint &
@return
phpdoc - property typehint &
@var
phpdoc - inline
@var
phpdoc @throws
phpdoc- multi-catch statements
- Main motivation here is that PHPStan normalizes all types before analysis, so it is better to see it in codebase the same way PHPStan does
forbidNullInAssignOperations
- Denies using assign operators if null is involved on right side
- You can configure which operators are ignored, by default only
??=
is excluded
forbidNullInBinaryOperations
- Denies using binary operators if null is involved on either side
- You can configure which operators are ignored. Default ignore is excluding only
===, !==, ??
- Following custom setup is recommended when using latest phpstan-strict-rules and
allowComparingOnlyComparableTypes
is enabled
forbidNullInInterpolatedString
- Disallows using nullable expressions within double-quoted strings
- This should probably comply with setup of concat operator (
.
) inforbidNullInBinaryOperations
so if you blacklisted it there, you might want to disable this rule
forbidPhpDocNullabilityMismatchWithNativeTypehint
- Disallows having nullable native typehint while using non-nullable phpdoc
- Checks
@return
and@param
over methods and@var
over properties - PHPStan itself allows using subtype of native type in phpdoc, but resolves overall type as union of those types making such phpdoc actually invalid
forbidProtectedEnumMethod
- Disallows protected method within enums as those are not extendable anyway
- Ignore method declared in traits as those might be reused in regular classes
forbidReturnValueInYieldingMethod
- Disallows returning values in yielding methods unless marked to return Generator as the value is accessible only via Generator::getReturn
- To prevent misuse, this rule can be configured to even stricter mode where it reports such returns regardless of return type declared
forbidUnsafeArrayKey
- Denies non-int non-string array keys
- PHP casts
null
,float
andbool
to some nearest int/string- You should rather do that intentionally and explicitly
- Those types are the main difference to default PHPStan behaviour which allows using them as array keys
- You can exclude reporting
mixed
keys viareportMixed
configuration - You can exclude reporting
isset($array[$invalid])
and$array[$invalid] ?? null
viareportInsideIsset
configuration
forbidVariableTypeOverwriting
- Restricts variable assignment to those that does not change its type
- Array append
$array[] = 1;
not yet supported
- Array append
- Null and mixed are not taken into account, advanced phpstan types like non-empty-X are trimmed before comparison
- Rule allows type generalization and type narrowing (parent <-> child)
forbidUnsetClassField
- Denies calling
unset
over class field as it causes un-initialization, see https://3v4l.org/V8uuP - Null assignment should be used instead
forbidUselessNullableReturn
- Denies marking closure/function/method return type as nullable when null is never returned
- Recommended to be used together with
uselessPrivatePropertyDefaultValue
forbidUnusedException
- Reports forgotten exception throw (created or returned from function, but not used in any way)
forbidUnusedMatchResult
- Reports forgotten usage of match result
- Any
match
with at least one arm returning a value is checked
requirePreviousExceptionPass
- Detects forgotten exception pass-as-previous when re-throwing
- Checks if caught exception can be passed as argument to the call (including constructor call) in
throw
node inside the catch block -
You may encounter false-positives in some edge-cases, where you do not want to pass exception as previous, feel free to ignore those
- If you want to be even stricter, you can set up
reportEvenIfExceptionIsNotAcceptableByRethrownOne
totrue
and the rule will start reporting even cases where the thrown exception does not have parameter matching the caught exception- Defaults to true
- That will force you to add the parameter to be able to pass it as previous
- Usable only if you do not throw exceptions from libraries, which is a good practice anyway
uselessPrivatePropertyDefaultValue:
- Detects useless default value of a private property that is always initialized in constructor.
- Cannot handle conditions or private method calls within constructor.
- When enabled, return statements in constructors are denied to avoid false positives
- Recommended to be used with
forbidUselessNullableReturn
Native PHPStan extra strictness
Some strict behaviour in PHPStan is not enabled by default, consider enabling extra strictness even there:
Contributing
- Check your code by
composer check
- Autofix coding-style by
composer fix:cs
- All functionality must be tested