Attributes Laravel Package

Product Decisions This Supports

• Technical-debt vs. feature trade-off: Informs whether to spend sprint capacity on code-quality infrastructure (static analysis coverage, CI gates, annotation hygiene) versus user-facing work. This package is squarely a "quality infrastructure" line item — its ROI is measured in defect escape rate, review latency, and refactor confidence, not in shipped features.
• Build vs. buy for an annotation vocabulary: Teams often hand-roll @pure, @immutable, @deprecated phpdoc tags or internal attribute classes. This package is a candidate "buy" (MIT, zero cost, tiny surface) to avoid maintaining a bespoke vocabulary that no analyzer understands.
• Standardization / interoperability decisions: If your stack runs more than one analyzer or refactoring tool (PHPStan, Psalm, Rector, PHP CS Fixer), a shared attribute set is a decision about whether intent should be expressed once and consumed everywhere, rather than re-encoded per tool.
• Public API and deprecation policy: Attributes are a machine-readable contract. They let you mark symbols as deprecated, pure, or immutable in a way that surfaces in IDE and CI output — directly shaping how you communicate breaking changes to library consumers or downstream teams.
• Domain invariant encoding: Expressing things like "this value object is immutable" or "this function is side-effect free" as attributes turns architectural rules into checkable constraints, which supports decisions about where to enforce invariants (types vs. tests vs. static analysis).
• Roadmap input for platform/DX work: Feeds the backlog for CI pipelines, quality gates, and onboarding docs — useful signal for whether static analysis maturity is a bottleneck or a nice-to-have.

When to Consider This Package

Consider it when:

• You are on PHP 8.1+ and already run PHPStan or Psalm at a meaningful level. Static-analysis attributes only pay off once an analyzer is actually consuming them.
• You want annotations that are survive-refactor safe — real attributes on real symbols are checked and greppable, unlike free-text phpdoc that silently rots.
• You maintain a shared library or internal platform package and want consumers' analyzers to read your intent (purity, immutability, deprecation) without reading your docs.
• You are standardizing across tools and want one vocabulary instead of three dialects.
• You want a low-commitment pilot: MIT, no runtime dependency, trivial to remove.

Look elsewhere or defer when:

• Your analyzer already ships equivalent attributes or first-class phpdoc support for the semantics you need. Duplicating the vocabulary adds a dependency for no new signal.
• You don't yet run static analysis. Solve adoption first; this package is an optimization on top of a practice you haven't established.
• You need commercial support, an SLA, or a stable long-term API guarantee. At 94 stars and a middling health score (~0.47), this reads as a single-maintainer, early-stage project — treat it as an experiment, not a foundation.
• Your team is small or pre-product-market-fit and developer-experience tooling is not the current bottleneck. The integration and onboarding cost outweighs the benefit.
• You are on older PHP or a framework version whose tooling can't consume attributes.

How to Pitch It (Stakeholders)

To executives: This is a near-zero-cost, low-risk hygiene investment. It converts architectural intent — "this is immutable," "this function is side-effect free," "this API is deprecated" — from tribal knowledge and stale comments into machine-enforced contracts. The payoff is fewer regressions reaching production, faster code review, and safer refactors, all with no license cost and no runtime footprint. Frame it as an experiment behind a time-boxed spike, given the project's early maturity, with a clear kill criterion if adoption doesn't stick.

To engineering: It gives us one shared, tool-readable vocabulary instead of per-tool phpdoc dialects that drift out of sync. Adoption is incremental and reversible — no runtime dependency, MIT licensed, and attributes degrade gracefully to no-ops if a tool doesn't understand them. Start by annotating one high-traffic domain module and measuring whether analyzer findings and review comments actually improve before rolling out further.

Honest caveat to include: 94 stars and a ~0.47 health score mean this is a bet on an emerging convention, not an established standard. Validate that your analyzers honor the attributes before committing, and keep an exit path (your own thin wrapper) so a change in maintenance doesn't strand your codebase.