Laravel CSV Import

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