Prepare for PHPStan 1.0

[ondrejmirtes]

Hello everyone 👋

I announced today that PHPStan 1.0 is going to be released on November 1st 2021.

I'm approaching you as one of the most popular PHPStan extensions. I'd love if you could prepare your code for PHPStan 1.0 in advance so that it's ready to release on the same day.

Here's a brief guide how to approach the upgrade:

1. Create a branch 🌴
2. Update your composer.json to "phpstan/phpstan": "^1.0", add "minimum-stability": "dev" and "prefer-stable": true if necessary.
3. Update your code with the BC breaks below in mind. 🔧
4. Fix the code so that it passes PHPStan's analysis 🤓
5. Wait for PHPStan 1.0 release on November 1st, merge your branch and tag the next major version 👍

Thank you!

---

Here are the BC breaks. The list is huge but most of those have very little impact.

There are new rules around using PHPStan internals in regard to backward compatibility promise: https://phpstan.org/developing-extensions/backward-compatibility-promise

It's possible that not everything you use is covered by it - so I'm here to help you to transition to correct usage, or add some @api annotations in PHPStan itself so that more is covered by the promise. Let me know!

BC breaks for end-users

• Level max is now level 9. Feel free to update max to 8 if your code isn't ready.
• Description of some types was updated to match the syntax in PHPDocs. This includes numeric-string (it was previously described as string&numeric), and also array shapes.
• Removed baselineNeon error formatter, use --generate-baseline CLI option instead (phpstan/phpstan-src@492cfbc)
• Removed polluteCatchScopeWithTryAssignments config parameter (phpstan/phpstan-src@8933c7e)
• Removed deprecated autoload_files parameter - use Discovering Symbols instead (phpstan/phpstan-src@7a21246)
• Removed deprecated autoload_directories parameter - use Discovering Symbols instead (phpstan/phpstan-src@f67b48a)
• Removed bootstrap parameter - use bootstrapFiles instead (phpstan/phpstan-src@1baa294)
• Moved implicitThrows configuration parameter to exceptions.implicitThrows (phpstan/phpstan-src@96b7c48)
• Removed --paths-file CLI option (phpstan/phpstan-src@5670cf2)
• Removed dump-deps command (phpstan/phpstan-src@9c7017c)
• Deprecated excludes_analyse option, use excludePaths instead (phpstan/phpstan-src@d25c5e5)

The following are interesting only if you create a custom ruleset in your configuration file:

• Removed DeadCatchRule, replaced by CatchWithUnthrownExceptionRule (phpstan/phpstan-src@4dba60b)
• Removed VariableCertaintyInIssetRule, replaced by IssetRule (phpstan/phpstan-src@2e858de)
• Removed MissingClosureNativeReturnTypehintRule, no longer needed thanks to type inference (phpstan/phpstan-src@1c34d8d)
• Rename rules with typos (phpstan/phpstan-src@003ab1a)

BC breaks for extension developers

• Extensions are checked with rules for correct usage of PHPStan internals according to backward compatibility promise.
• Removed CompoundTypeHelper (phpstan/phpstan-src@145c4e3)
• Removed CommentHelper (phpstan/phpstan-src@ebad6f6)
• Removed DependencyDumper (phpstan/phpstan-src@9c7017c)
• Removed PHPStan\Reflection\Generic\ResolvedFunctionVariant, replaced by PHPStan\Reflection\ResolvedFunctionVariant (phpstan/phpstan-src@1cc6c81)
• Removed ClassReflection::getNativeMethods(), use getNativeReflection() instead (phpstan/phpstan-src@d2c1446)
• Removed PhpPropertyReflection::hasPhpDoc(), replaced by hasPhpDocType() (phpstan/phpstan-src@bedd5be)
• NodeDependencies no longer iterable (phpstan/phpstan-src@f76875a)
• Renamed TestCase to PHPStanTestCase (#634), thanks @frankdejonge!
• StaticType and ThisType - require ClassReflection in constructor (phpstan/phpstan-src@7aabc84)
• PHPStanTestCase - extensions can no longer be provided by overriding methods from PHPStanTestCase. Use getAdditionalConfigFiles() instead. (phpstan/phpstan-src@65efd93, phpstan/phpstan-src@239291a)
• Removed some unused internal helper methods from Broker (phpstan/phpstan-src@d578151)
• Changed return types of various methods that had |false to |null (phpstan/phpstan-src@629ccf6)
• Type generalization precision is now a required argument (phpstan/phpstan-src@6568103)
• Some constructor parameters are now required (phpstan/phpstan-src@1f4062f)
• Deprecated BrokerAwareExtension (phpstan/phpstan-src@db2f7fb)
• Deprecated PHPStanTestCase::createBroker(). Use createReflectionProvider() instead. (phpstan/phpstan-src@1e5cf58)
• Deprecated PHPStan\Broker\Broker. Use PHPStan\Reflection\ReflectionProvider instead. (phpstan/phpstan-src@c775594)
• Deprecated PHPStan\Broker\Broker::getInstance(). Use PHPStan\Reflection\ReflectionProviderStaticAccessor instead. (phpstan/phpstan-src@4e7d60d)

[localheinz]

Thank you, @ondrejmirtes, for reaching out with detailed explanations for upgrading - I will update as soon as possible!

[rpkamp]

@localheinz is there a timeline for this and/or is there anything I can do to help out?

[localheinz]

@rpkamp

Haven't had the time to take care of this yet, but if you can spare some time and submit a pull request, I would appreciate it!

[InvisibleSmiley]

extensions can no longer be provided by overriding methods from PHPStanTestCase. Use getAdditionalConfigFiles() instead.

This affects RuleTestCase as well. My test failed because getStaticMethodTypeSpecifyingExtensions was removed.

[rpkamp]

@InvisibleSmiley that sounds like a problem with PHPStan itself, not this extension. Or am I missing something?

[InvisibleSmiley]

@InvisibleSmiley that sounds like a problem with PHPStan itself, not this extension. Or am I missing something?

Oh sorry, I think I had previously visited this page and quickly glanced at the title and list of changes without checking the URL.
Commented on the PHPStan 1.0 release discussion thread now.