Open source
Imports for Laravel
composer require roundly-consulting/imports-for-laravelOverview
CSV and XLSX imports into your Eloquent models. Describe each record type once in an importer class; your users download a template, upload a file, review the suggested column mapping and a preview in which every row has been checked, choose what happens to records that already exist, and import in the background — with undo. Nothing is saved until the user commits, and invalid rows never are. MIT-licensed, with its own streaming CSV and XLSX reader and writer — no third-party spreadsheet library — built on Laravel’s job batches plus Roundly’s options, crypto, enums and package-toolkit.
What you get
One importer per record type
Describe a row once — typed fields, labels in any locale, aliases, examples and rules, a natural key for duplicates and owner-scoped references to other records.
Templates people can fill in
CSV or XLSX in English or Slovak, with dropdowns for allowed values, a tip on each column and example rows that are skipped when left in.
Columns matched for you
Suggestions from headers, translated labels, aliases and close spellings, and mappings saved per owner, so the next file with the same headers maps itself.
A preview before anything is saved
Every row validated, errors named by row and cell, valid, invalid and duplicate counts, update diffs and an errors file — in the request or on the queue with progress.
Background commit with undo
Skip, update or create for existing records, idempotent chunks on Laravel job batches, cancel and resume, and an undo that keeps anything changed since.
Safe with untrusted files
Its own streaming CSV and XLSX reader and writer — no third-party spreadsheet library — ZIP-bomb and path-traversal defences, formula-safe CSV and owner-scoped access.
Facade, DI or actions
One Imports facade, an injectable manager or single-purpose actions — plus a recording fake, spreadsheet builders for tests and an opt-in JSON API.
Documentation
Use cases
Where the package fits — apps whose users bring data from spreadsheets or other tools, recurring updates, bulk file uploads and multi-tenant apps.
Installation
Install via Composer, publish the imports and options migrations, create job_batches, schedule sweep and prune, settle key types, write an importer.
Configuration
Every key of config/imports.php with its env variable and default — key types, storage, limits, reading, preview, commit, undo, queue, templates, API.
Importers
One class per record type extending Importer — every method and default, natural keys, create and update callbacks, rollback hooks, registration rules.
Fields and values
The nine field types and their coercion, labels, aliases, examples, rules and normalisers, references to other records and every cell error code.
Owners and permissions
The owner as a security boundary — Ownership rules, the OwnerScope contract, the teams-for-laravel recipe, authorize() on every step and audit recipes.
The Imports facade
Tour the Imports facade — for($owner), importers(), template(), read(), the session and batch handles, saved mappings, sweep and prune — with every method.
DI and actions
Skip the facade: inject ImportsManager or call a single-purpose action — every host-facing action with its execute() signature and facade path.
Reading files
The native streaming CSV and XLSX readers — format detection by content, encodings, delimiters, XLSX support, limits, rejections and Imports::read().
Templates and error reports
CSV and XLSX templates in English or Slovak with dropdowns and column tips, downloads, the template command, error reports and formula-safe output.
Column mapping
Mapping suggestions from headers, labels, aliases and fuzzy matches, map() by header or column, and saved mappings per owner that apply themselves.
Validated preview
Sessions and statuses, every row validated before the commit, counts, row results with cell errors, update diffs, queued validation and duplicate modes.
Commit and progress
The commit as one Laravel job batch of idempotent chunks — progress, summary, callback exceptions, cancel and resume, the lock and the ledger.
Undo
Undo within a window — unchanged created records are deleted or handed to your rollback hook, changed ones kept and listed, updates never reverted.
File batches
Many files or a ZIP, one record per file — FileImporter, allowed extensions, SHA-256 duplicate checks, ImportFile, ZIP-bomb and path-traversal defences.
JSON API
The opt-in JSON API — every route, its validated input and response, the owner resolver, upload throttling, errors and resources without class names.
Events
Every event the package dispatches after the commit — upload, mapping, preview, start, chunks, completion, failure, cancel, resume, undo, cleanup.
Exceptions
Every exception with its named constructors and HTTP status — rejections, mapping, state, authorization, undo window, definition and configuration errors.
Artisan commands
imports:sweep, prune, doctor, importers, template and install — what each does, the doctor’s checks, scheduling and the facade equivalents.
Testing
Imports::fake() records and passes through — every assertion pair, recorded operations, withoutRunning(), spreadsheet builders, factories, workbench.
Requirements
PHP 8.4+ with zip, xmlreader, xmlwriter and mbstring, Laravel 13, MySQL or PostgreSQL, a queue with job_batches and four Roundly packages.
Show your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.