Vec Laravel Package

Product Decisions This Supports

Build vs. buy for list-handling utilities. Today, every Laravel team eventually writes the same internal helpers: array_map wrappers, index re-checks, dedupe-and-reindex logic. php-standard-library/vec is a focused, MIT-licensed answer to that. The PM decision is whether to spend ~2–4 engineer-weeks building and maintaining a house ArrayUtils (plus its tests, docs, and onboarding burden) or adopt a package that already encodes those semantics. For a small, well-scoped surface area like this, buy is usually the right default unless the maturity signals below disqualify it.

Whether to invest in a functional-standard codebase. Vec is a signal-bearing package: adopting it is a statement that list transformations should be expressed as composable, immutable pipelines rather than imperative loops and mutation. That's a team-standards decision with a longer half-life than any single feature. If the roadmap includes data-heavy surfaces — imports, ETL, report builders, webhook/event sequencing, batch job fan-out — standardizing early is cheaper than retrofitting after three sprints of divergent patterns.

Feature scoping for order-sensitive domain logic. Places where ordering is a product requirement, not an incidental property: ranked search results, ordered steps in an approval/workflow state machine, paginated API payloads where cursor drift breaks the UI, CSV/Excel row ingestion, and any DTO or value object that carries a sequence. These are exactly where Vec's strict 0-indexed guarantee is worth something, because the failure mode it prevents (a keyed array silently becoming sparse after array_filter, then serializing as a JSON object instead of an array) is a real, customer-visible bug class.

Prioritizing bug classes on the roadmap. A meaningful share of "weird JSON" and "the front end crashed on an empty list" bugs trace back to PHP arrays being simultaneously lists and maps. Adopting a package that separates the two is a leverage decision: it doesn't fix one bug, it removes a category of them. That framing helps justify time spent on standards work that otherwise reads as unglamorous refactoring.

Ecosystem and hiring signal (weak but real). A codebase that uses recognized, composable abstractions is easier to staff and onboard into. This is a supporting argument, not a leading one — it should never be the deciding factor for a single utility package.

What it does not decide. It is not a Collection replacement and shouldn't be framed as one. Laravel's Collection remains the right tool for Eloquent results, associative data, lazy evaluation over large sets, and anything touching the framework. Vec earns its place only at the boundary where you genuinely need "an ordered list, and nothing else."

When to Consider This Package

Adopt when:

• Your domain has multiple order-critical flows — ranked results, step sequences, paginated payloads, import pipelines — where a sparse or re-keyed array is a genuine production defect.
• You're already inside the php-standard-library ecosystem (or evaluating it) and want Vec to compose with its sibling packages. Standalone adoption of one sub-package from a monorepo is the weakest case for it.
• You want a narrow, auditable dependency — MIT, no service provider required, no framework coupling, small enough that a security review is a coffee break rather than a sprint.
• You have a pilot candidate: one bounded module (an importer, a report generator, a webhook fan-out service) where you can measure readability and defect rate before committing a standard.
• Readability is the bottleneck, not throughput — you're optimizing for the next engineer reading the transform chain, not for shaving microseconds.

Look elsewhere (or wait) when:

• Maturity risk is unacceptable for the context. This is the blunt one: the package shows ~1 GitHub star, 0 dependents, and its release notes merely point at the parent monorepo. That is not evidence the code is bad — it is evidence there is no community backstop. If this code sits on a revenue-critical path, you are the maintainer of last resort. For a core-path dependency, prefer Collection, native arrays, or a 200-line internal helper you fully control.
• You need associative or keyed data. Vec explicitly excludes it. Reaching for it there means fighting the abstraction.
• The team is not fluent in functional style. Budget 1–2 weeks of ramp-up or don't start; a half-adopted abstraction is worse than none.
• You're on a hot path where per-element callable overhead matters. Benchmark first; if the numbers are close, decide on readability rather than performance.
• Your org caps dependency count and this would be the fifth package doing adjacent work.
• You need Laravel-native ergonomics — a facade, a service provider, an Eloquent bridge. None exist here; you'd be writing and owning that glue.

Decision rule I'd apply: treat Vec as an experiment, not an architecture. Pilot on one module with a named owner, a written rollback plan (it's toArray() away from native code, which makes rollback cheap — note that as a genuine strength), and a 6–8 week review checkpoint.

Due diligence before committing: confirm the package tracks a live parent release cadence, check PHP version support against your matrix, and grep the test suite. If any of those three come back thin, that's your answer.

How to Pitch It (Stakeholders)

For executives — the 30-second version: "PHP's array type is two things at once — an ordered list and a lookup table — and that ambiguity causes a recurring class of bugs that surface as broken JSON and crashed list views. This package separates them: it's a small, MIT-licensed, type-safe 'pure list' utility. Cost is roughly a sprint of one engineer's time to pilot in a contained area; upside is fewer defects in data-processing code and a consistent pattern for how we handle sequences. The dependency is tiny and removable in an afternoon, so the downside is bounded. The caveat: it's not widely adopted, so we pilot rather than standardize on day one."

For engineering leads — the practical case:

• It removes the "array_filter silently re-keyed this and now Laravel serialized it as an object" bug class.
• It gives list transforms one obvious shape: Vec::fromArray($rows)->map(...)->filter(...) instead of nested foreach with manual index bookkeeping.
• It stays out of Collection's lane, so it doesn't create a competing abstraction over Eloquent or associative data.
• Rollback is trivial — everything converts back with toArray(). That makes the pilot genuinely low-risk.
• Honest counterpoint we should say out loud in the room: low adoption means we own the edge cases. Pilot, measure, then decide.

For the product/design side:

• Ordering guarantees in API responses become something we can state in the contract, not just hope for — relevant for anything a client paginates, ranks, or renders as a sequence.
• Fewer "empty list rendered as {}" and "order changed between requests" tickets.

What I'd ask for: one module, one named owner, one sprint, and a checkpoint at 6–8 weeks with three numbers — defects in that module, review-cycle time on transforms, and developer sentiment. Then we either expand, hold, or revert. All three outcomes are cheap.