README

Validate Excel file uploads row-by-row against configurable column rules. If errors are found, returns an annotated .xlsx file with red cell highlights and hover comments. If clean, returns the parsed rows ready to insert into your database.

Installation

composer require aymane-asserrar/livewire-excel-validator

Requires PHP 8.1+ and Laravel 10/11/12 (auto-discovered via service provider).

Basic Usage

use AymaneAsserrar\ExcelValidator\ExcelValidator;

$result = ExcelValidator::validate(
    file:      $request->file('import'),  // UploadedFile or a file path string
    rules:     [
        'name'   => ['required', 'string', 'max_length:100'],
        'email'  => ['required', 'email', 'unique'],
        'age'    => ['numeric', 'min:18', 'max:120'],
        'role'   => ['required', 'in:admin,editor,viewer'],
        'status' => ['required', 'in:active,inactive'],
    ],
    headerRow: 1,  // optional, defaults to 1
);

if ($result->hasErrors()) {
    // Save the annotated file path in the session and redirect
    session(['annotated_path' => $result->annotatedPath]);
    return back()->with('error', $result->errorCount() . ' error(s) found.');
}

// No errors — use $result->rows to insert into the database
foreach ($result->rows as $row) {
    User::create([
        'name'  => $row['name'],
        'email' => $row['email'],
    ]);
}

Custom Column Labels

Add _label:My Label to any rule list to override how the column name appears in error messages:

'email' => ['required', 'email', 'unique', '_label:Email Address'],

Without _label, the column key is title-cased automatically (email_address → Email address).

Available Rules

Rules are evaluated in order and stop at the first failure per cell.

Note (v2.0.0): Rows that are entirely blank are no longer skipped when any column carries a required rule. Previously, a fully empty row would be silently ignored and the required error would never fire.

The ValidationResult Object

Serving the Annotated Error File

The annotated file is written to sys_get_temp_dir(). The recommended pattern is to store the path in the session and serve it via a dedicated route:

// In your controller / Livewire component
session(['excel_errors_path' => $result->annotatedPath]);

// In routes/web.php
Route::get('/excel/download-errors', function () {
    $path = session('excel_errors_path');
    abort_unless($path && file_exists($path), 404);
    session()->forget('excel_errors_path');
    return response()->download($path, 'validation_errors.xlsx')->deleteFileAfterSend(true);
})->name('excel.download-errors');

Or use the built-in helper directly in a controller:

return $result->download('my_errors.xlsx');

What the Annotated File Looks Like

• Red background + red text on every invalid cell
• Hover comment on each red cell listing the exact rule(s) that failed
• Amber header on every column that contains at least one error

Note: The "Validation Errors" summary sheet (Row / Column / Value / Error) was removed in v1.1.0. Use $result->flatErrors() to access error details programmatically.

Non-Laravel Usage

The validator has no hard Laravel dependency. Pass a file path string instead of an UploadedFile:

$result = ExcelValidator::validate('/tmp/upload.xlsx', $rules);

ValidationResult::download() will throw a RuntimeException if called outside a Laravel context — use $result->annotatedPath directly and serve the file yourself.

License

MIT — Aymane Asserrar