Phpstan Lychee Laravel Package

Product Decisions This Supports

• Codifying architecture conventions as executable checks (shift-left quality). This package is a worked example of turning team-specific rules — the kind normally enforced by code review comments and wiki pages — into PHPStan rules that fail CI. That directly supports decisions like "do we invest in review automation vs. headcount?" and "how do we keep a multi-repo Laravel estate consistent?"
• Build vs. buy vs. fork for static analysis. The realistic decision this informs is build: the package is a reference implementation, not a dependency. If your roadmap includes a custom ruleset for your own domain (e.g., "no Eloquent queries in controllers," "no env() outside config," "no cross-module imports"), this repo is a template of how rules are structured, registered, and shipped.
• Multi-repo / monorepo consistency. LycheeOrg maintains several related PHP repos; a shared rules package is the mechanism for keeping them aligned. This maps to decisions about internal platform packages, shared CI images, and org-wide coding standards.
• Upgrade and deprecation enforcement. Custom rules are one of the few cheap levers for making a framework or PHP version migration stick — you encode "old pattern" as a rule, and the codebase self-enforces the migration instead of relying on a migration doc.
• Not supported: general Laravel static-analysis coverage. That is a buy decision (Larastan, phpstan-strict-rules, phpstan-dba), not this package.

When to Consider This Package

Consider it when:

• You are inside LycheeOrg, or you maintain a fork/derivative whose conventions match theirs — in which case adopting is a small, aligned win.
• You are a PHP/Laravel team planning your own custom PHPStan ruleset and want a compact, MIT-licensed reference for structure, rule registration, and packaging. Treat it as documentation-with-code, not a library.
• You need a precedent to justify budget for codifying conventions — a small, real, low-ceremony example is easier to green-light than a proposal document.

Look elsewhere when:

• You need general-purpose rules for a Laravel or PHP codebase. Use Larastan, phpstan/phpstan-strict-rules, phpstan/phpstan-deprecation-rules, and phpstan-dba instead.
• You require external support, stability guarantees, or battle-testing. One star, zero dependents, and a single-org maintainership means bus factor of one and effectively no third-party validation of rule edge cases. Any adoption outside the org should assume you own the code.
• Your conventions diverge from Lychee's. Rules encoding another product's architecture will produce false positives that teams will suppress wholesale — the classic failure mode that poisons trust in static analysis.
• You want framework-agnostic tooling, or you are not already running PHPStan in CI (fix that first; the rules are worthless without the gate).

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed rules package maintained by a single open-source project with essentially no external adoption. It is not a dependency we should take on — no support, no track record, negligible ecosystem signal. Its value to us is as a blueprint: a concrete, inexpensive demonstration of how to move code-review conventions into automated CI checks, which reduces reviewer load and keeps multiple repos consistent as we scale. The recommendation is to spend a small amount of engineering time building our own ruleset modeled on this pattern, not to adopt this package.

For engineering: Treat it as a reference implementation. It shows the end-to-end shape of a custom PHPStan rules package: rule classes, registration, and distribution for use across multiple repos. Read it, copy the structure, write rules for our architecture. Two caveats: the ruleset is tuned to Lychee's design and will produce noise in a codebase with different conventions, and with one maintainer and zero dependents you should expect to own any code you take. Keep the investment scoped — a handful of high-value rules (boundary violations, forbidden APIs, deprecations) delivers most of the benefit; a large speculative ruleset does not. Success metric is fewer convention-related review comments and a clean, low-suppression CI gate within one quarter.