Arch App Services Laravel Package

Product Decisions This Supports

• Codifying architecture instead of documenting it. This package turns conventions (single-purpose Action classes, Data Validators, Result-based error handling, transaction boundaries) into PHPStan rules that fail CI. That makes "we follow the Action pattern" a build-time gate rather than a wiki page — a build-vs-buy decision favoring buy for teams that would otherwise spend a quarter writing and maintaining bespoke static-analysis rules.
• Layer-boundary policy. The 0.5.1 split of NoHttpExceptionsInActionsAndDataValidatorsRule into NoHttpExceptionsInActionsRule and NoHttpExceptionsInDataValidatorsRule is a product statement: HTTP concerns are banned in both the action layer and the validation layer, and each can be scoped independently via actionNamespaces / dataValidatorNamespaces. Teams can now adopt one rule without the other — useful for incremental rollouts where validators are already cleaned up but actions are not.
• Roadmap input for error-handling strategy. The bundled documentation on the Result pattern and transactions tells us the package's opinionated stance: domain failures are values, not exceptions, and transaction scope is an architectural concern. That directly informs whether our roadmap adopts a Result-typed service layer or stays with exception-driven controllers.
• Onboarding and code-review load. Enforced rules reduce reviewer nitpicking and make unfamiliar codebases predictable — a measurable lever on time-to-first-PR for new hires and on review latency for senior engineers.
• Use cases that fit: modular monoliths and Laravel APIs with a growing domain layer, teams already running PHPStan at a meaningful level, and organizations standardizing several Laravel services on one internal architecture.

When to Consider This Package

Consider adoption when:

• You are on Laravel and already run PHPStan in CI — these rules are worthless as a local-only convenience and only pay off as a merge gate.
• You have (or want) an Action/service-class architecture with thin controllers, and you are willing to enforce it mechanically.
• You have multiple teams or services where architectural drift is a real cost, and a shared, versioned rule set beats a copied internal package.
• You can absorb pre-1.0 churn. 0.5.1 is a breaking change published on a patch-level version, removing NoHttpExceptionsInActionsAndDataValidatorsRule outright. Budget a pin-and-upgrade discipline (exact versions, a scheduled upgrade ticket per release) rather than floating constraints.
• You are comfortable with single-maintainer dependency risk (all 0.5.1 changes are authored by one contributor). Have an exit plan: the rules are thin PHPStan extensions you could vendor into your own phpstan/ namespace if the package stalls.

Look elsewhere when:

• You need framework-agnostic architecture rules, or you are not on Laravel.
• Your team is small enough that conventions hold without static enforcement, and adding a dependency plus CI time is net negative.
• You require stable public API guarantees (post-1.0 semver, LTS-style support windows) before taking a dependency into a platform shared by many services.
• You need the rules to cover controller/HTTP-layer exceptions — the identifiers are unchanged but the rule set is explicitly scoped to Actions and Data Validators, so controller-level policy is still yours to own.

Migration note for existing adopters: replace the single service registration with the two new ones. ignoreErrors entries keyed on the existing identifiers keep working, so suppression baselines do not need rewriting — the migration cost is confined to the Neon/PHPStan config file.

How to Pitch It (Stakeholders)

To executives: We are evaluating a small Laravel package that converts our architectural standards into automated CI checks. The business case is defect prevention and onboarding speed: instead of relying on reviewers to catch layering violations, the build fails. Cost is low (a dev dependency), risk is bounded (pin the version, rules are replaceable in-house), and the current release is pre-1.0 — so the recommendation is a scoped pilot on one service, not a platform-wide mandate.

To engineering: This gives us enforced Actions/Data Validators separation, Result-based error handling, and explicit transaction boundaries, all caught by PHPStan rather than in review. 0.5.1 splits the old combined rule into two independently scoped rules (NoHttpExceptionsInActionsRule, NoHttpExceptionsInDataValidatorsRule) configured by namespace — so we can roll out per layer. It is a breaking change on a patch version: pin exactly, and expect to touch phpstan.neon on upgrades. Existing ignoreErrors identifiers still apply. Recommend a one-service pilot with the rules at error level, and only then a shared config package for the rest of the estate.