PHPackages                             philiprehberger/laravel-csv-import - 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. [Queues & Workers](/categories/queues)
4. /
5. philiprehberger/laravel-csv-import

ActiveLibrary[Queues & Workers](/categories/queues)

philiprehberger/laravel-csv-import
==================================

Chunked CSV import with row-level validation, error collection, dry-run mode, and queue support.

v1.0.2(1mo ago)15[1 PRs](https://github.com/philiprehberger/laravel-csv-import/pulls)MITPHPPHP ^8.2CI passing

Since Mar 9Pushed 1mo agoCompare

[ Source](https://github.com/philiprehberger/laravel-csv-import)[ Packagist](https://packagist.org/packages/philiprehberger/laravel-csv-import)[ Docs](https://github.com/philiprehberger/laravel-csv-import)[ RSS](/packages/philiprehberger-laravel-csv-import/feed)WikiDiscussions main Synced 1mo ago

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

Laravel CSV Import
==================

[](#laravel-csv-import)

[![Tests](https://github.com/philiprehberger/laravel-csv-import/actions/workflows/tests.yml/badge.svg)](https://github.com/philiprehberger/laravel-csv-import/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/2bfcf1489add36d70760442fd72054912e143c379b53af54349bf1216fcbc510/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068696c69707265686265726765722f6c61726176656c2d6373762d696d706f72742e737667)](https://packagist.org/packages/philiprehberger/laravel-csv-import)[![License](https://camo.githubusercontent.com/ac4d48191eac09552e3f21dcc7cf15276abc7af879c111df6e1756a484937c46/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7068696c69707265686265726765722f6c61726176656c2d6373762d696d706f7274)](LICENSE)

Chunked CSV import with row-level validation, error collection, dry-run mode, and queue support.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11 or 12

Installation
------------

[](#installation)

```
composer require philiprehberger/laravel-csv-import
```

The service provider is registered automatically via Laravel's package auto-discovery.

Optionally publish the config file:

```
php artisan vendor:publish --tag=csv-import-config
```

Usage
-----

[](#usage)

### 1. Create an Import Handler

[](#1-create-an-import-handler)

Implement `PhilipRehberger\CsvImport\Contracts\ImportHandler`:

```
namespace App\Imports;

use App\Models\User;
use PhilipRehberger\CsvImport\Contracts\ImportHandler;

class UserImportHandler implements ImportHandler
{
    public function rules(): array
    {
        return [
            'first_name' => ['required', 'string', 'max:255'],
            'last_name'  => ['required', 'string', 'max:255'],
            'email'      => ['required', 'email', 'max:255'],
        ];
    }

    public function map(array $row): array
    {
        return [
            'First Name' => 'first_name',
            'Last Name'  => 'last_name',
            'Email'      => 'email',
        ];
    }

    public function handle(array $row): void
    {
        User::create($row);
    }

    public function uniqueBy(): ?string
    {
        return 'email';
    }
}
```

### 2. Run the Import

[](#2-run-the-import)

```
use PhilipRehberger\CsvImport\CsvImporter;

$result = CsvImporter::make('/path/to/users.csv')
    ->using(UserImportHandler::class)
    ->chunkSize(500)
    ->import();

echo "Imported: {$result->successCount}";
echo "Errors:   {$result->errorCount}";

if ($result->hasErrors()) {
    foreach ($result->getErrors() as $error) {
        echo "Line {$error->lineNumber}: " . implode(', ', $error->errors->all());
    }
}
```

### Dry-Run Mode

[](#dry-run-mode)

```
$result = CsvImporter::make('/path/to/users.csv')
    ->using(UserImportHandler::class)
    ->dryRun();
```

### Queue Support

[](#queue-support)

```
CsvImporter::make('/path/to/users.csv')
    ->using(UserImportHandler::class)
    ->chunkSize(1000)
    ->importQueued();
```

### Importing an Uploaded File

[](#importing-an-uploaded-file)

```
$result = CsvImporter::fromUpload($request->file('csv'))
    ->using(UserImportHandler::class)
    ->import();
```

### Changing the Delimiter

[](#changing-the-delimiter)

```
CsvImporter::make($path)
    ->using(MyHandler::class)
    ->delimiter(';')
    ->import();
```

API
---

[](#api)

### CsvImporter (Fluent Builder)

[](#csvimporter-fluent-builder)

MethodDescription`CsvImporter::make(string $path)`Create an importer from a file path`CsvImporter::fromUpload(UploadedFile $file)`Create an importer from an uploaded file`->using(string $handlerClass)`Set the import handler class`->chunkSize(int $size)`Set chunk size (default: config value)`->delimiter(string $delimiter)`Set CSV delimiter`->enclosure(string $enclosure)`Set CSV enclosure character`->import()`Run import synchronously`->dryRun()`Validate all rows without persisting`->importQueued()`Dispatch import as a background job### ImportHandler Interface

[](#importhandler-interface)

MethodDescription`rules(): array`Laravel validation rules for each mapped row`map(array $row): array`Map CSV headers to attribute names`handle(array $row): void`Persist a single validated row`uniqueBy(): ?string`Attribute name for duplicate detection, or `null` to disable### ImportResult

[](#importresult)

Property / MethodTypeDescription`$totalRows``int`Total data rows in the file`$successCount``int`Rows successfully handled`$errorCount``int`Rows that failed validation or handling`$skippedCount``int`Rows skipped due to duplicate detection`hasErrors()``bool`True if errorCount > 0`getErrors()``RowError[]`All collected row errors`toArray()``array`Serialisable summary### Events

[](#events)

EventPayload`ImportStarted``$path`, `$totalRows`, `$isDryRun``ImportChunkProcessed``$path`, `$chunkIndex`, `$rowsInChunk`, `$successCount`, `$errorCount`, `$skippedCount``ImportCompleted``$path`, `$result` (ImportResult), `$isDryRun`Development
-----------

[](#development)

```
composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse
```

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance89

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

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 ~4 days

Total

3

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfd7d24cbbf32400fa13ce0bbe7a31edd2d66a6d4488eafdb3d64c5337bf0435?d=identicon)[philiprehberger](/maintainers/philiprehberger)

---

Top Contributors

[![philiprehberger](https://avatars.githubusercontent.com/u/8218077?v=4)](https://github.com/philiprehberger "philiprehberger (12 commits)")

---

Tags

laravelvalidationcsvqueueimport

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/philiprehberger-laravel-csv-import/health.svg)

```
[![Health](https://phpackages.com/badges/philiprehberger-laravel-csv-import/health.svg)](https://phpackages.com/packages/philiprehberger-laravel-csv-import)
```

###  Alternatives

[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k84.2M225](/packages/laravel-horizon)[axlon/laravel-postal-code-validation

Worldwide postal code validation for Laravel and Lumen

3853.3M1](/packages/axlon-laravel-postal-code-validation)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

3786.5k](/packages/harris21-laravel-fuse)[palpalani/laravel-sqs-queue-json-reader

Custom SQS queue reader for Laravel

26109.8k](/packages/palpalani-laravel-sqs-queue-json-reader)[shaffe/laravel-mail-log-channel

A package to support logging via email in Laravel

1286.2k](/packages/shaffe-laravel-mail-log-channel)

PHPackages © 2026

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