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)

ImportHandler Interface

ImportResult

Events

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