README

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

Requirements

PHP 8.2+
Laravel 11 or 12

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

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

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

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

Queue Support

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

Importing an Uploaded File

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

Progress Tracking

$result = CsvImporter::make('/path/to/users.csv')
    ->using(UserImportHandler::class)
    ->chunkSize(500)
    ->onChunkComplete(function (int $chunkIndex, int $processedRows, int $successCount, int $errorCount) {
        echo "Chunk {$chunkIndex}: {$processedRows} rows, {$successCount} ok, {$errorCount} failed\n";
    })
    ->import();

Column Transforms

Apply transformations to mapped columns before validation:

$result = CsvImporter::make('/path/to/users.csv')
    ->using(UserImportHandler::class)
    ->transformColumn('email', fn (string $value) => strtolower($value))
    ->transformColumn('first_name', fn (string $value) => trim($value))
    ->import();

Changing the Delimiter

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

API

CsvImporter (Fluent Builder)

Method	Description
`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
`->onChunkComplete(callable $callback)`	Register a per-chunk progress callback
`->transformColumn(string $column, callable $transformer)`	Register a pre-validation column transformer
`->import()`	Run import synchronously
`->dryRun()`	Validate all rows without persisting
`->importQueued()`	Dispatch import as a background job

ImportHandler Interface

Method	Description
`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

Property / Method	Type	Description
`$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

Event	Payload
`ImportStarted`	`$path`, `$totalRows`, `$isDryRun`
`ImportChunkProcessed`	`$path`, `$chunkIndex`, `$rowsInChunk`, `$successCount`, `$errorCount`, `$skippedCount`
`ImportCompleted`	`$path`, `$result` (ImportResult), `$isDryRun`

Development

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

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT

philiprehberger / laravel-csv-import

Maintainers

Package info

Fund package maintenance!

Statistics

Security