Soda Laravel Package

Product Decisions This Supports

• Adopting a standard, opinionated quality gate for Laravel/PHP services. The release ships a 108-check default gate with stable rule IDs and no new dependencies, making it a low-risk candidate for a shared CI standard across repositories.
• Build vs. buy for static-analysis policy. Rather than maintaining bespoke PHPStan/Rector/CS rules internally, this package provides a maintained rule set. The release's focus on false-positive reduction (redundant else/elseif only after proven unconditional exits; prefer_continue restricted to nested executable control flow) is the kind of maintenance cost a team avoids by buying rather than building.
• Default-gate composition and roadmap sequencing. max_return_statements has been removed from the standard gate but remains an explicit opt-in rule. PM decision: whether our baseline enforces return-count limits by default or treats them as a team-specific add-on. This affects onboarding friction and legacy-code migration plans.
• Upgrade scheduling. Rules and IDs remain compatible, existing explicit configurations are retained, and no new options or dependencies were introduced. This supports a routine minor-version upgrade rather than a dedicated migration epic.
• Reducing review friction and suppression debt. Narrower, better-justified findings mean fewer inline ignores and less reviewer debate. The corrected documentation rewrites and added regression cases support trust in reported findings, which is a prerequisite for enforcing the gate as blocking rather than advisory.
• Behavior-preserving refactors and legacy modernization. The release explicitly protects observable bindings inside try/finally and return variables carrying local type assertions. That reduces the risk of automated or suggested rewrites changing runtime behavior in payment, queue, and transaction-heavy Laravel code paths.

When to Consider This Package

Consider adoption when:

• You maintain one or more Laravel/PHP codebases and want a consistent, enforceable style and control-flow standard in CI without writing and maintaining custom rules.
• Your team is debating readability and control-flow conventions (early returns, continue over nesting, redundant branches) and needs an objective arbiter rather than ad-hoc review comments.
• You are standardizing across teams and value stable rule IDs and backward-compatible configuration, so baselines do not churn on every upgrade.
• You are modernizing legacy code and want guardrails that avoid behavior-changing rewrites in try/finally blocks and typed return paths.
• You want a low-migration-cost addition: this release adds no dependencies and no new options, and preserves existing explicit configurations.

Look elsewhere or defer when:

• Your organization already has a mature, heavily customized static-analysis stack (PHPStan/Rector/CS-Fixer with in-house rules) and the marginal value of an additional ruleset is low.
• You need framework-agnostic analysis; this is positioned for Laravel/PHP conventions.
• You depend on max_return_statements as a blocking default. It has been removed from the standard gate; you must configure it explicitly, so evaluate whether that changes your baseline before upgrading.
• You require strict semantic/type analysis rather than style and control-flow guidance; this package narrows findings but is not a substitute for type checking.

How to Pitch It (Stakeholders)

For executives: This is a low-risk, no-new-dependency upgrade to our PHP code-quality tooling. It reduces noisy, incorrect findings that slow down code review, keeps existing configurations and rule IDs intact, and requires no migration work. It supports a consistent engineering standard across Laravel services and lowers the cost of modernizing legacy code without changing runtime behavior.

For engineering leadership: The release is primarily a precision improvement — fewer false positives on else/elseif, prefer_continue, and return-count rules, with explicit protection for observable bindings in try/finally and typed return paths. The default gate is now 108 checks; max_return_statements remains available but must be opted into explicitly. Adopt it as a standard gate, decide deliberately whether to re-enable the return-count rule, and schedule the upgrade as a routine minor-version change rather than a migration.

For engineering teams: Findings will narrow, not expand. If you were relying on max_return_statements through the default gate, add it explicitly to your configuration to preserve prior behavior. Existing explicit rules and IDs continue to work, so the upgrade path is straightforward; expect fewer suppressions and less reviewer debate over control-flow style.