Product Decisions This Supports
- Build vs. buy vs. inline (the honest framing): This is a ~100-line value object that wraps an associative array behind
get/set/has/all, ArrayAccess, and iteration. At 5 stars, zero dependents, and a last release in July 2021, it is not a strategic dependency. The real decision is "adopt the convention, or spend an afternoon writing the class ourselves" — treating it as a convention decision rather than an infrastructure one removes most of the risk from the table.
- Internal API and contract-boundary decisions: Anywhere the product passes structured payloads between layers — webhook payloads, job/command arguments, config bundles, third-party API responses — is a candidate. A named container turns anonymous arrays into a self-documenting type and gives you a single seam where a partner's shape change is absorbed rather than rippling through call sites. That is a real roadmap enabler when a vendor revises its contract.
- Maintainability and onboarding investment: The business case is indirect and measured in defect rate and ramp time on affected modules, not in user-facing capability. It makes handler signatures self-documenting and refactors safer. Sell it as a code-quality line item, not a platform initiative.
- Framework/runtime roadmap alignment: v2.0.0 is a platform-boundary release — PHP 8.0 floor, tests moved to Pest — with no stated runtime feature change. If a PHP modernization is already on the roadmap, this rides along for free. If it isn't, this release gives you no reason to move.
- Dependency-portfolio hygiene: Single maintainer, 2021 cadence, no published support or security policy. Add it only to non-critical paths (or vendor it), and record an owner plus a review date regardless of the decision.
- Good fits: domain value objects (money, address, pagination params), validated request/config bundles, and test fixtures where an explicit iterable container beats a bare array. Poor fits: anything needing validation rules, schema enforcement, typed/nested collections, immutability guarantees, or serialization promises — this is a bag, not a DTO library, and that mismatch is the most common failed adoption.
When to Consider This Package
- Consider it when the team is already on PHP 8.0+ (Laravel 9+) and wants a conventional named container instead of raw arrays at a handful of internal seams — and when engineering is comfortable that the class is small enough to fork or copy if the maintainer stops.
- Consider it for existing consumers: the
^2.0 bump is a constraint change plus a green test run. Retain what fits; there is no feature incentive to churn.
- Consider it as a coding-standard reference even if you never install it. "Getters +
ArrayAccess + IteratorAggregate" is a reasonable internal convention to standardize on.
- Look elsewhere if the actual requirement is validation, schema enforcement, typed/nested structures, immutability, or serialization guarantees. Reach for a DTO/mapper approach instead.
- Look elsewhere if the package would sit on a critical path and your organization requires an active support policy, a security-patch commitment, or a bus factor above one. None of those are stated here.
- Look elsewhere or vendor for PHP 7.4 shops: adoption is blocked outright, and the real work item is a runtime migration independently justified by 7.4 being end-of-life. Sequence the PHP bump as a platform project, then bump the constraint in the same commit.
- Do not adopt on the strength of v2.0.0 alone. A two-line changelog for a major version is either a genuinely narrow break or an incomplete record — read the diff before committing, and verify the
require block resolves against your current Laravel rather than trusting the stated PHP floor.
- Do not treat the Pest swap as an adoption criterion. It is contributor- and CI-facing, not runtime behavior. Relevant only if you contribute upstream or mirror the test setup.
- Watch for the mutation footgun: objects wrapping arrays share by reference, so passing a bag and mutating it in one place silently changes it everywhere. Acceptable as a design choice; not acceptable as a surprise.
How to Pitch It (Stakeholders)
Executive summary: A small, low-ceremony PHP utility that replaces loose arrays with a named container. It delivers no customer-facing capability and no measurable revenue lever. The case is modest and indirect: cleaner internal contracts, slightly lower defect and onboarding cost in the modules that use it, and a one-file seam where payload shapes can change without touching call sites. The decision is low-stakes in both directions — a small refactor with a small payoff. The one thing to flag upward is dependency posture: one maintainer, zero known dependents, last release mid-2021, no support policy. Fund it as a maintainability improvement, not a platform investment.
Engineering summary: v2.0.0 drops PHP below 8.0 and moves the package's own tests to Pest; no runtime API changes are stated, but a two-line changelog for a major version means review the diff before it goes near anything important. Mechanically it is a ^2.0 constraint bump plus a full test run for anyone on PHP 8.0+; it is blocked entirely below that. Pin the major line — do not float a package this quiet. Verify empirically that it resolves against your actual Laravel versions with composer update --dry-run, since its effective reach is bounded by its illuminate/* constraint, not its PHP floor. Wrap it behind a thin internal adapter so call sites depend on your interface, not the vendor class — that single move converts a future major version, or plain abandonment, into a one-file change. Confirm Pest stays in require-dev and that coverage didn't silently regress. Keep it off critical paths and record an owner and review date on the dependency watchlist.
Product recommendation: Adopt selectively and cheaply. Use it in internal, non-critical seams where the team wants a named container instead of arrays; budget it as an afternoon-scale maintainability improvement; and be explicit that a one-day in-house equivalent is a legitimate outcome, not a failure to adopt. If the roadmap already includes a PHP 8.0+ migration, fold this in for free — if not, defer and pin the previous major. Either way, set the expectation that replacing it later is an afternoon of work, not a project.