Phpstan Php Language Extensions Laravel Package

Product Decisions This Supports

• Build vs. buy for architecture governance. Instead of funding custom PHPStan rules or bespoke static-analysis scripts to police module boundaries, this package lets you adopt pre-built enforcement for the php-language-extensions attribute family (#[Internal], #[Friend], #[Pure], #[Immutable], #[NamedConstructor], etc.). The decision is a low-cost "buy" (MIT, zero runtime footprint) against an expensive-to-maintain internal alternative.
• Opening or closing an internal API. #[Internal] and #[Friend(SomeClass::class)] turn "please don't call this from outside the module" from a wiki page into a CI failure. That makes go/no-go decisions about exposing a class to another team a code change with a reviewable diff, not a social negotiation.
• Modularisation roadmap (monolith → modules). Friend declarations are an incremental seam: you can carve out a module boundary, allow a handful of legacy callers explicitly, and shrink that allowlist sprint by sprint. This gives the roadmap a measurable burn-down (count of #[Friend] entries per module) instead of a subjective "we're more modular now."
• SDK / library / plugin-platform surface control. For teams shipping packages consumed by other teams or external developers, this supports decisions about what is contractually public, what is provisional, and what is explicitly off-limits — enforced at the point of code, not in release notes.
• Coupling metrics as a planning input. Violation counts and friend-declaration counts are honest, automatable proxies for coupling. Useful for prioritising refactoring work and for arguing for (or against) a platform-team investment.
• Deprecation and migration sequencing. Marking a class internal-first and observing who breaks tells you the real blast radius before you commit to a removal date.

When to Consider This Package

Adopt it when most of the following hold:

• PHPStan is already in CI. This extension is a plugin for PHPStan; if you aren't running PHPStan, adopting this is really a decision to adopt PHPStan. Do not smuggle a second static-analysis tool in through the back door.
• You intend to use (or already use) php-language-extensions. The package validates those attributes; without the attributes it does nothing. Treat it as the enforcement half of a two-part adoption.
• Boundaries are currently enforced by convention, code review, or folklore. That is precisely the gap static enforcement closes.
• You have a monorepo or shared internal libraries with multiple consuming teams — the value scales with the number of teams that can accidentally reach into each other's code.
• Static-only enforcement is acceptable. These checks run at analysis time and are trivially bypassed at runtime by anyone who ignores the tooling. If you need guarantees, this is not the tool.
• You can absorb a small third-party dependency in your PHPStan upgrade path. Pin it and budget an hour per PHPStan major upgrade.

Look elsewhere when:

• You need runtime enforcement (container-level access control, sealed classes at the language level). Consider readonly/final/visibility, or a proper module system.
• You need whole-codebase dependency-direction rules — layers, forbidden dependencies between namespaces, cycle detection. deptrac or phparkitect are the better fit; this package governs class-level access, not architectural layers.
• Your team is on Psalm, not PHPStan. There is a separate Psalm plugin for the same attribute family; don't adopt this one by mistake.
• The codebase is small and single-team. Convention is cheaper than a CI dependency; the payoff arrives with organisational scale.
• Governance-critical adoption with no fallback appetite. 44 stars, zero dependents, single maintainer. Treat it as a reversible bet rather than load-bearing infrastructure, or be prepared to vendor it (MIT permits this) if it goes quiet.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, free, MIT-licensed plugin that makes our architecture rules enforceable in CI rather than advisory. It costs nothing at runtime, adds no production dependency, and lets us stop paying for custom tooling and manual review to police which teams may use which classes. It directly supports our modularisation work: each boundary we declare becomes a measurable, shrinking list of exceptions instead of an unverifiable claim. The honest caveat is maturity — a single maintainer and a small user base — so we should treat it as a cheap, reversible experiment with a one-sprint spike, not a strategic bet. If it disappoints, we remove one line from CI config.

For engineering (one paragraph): Attributes are inert at runtime, so this adds zero production behaviour. The package is a PHPStan extension that validates php-language-extensions attributes — #[Internal], #[Friend], #[Pure], #[Immutable], #[NamedConstructor] — so the rules you write in code become PHPStan errors, using the CI step you already run. No new pipeline, no new tool for developers to learn. It complements rather than replaces deptrac: this covers class-level access ("who may call this"), deptrac covers layer-level direction ("what may depend on what"). Adopt in a spike: enable it, run it against one module, and measure the violation count before committing. Pin the version and expect a small maintenance touch on PHPStan major upgrades. It is straightforward to vendor or fork if the project stalls, given the license and small surface area.

Recommendation: Time-boxed pilot (one sprint) on a single bounded module, with success defined as: attribute enforcement running in CI, a baseline violation count, and a friend-declaration count we can trend. If the maintainer or PHPStan compatibility looks shaky at review, fall back to a handful of native PHPStan rules — but note that fallback costs more to build and maintain than this package does to adopt.