Args Laravel Package

Technical Evaluation

What we are actually evaluating. johnbillion/args is a small, single-purpose PHP library that makes array-shaped arguments ("args arrays") bearable: a base Args class with defaults, a merge() helper, supports() checks, and a set of typed subclasses that mirror well-known WordPress argument arrays (WP_Query, WP_Term_Query, WP_REST_Server). The value is documentation-as-code: consumers get autocompletion and PHPStan-visible array shapes instead of hand-rolled wp_parse_args() calls.

Architecture fit — the core finding. This is a WordPress-shaped library, not a Laravel-shaped one. Roughly 80% of its surface area wraps WordPress APIs that do not exist in a Laravel codebase. In a pure Laravel context, only the generic base class is portable, and its behavior (defaults, merge, key validation) is a few dozen lines that Laravel already covers with Illuminate\Support\Arr, config merging, PHP 8 named arguments, and readonly DTOs. The package is technically installable anywhere and architecturally justified almost nowhere in a Laravel-only stack. Fit becomes strong only in a hybrid context: a Laravel app fronting a headless WordPress, a WP plugin maintained alongside a Laravel product, or a migration off WordPress where shared arg contracts reduce churn.

Integration feasibility. Installation is trivial — Composer, no service provider, no config file, no framework coupling, no bootstrapping. That low friction is a trap: "easy to install" is not "worth installing." Real effort sits in the adoption decision and convention-setting, not the mechanics.

Technical risk.

Key questions for the requester.

1. Is any WordPress code in scope, now or within 12 months? If no, this is a decline.
2. What problem is being solved — typed args, or defaults/merging? If the latter, Arr and DTOs already cover it.
3. Has legal cleared GPL-2.0 for the intended distribution model?
4. What is the existing convention for array-shaped input (DTOs, form requests, value objects)? Introducing a second pattern has a cost beyond the dependency itself.
5. Who owns the fork if upstream stalls?

Integration Approach

Stack fit. Green-light for WordPress-adjacent modules only. For pure Laravel services, the recommendation is to decline and standardize on readonly DTOs plus Laravel's validator — same developer ergonomics, no copyleft, no external maintainer.

Compatibility checks before adoption. Resolve the package's PHP constraint against our Laravel version matrix (Laravel 10 → PHP 8.1, 11/12 → PHP 8.2+). Confirm PHPStan compatibility with our Larastan baseline — the library is written with generic array shapes, which is a genuine plus for static analysis but can lengthen analysis runs on deep shapes. Verify PHPUnit support if we intend to unit-test consumers.

Migration path — adapter-first, not direct. Do not reference the vendor namespace from application code. Wrap it:

• One project-owned App\Support\ArgObject extending or composing the base class.
• Call sites depend on our class, never on Args\*.
• If upstream stalls or legal reverses, we replace one file.

This containment is the single highest-leverage design decision and costs roughly a day.

Sequencing.

1. Legal gate on GPL-2.0 for the target distribution model — blocking, no engineering before this clears.
2. Spike (2–3 days) in one WP-facing module: convert one args array, measure static-analysis impact and developer reaction.
3. Convention doc — when to use ArgObject vs. a DTO vs. plain arrays.
4. Adapter layer committed, with the vendor pinned to an exact version.
5. Go/no-go review at the end of the spike. A kill decision here is a success, not a failure — expected cost of the evaluation is under one engineer-week.

Operational Impact

Maintenance. Low-velocity upstream is the defining operational fact. Pin an exact version (no ^), commit composer.lock, and add the package to the quarterly dependency review with an explicit "is upstream alive?" check. Budget a few hours per PHP minor upgrade to validate.

Support. Community-only, GitHub issues, no SLA. The GPL license is the mitigation: we can fork and self-maintain. Record that escape hatch in the runbook so it is a planned option rather than an emergency improvisation.

Scaling. Negligible runtime cost — pure in-process array shaping, no I/O, no caching, no state. The only scaling concern is static analysis: generic array shapes can add meaningful seconds to PHPStan in CI as adoption widens. Watch CI duration after rollout.

Failure modes to instrument.

• Upstream abandonment — breaks on a future PHP release; detected via CI, mitigated by the fork option.
• License contamination — discovered late in a product that ships binaries or SDKs; this is a legal, not engineering, failure and is why the gate is step one.
• Pattern sprawl — some teams use ArgObject, others use DTOs, others use raw arrays; the codebase becomes inconsistent and onboarding slows. Mitigated only by the convention doc and review enforcement.
• False confidence — developers assume the typed arrays are enforced at runtime, then debug failures deep in the WordPress call. Document that these are static-analysis aids.
• Scope creep into Laravel-native code — the most likely failure in practice. A developer discovers the package and applies it to HTTP client options or query builder args, where it adds a dependency for zero net value.

Ramp-up. Individual ramp-up is roughly half a day — the API is small and readable. The real cost is pattern ramp-up: every engineer needs to know when this applies and when it does not. That is a documentation and code-review investment, not a training one, and it should be scoped explicitly rather than assumed.

TPM recommendation. Treat the 17/100 score as directionally correct for a Laravel-primary stack. Approve a timeboxed spike only if WordPress code is confirmed in scope and legal clears GPL; otherwise decline and redirect the effort toward standardizing DTOs, which delivers the same typed-args benefit with no license, maintenance, or consistency exposure.