Phpstan Php Language Extensions Laravel Package

Getting Started

This extension wires the attributes from dave-liddament/php-language-extensions into PHPStan, so violations of those attributes become static-analysis errors instead of runtime surprises.

1. Install the runtime attributes package and the PHPStan rule package (the latter is dev-only because it only matters during analysis):

   composer require dave-liddament/php-language-extensions
   composer require --dev dave-liddament/phpstan-php-language-extensions
   

2. Register the rules. If you use phpstan/extension-installer, they are picked up automatically. Otherwise include the shipped ruleset in phpstan.neon:

   includes:
       - vendor/dave-liddament/phpstan-php-language-extensions/rules.neon
   

3. Look first at your existing phpstan.neon and the package's rules.neon / README to see which rules are registered and which parameters keys they read. The attributes are inert at runtime, so nothing changes behavior — analysis is where they pay off.

4. First use case: mark an unstable class as #[Internal] and confirm PHPStan flags a call from outside the allowed namespace. That single rule is the one most teams adopt first, because it turns "please don't use this" comments into build failures.

Implementation Patterns

• API boundaries (#[Internal] / #[NotInternal]). Tag implementation classes as internal; the rule reports usage from outside the package/namespace you configure. Use #[NotInternal] on the few classes that must stay public (e.g. a factory you re-export).
• Named-argument enforcement (#[RequiresNamedArguments]). Put it on constructors and factory methods whose signatures are likely to change. The rule flags positional calls, so adding a parameter later doesn't silently reorder arguments at call sites.
• Readonly enforcement (#[EnforceReadonly]). Apply to value objects; the rule insists the class and its properties are readonly, catching classes that drifted from the convention.
• Layering with baselines. Adopt the rules on a legacy codebase with a baseline first (phpstan --generate-baseline), then fix incrementally.
• CI integration. The rules run as part of your normal vendor/bin/phpstan analyse step — no new CI job required. Add the analysis target for src/ only; you generally don't want to analyze vendor attributes themselves.
• Combine with runtime checks where it matters. For #[Internal], also mark the method @internal in the docblock so IDE/other tooling aligns with the PHPStan rule.

Gotchas and Tips

• Errors are reported at the call site, not the definition. Ignore rules must target the calling file/method. Use the error identifier (something like phpLanguageExtensions.internal) in ignoreErrors rather than the message text, which can vary between PHPStan versions.
• Config parameter names move between releases. The package is small and pre-1.0-ish in maturity; the parameter keys that describe "what counts as inside" for Internal are the thing most likely to change. Pin a version in composer.json and check the README on upgrade.
• PHPStan version compatibility. The package depends on PHPStan internals for rule registration; a major PHPStan upgrade (e.g. 1.x → 2.x) is the most common breakage point. Run PHPStan in CI at a pinned version.
• EnforceReadonly can false-positive. Classes that legitimately need mutable state will trip it. Prefer removing the attribute over suppressing; suppression is a slippery slope here.
• Named-argument rule only fires on statically resolvable calls. Dynamic calls (call_user_func, variable functions, new $class) escape it — don't assume full coverage.
• #[Internal] requires autoloading during analysis. If the class isn't autoloadable at PHPStan time (odd PSR-4 setups, generated code), the rule can't read the attribute and silently passes. Verify with phpstan -vvv that the file is being resolved.
• Attributes don't replace @internal and vice versa. The attribute drives PHPStan; the docblock drives IDEs and other static analyzers. For a public surface you care about, set both.
• Extension point: if a project-specific policy is needed (e.g. "this namespace must be named-argument-only"), that's generally cleaner as a custom PHPStan rule in your own extension than as an ever-growing ignoreErrors list.