[Idea] Validator::collection(), first-class bulk validation with per-item error collection

[Amirhf1]

Problem

Validating a collection of items - CSV imports, bulk API payloads, queue-based processors - has no first-class solution in Laravel. Today every developer writes the same loop:

$errors = [];
foreach ($rows as $i => $row) {
    $validator = Validator::make($row, $rules);
    if ($validator->fails()) {
        $errors[$i] = $validator->errors();
    }
}

This pattern is repeated in every import job, every bulk endpoint, every test fixture loader. There's no standard structure for the error collection, no lazy support, and no unified exception.

The existing Rule::forEach() helps with nested array validation but doesn't solve the "validate N independent items, collect all errors" use case.

Proposed API

$result = Validator::collection($rows, [
    'email' => ['required', 'email'],
    'age'   => ['required', 'integer', 'min:0'],
]);

if ($result->hasErrors()) {
    // Collection<int, MessageBag> keyed by row index
    $result->errors();

    // Only the rows that failed
    $result->failed();

    // Throw a single exception carrying all per-row errors
    $result->throwIfFailed();
}

// Only the rows that passed - safe to persist
$result->passed()->each(fn ($row) => User::create($row));

With lazy support:

// Validates lazily - cursor is never fully materialized
$result = Validator::collection(User::cursor(), $rules);

Implementation Sketch

• Factory::collection(iterable $items, array $rules, ...) - iterates items, creates a Validator per row via the existing factory, collects errors into a ValidatedCollection
• ValidatedCollection - thin value-object: hasErrors(), errors(), passed(), failed(), throwIfFailed()
• BatchValidationException extends ValidationException - carries Collection<int, MessageBag> indexed by row position
• If $items is a LazyCollection, validation runs lazily; errors materialize only on terminal calls
• after() callbacks: explicitly not supported per-row (documented)

Estimated diff: ~160 lines across 3–4 files. I'm happy to implement if the API direction makes sense.

Open Design Questions

1. Should passed() require an explicit opt-in (e.g. ->unsafe()) when errors exist, to prevent silent data loss?
2. Should BatchValidationException extend ValidationException or stand alone?
3. Is Validator::collection() the right entry point, or Validator::make()->validateCollection($items)?

Happy to hear if there's a simpler shape you'd prefer before I start writing code.

[shaedrich]

You can do this today already without foreach:

$validator = Validator::make(['rows' => $rows], [
    'rows.*.email' => ['required', 'email'],
    'rows.*.age'   => ['required', 'integer', 'min:0'],
]);
if ($validator->fails()) {
    $errors = $validator->errors();
}

[Amirhf1]

Hey @shaedrich, great point, and you're right that rows.* works well for simple cases! That's actually what I use too for regular form validation.

But the use case I'm targeting is a bit different. A few things that rows.* doesn't cover cleanly:

1. Per-item error access is awkward
With rows.* you get flat dot-notation keys like rows.0.email. When you want to respond with "row 5 had these errors", you have to manually parse and group those keys. ValidatedCollection gives you a MessageBag per row index out of the box.

2. No way to get only the passing rows
There's no clean way to say "give me only the rows that passed so I can persist them". You'd have to loop again and filter manually. $result->passed() makes partial saves a one-liner.

3. LazyCollection / cursor support
The rows.* approach requires the full array in memory upfront. If you're validating a User::cursor() or a chunked CSV stream, that's not viable. Lazy validation is one of the main motivations here.

So yeah rows.* is totally fine and I'd keep using it for nested form payloads. This proposal is more about the "validate 50k rows from a CSV and collect errors per row without blowing up memory" scenario. Two different tools for two different jobs! :))

[shaedrich]

Correct, this isn't ideal

[Amirhf1]

@taylorotwell / @driesvints before I open a PR, could you confirm the API direction makes sense for core?

The main use case rows.* doesn't cover:
LazyCollection / cursor support - no full array in memory Per-row MessageBag no manual key parsing passed() for partial saves no second loop needed

[shaedrich]

Taylor never replies to discussions