Vec Laravel Package

Technical Evaluation

Architecture fit php-standard-library/vec is a narrow, framework-agnostic utility package: functions for creating and transforming sequential, 0-indexed arrays. It has no Laravel service provider, no facade, no config, and no Eloquent awareness — which is both its virtue (portable across Laravel, Lumen, Symfony, and plain PHP services) and its main architectural question: where does it sit relative to Illuminate\Support\Collection and native array_*?

The defensible architectural argument is a type-narrowing one. array is an overloaded type in PHP: list, map, sparse map, and tuple all share one signature. If Vec is used as a return type and parameter type in domain code (public function items(): Vec), it encodes the invariant "this is a list, keys 0..n-1" in the type system rather than in a comment, giving PHPStan/Psalm something to check. That is a real, reviewable benefit — but only if the package ships generics-annotated docblocks/stubs and immutable semantics. The README/description does not confirm generics support, immutability guarantees, or the actual method surface, so this must be verified before it is used as an architectural primitive.

Where it does not fit: Eloquent results, request payload validation, Blade rendering, and anywhere a keyed/associative structure is natural. Introducing Vec there creates a third array idiom in the codebase alongside native arrays and Collection.

Integration feasibility Technically trivial: a composer require, autoloading via PSR-4, zero bootstrap. The realistic friction is organizational, not technical — 1 star, 0 dependents, and a split-package release history that mirrors the monorepo (6.1.x–6.3.x all point at the main repository's release notes). That means version numbers are coupled to the whole standard library, changelogs are not package-specific, and breakage diagnosis routes through a repository you don't control.

Technical risk

• Abandonment / bus factor. Effectively a single-maintainer ecosystem with no observable downstream adoption. Mitigation: the surface area is small enough to fork or reimplement internally.
• Vocabulary collision. map, filter, reduce already exist on Collection; two implementations of the same verb in one codebase is a predictable source of review friction and inconsistent pipelines.
• Behavioral ambiguity on bad input. What happens when you pass an associative or sparse array? Exception, silent array_values reindex, or undefined behavior? This is the single most important thing to test, because silent reindexing corrupts data in ETL-style paths.
• Unbounded performance claims. No published benchmarks. For typical request payloads the overhead is likely irrelevant; for 100k+ element loops it should be measured, not assumed.
• Release metadata anomaly. The stated last release date is 2026-10-28; verify against Packagist before pinning.

Key questions

1. What is the declared PHP floor, and does it match the fleet (8.2/8.3/8.4)?
2. Is the API immutable (each op returns a new Vec) and does it ship static-analysis stubs for generics (Vec<int, User>)?
3. What is the exact behavior on non-list input — throw, coerce, or undefined?
4. Is Vec an interface or a final class? Can we type-hint it without binding to the concrete implementation?
5. How does an element get into and out of a Collection — is there a supported conversion path, or do we write one?
6. Who owns internal upgrades if the upstream repository goes quiet?
7. Is there a security policy / CVE process, or is this "read the diff" maintenance?

Integration Approach

Stack fit Position Vec as a domain-layer value type for ordered data, deliberately behind the framework boundary:

The rule to publish: Vec may be a return type and a parameter type in the domain namespace; it may not cross into App\Http or App\Models.

Migration path

1. Spike (2–3 days). Verify the API surface against the published docs, write 10–15 characterization tests covering empty input, associative input, nested lists, and large lists, and run a microbenchmark against Collection and native array_map. Output: go/no-go memo.
2. Boundary helper. Regardless of outcome, add a small internal adapter (e.g., App\Support\Lists) wrapping conversion in both directions. If the package is later dropped, only this file changes — the domain call sites keep working.
3. Single-module pilot. Pick one pipeline with heavy list manipulation (report generation, webhook fan-out, import normalization). No retrofitting of legacy modules.
4. Standardize or retire. If the pilot shows cleaner diffs and no performance regression, write an ADR and add a PHPStan/php-cs-fixer rule to prevent mixed Vec/Collection chains in the same expression. If not, remove the dependency; cost was one sprint.

Compatibility No framework coupling means Laravel 10/11/12 compatibility is a PHP-version question only. Coexistence with Collection requires explicit conversion at boundaries; keep those conversions in the adapter, not scattered. Standard PHPUnit/Pest works — add a single assertVecEquals assertion helper to TestCase so failures diff on toArray() rather than on object internals.

Sequencing Install → characterization tests + benchmark → adapter → one-module pilot → ADR → optional broader adoption for new code only. Do not gate any roadmap item on this decision; it is a code-quality choice, not a delivery dependency.

Operational Impact

Maintenance Low ongoing effort, non-trivial vendor risk. Pin to an exact version, not a caret range, while upstream is at 6.x with monorepo-coupled releases. The realistic hedge is that the package is small: a fork or a ~200-line internal replacement for the handful of functions actually used is a credible fallback and should be costed upfront (roughly 1–2 engineer-days). Assign a named internal owner; "the team" is not an owner.

Support Community-only, no commercial backing, no package-specific changelog. Escalation path is the upstream issue tracker in the monorepo. Budget zero expectation of upstream responsiveness for Laravel-specific needs — any facade or service-provider integration is ours to build, and there is no strong reason to build it.

Scaling For request-sized payloads (hundreds to low thousands of elements) the abstraction cost is immaterial next to I/O. For hot loops, queue workers processing large batches, or memory-sensitive jobs, do not adopt without a benchmark, and prefer generators/streaming over materializing a Vec of the whole dataset. Watch for object-per-list allocation in tight loops — a Vec wrapping an array per iteration is the classic regression pattern here.

Failure modes

• Silent reindexing of associative input → data corruption downstream. Highest-severity risk; assert on it in tests.
• Idiom fragmentation — half the codebase uses Collection, half uses Vec, and reviewers can't tell which is correct. Prevented only by the ADR plus a static-analysis rule.
• Package abandonment or a breaking 7.x shipped via monorepo release. Mitigated by pinning and the adapter boundary.
• False type safety — if generics are docblock-only, a Vec of the wrong element type fails at consumption, not construction. Treat Vec as documentation plus runtime list enforcement, not as a sound type system.
• Upgrade coupling — bumping this package may mean adopting an unrelated stdlib release train. Verify before each bump.

Ramp-up One to two days for engineers already fluent in Collection or JavaScript array methods; the mental model transfers almost entirely. The real onboarding artifact is a short internal cheat-sheet mapping collect()->map(...) to the Vec equivalent, plus the explicit "when not to use this" list. Team unfamiliarity with functional chaining would push this to a week and, at 1 star and 0 dependents, is probably not worth the spend.

TPM verdict Worth a bounded pilot, not a platform commitment. The opportunity signal (65) is offset by a low overall score (21.7) driven by adoption and maturity. Approve a time-boxed spike with a pre-agreed kill criterion; require an ADR before any second module adopts it; keep Collection as the default everywhere else.