Phpstan Forbidden Laravel Package

Product Decisions This Supports

• Codifying architecture decisions instead of documenting them. Every ADR that says "don't call env() outside config/", "don't use DB:: in controllers", "don't touch the legacy Billing namespace" is currently enforced by code review and memory. This package turns those decisions into CI failures — the decision becomes a build artifact rather than a wiki page.
• Deprecation and migration programs. Ban a class, method, or function and you get a live, per-PR count of remaining usages. That gives you a measurable burn-down for a framework upgrade, a service extraction, or a "kill the v1 SDK" initiative — the kind of progress metric that's otherwise assembled by hand before every steering meeting.
• Build vs. buy vs. write-it-yourself. The scope is narrow (PHPStan custom rules that report banned nodes). The realistic options are: adopt this, adopt the far more established spaze/phpstan-disallowed-calls, or have an engineer write an in-house rule in a day or two. This evaluation is itself the product decision — pick deliberately, not by default.
• Standardizing the approved stack. Banning competing libraries (a second HTTP client, a second date library, raw curl_* calls) is how a platform team makes "use the approved SDK" real without a policing process. Useful when you're consolidating after an acquisition or merging two codebases.
• Risk and compliance guardrails. Banning eval, unserialize, md5/sha1 for credentials, shell_exec, and similar is a cheap control that maps to security review findings and audit questions. It converts a policy document into a pass/fail gate.
• Review-load reduction. Measurable as fewer "you shouldn't use that here" comments per PR. That's a real capacity argument when you're trying to raise throughput without headcount.

When to Consider This Package

Adopt when most of the following hold:

• The codebase already runs PHPStan in CI at a meaningful level. This package is worthless without that base; it's an add-on, not a standalone linter.
• You have more than a handful of engineers, or multiple teams sharing a Laravel codebase where conventions drift.
• You have written-down architectural rules that are currently unenforced — that gap is the actual pain being solved.
• You're mid-migration and need a visible, shrinking violation count.
• Someone on the team can own the configuration file and the PHPStan version pin.

Look elsewhere — or don't adopt — when:

• Not on PHPStan / not on Laravel. Different toolchain, different problem.
• You only need one or two bans. PHPStan ships forbiddenFunctions-style configuration natively; you don't need a dependency for that.
• You need breadth. spaze/phpstan-disallowed-calls is the community default for this exact job, with a much larger user base. Choosing a 7-star, 0-dependent package over a widely adopted alternative needs a specific reason — better ergonomics, better Laravel fit, or an internal fork you intend to support.
• Dependency-risk tolerance is low. Seven stars, a single maintainer, no dependents, and a release date that reads as future-dated relative to today all warrant a provenance and maintenance check before it touches your CI. Cheap mitigation: vendor it, or treat it as a pattern to reimplement rather than a long-term dependency.
• You need runtime enforcement. This is static analysis only; anything dynamic (feature flags, tenant rules, data-level policy) is out of scope.
• You're pre-product-market-fit. Guardrail tooling is a scaling investment; at small team size the review process is the guardrail and it's working fine.

How to Pitch It (Stakeholders)

For executives: A very low-cost CI addition that converts our written engineering standards into automatic checks. The business value is not the tool — it's that architecture decisions stop being advisory. It gives us a number for migration and deprecation work ("412 remaining usages, down from 1,100") instead of a status color. Cost is negligible; the main risk is maintenance of a small open-source dependency, which we contain by pinning a version and keeping the configuration in our repo.

For engineering leadership: We already pay for PHPStan on every PR. This extends it so that "don't use X" is a build failure instead of a code review negotiation. It's the cheapest way to make ADRs enforceable and to get per-PR visibility into migration progress. The tradeoff is explicit: the package is small and lightly adopted, so we either (a) accept it as a thin, replaceable dependency, (b) use the more established spaze/phpstan-disallowed-calls instead, or (c) write the equivalent rule ourselves in a day or two. Recommendation is to decide that tradeoff intentionally and not let the tooling choice happen by accident.

The one-line version: It's a spell-checker for our architecture rules — cheap to try, trivial to remove, and it makes our standards actually true.