PHPackages                             aymane-asserrar/livewire-excel-validator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF &amp; Document Generation](/categories/documents)
4. /
5. aymane-asserrar/livewire-excel-validator

ActiveLibrary[PDF &amp; Document Generation](/categories/documents)

aymane-asserrar/livewire-excel-validator
========================================

Validate Excel uploads row-by-row. Returns a ValidationResult with per-cell errors, red-highlighted annotated file, hover comments, and a summary sheet.

v2.0.0(6d ago)06↓100%MITPHPPHP ^8.1

Since Mar 17Pushed 6d agoCompare

[ Source](https://github.com/AymaneAsserrar/LiveWireExcelValidator)[ Packagist](https://packagist.org/packages/aymane-asserrar/livewire-excel-validator)[ RSS](/packages/aymane-asserrar-livewire-excel-validator/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (4)Used By (0)

Laravel Excel Validator
=======================

[](#laravel-excel-validator)

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
------------

[](#installation)

```
composer require aymane-asserrar/livewire-excel-validator
```

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

---

Basic Usage
-----------

[](#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
--------------------

[](#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
---------------

[](#available-rules)

RuleDescription`required`Cell must not be empty`string`Must be non-numeric text`numeric`Must be a numeric value`integer`Must be a whole number`email`Must be a valid email address`url`Must be a valid URL`date`Must be a parseable date (or an Excel serial date)`boolean`Must be `true`/`false`, `yes`/`no`, or `1`/`0``min:{n}`Numeric value must be ≥ n`max:{n}`Numeric value must be ≤ n`min_length:{n}`String length must be ≥ n characters`max_length:{n}`String length must be ≤ n characters`in:{a,b,c}`Value must be one of the listed options`not_in:{a,b,c}`Value must not be any of the listed options`regex:{pattern}`Value must match the regex (no delimiters — e.g. `regex:^\d{4}$`)`unique`Value must be unique within that column across all rowsRules 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
-----------------------------

[](#the-validationresult-object)

Property / MethodDescription`$result->hasErrors()``true` if any row failed validation`$result->errorCount()`Total number of individual cell errors`$result->errors`Raw errors array: `[rowIndex => [colKey => [messages]]]``$result->flatErrors()`Flat array: `[['row' => n, 'column' => 'email', 'messages' => [...]]]``$result->rows`Parsed rows as `array`, keyed by lowercased header name`$result->annotatedPath`Absolute path to the annotated `.xlsx` file (null if no errors)`$result->filename`Original filename`$result->download()`Stream the annotated file as a download response **(Laravel only)**---

Serving the Annotated Error File
--------------------------------

[](#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
----------------------------------

[](#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
-----------------

[](#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
-------

[](#license)

MIT — [Aymane Asserrar](https://github.com/AymaneAsserrar)

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance98

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

6d ago

Major Versions

v1.1.0 → v2.0.02026-03-18

### Community

Maintainers

![](https://www.gravatar.com/avatar/9534b8d477efbe6bebd6d907cf3ccb036453a491b7753d3c827a25249c5824be?d=identicon)[AymaneAsserrar](/maintainers/AymaneAsserrar)

---

Top Contributors

[![AymaneAsserrar](https://avatars.githubusercontent.com/u/181023835?v=4)](https://github.com/AymaneAsserrar "AymaneAsserrar (6 commits)")

---

Tags

laravelvalidationexcelxlsximportphpspreadsheetlivewire

### Embed Badge

![Health badge](/badges/aymane-asserrar-livewire-excel-validator/health.svg)

```
[![Health](https://phpackages.com/badges/aymane-asserrar-livewire-excel-validator/health.svg)](https://phpackages.com/packages/aymane-asserrar-livewire-excel-validator)
```

###  Alternatives

[maatwebsite/excel

Supercharged Excel exports and imports in Laravel

12.7k140.5M631](/packages/maatwebsite-excel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
