---
title: "Imports for Laravel — docs | Roundly"
description: "Developer docs for Imports for Laravel: CSV and XLSX imports into Eloquent with templates, column mapping, validated preview, background batches and undo."
url: https://roundly-consulting.com/open-source/docs/imports-for-laravel
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

Open source

# Imports for Laravel

Install

`composer require roundly-consulting/imports-for-laravel`

Requires: PHP ^8.4 · Laravel ^13.0

[GitHub](https://github.com/roundly-consulting/imports-for-laravel) [Packagist](https://packagist.org/packages/roundly-consulting/imports-for-laravel) [Donate (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Patreon](https://www.patreon.com/cw/roundly)

## Overview

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/use-cases.md)

Where the package fits — apps whose users bring data from spreadsheets or other tools, recurring updates, bulk file uploads and multi-tenant apps.

#### [Installation](https://roundly-consulting.com/open-source/docs/imports-for-laravel/installation.md)

Install via Composer, publish the imports and options migrations, create job\_batches, schedule sweep and prune, settle key types, write an importer.

#### [Configuration](https://roundly-consulting.com/open-source/docs/imports-for-laravel/configuration.md)

Every key of config/imports.php with its env variable and default — key types, storage, limits, reading, preview, commit, undo, queue, templates, API.

#### [Importers](https://roundly-consulting.com/open-source/docs/imports-for-laravel/importers.md)

One class per record type extending Importer — every method and default, natural keys, create and update callbacks, rollback hooks, registration rules.

#### [Fields and values](https://roundly-consulting.com/open-source/docs/imports-for-laravel/fields.md)

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/owners-and-permissions.md)

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/facade.md)

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/without-facade.md)

Skip the facade: inject ImportsManager or call a single-purpose action — every host-facing action with its execute() signature and facade path.

#### [Reading files](https://roundly-consulting.com/open-source/docs/imports-for-laravel/reading-files.md)

The native streaming CSV and XLSX readers — format detection by content, encodings, delimiters, XLSX support, limits, rejections and Imports::read().

#### [Templates and error reports](https://roundly-consulting.com/open-source/docs/imports-for-laravel/templates.md)

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/column-mapping.md)

Mapping suggestions from headers, labels, aliases and fuzzy matches, map() by header or column, and saved mappings per owner that apply themselves.

#### [Validated preview](https://roundly-consulting.com/open-source/docs/imports-for-laravel/preview.md)

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/commit.md)

The commit as one Laravel job batch of idempotent chunks — progress, summary, callback exceptions, cancel and resume, the lock and the ledger.

#### [Undo](https://roundly-consulting.com/open-source/docs/imports-for-laravel/undo.md)

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/file-batches.md)

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](https://roundly-consulting.com/open-source/docs/imports-for-laravel/json-api.md)

The opt-in JSON API — every route, its validated input and response, the owner resolver, upload throttling, errors and resources without class names.

#### [Events](https://roundly-consulting.com/open-source/docs/imports-for-laravel/events.md)

Every event the package dispatches after the commit — upload, mapping, preview, start, chunks, completion, failure, cancel, resume, undo, cleanup.

#### [Exceptions](https://roundly-consulting.com/open-source/docs/imports-for-laravel/exceptions.md)

Every exception with its named constructors and HTTP status — rejections, mapping, state, authorization, undo window, definition and configuration errors.

#### [Artisan commands](https://roundly-consulting.com/open-source/docs/imports-for-laravel/commands.md)

imports:sweep, prune, doctor, importers, template and install — what each does, the doctor’s checks, scheduling and the facade equivalents.

#### [Testing](https://roundly-consulting.com/open-source/docs/imports-for-laravel/testing.md)

Imports::fake() records and passes through — every assertion pair, recorded operations, withoutRunning(), spreadsheet builders, factories, workbench.

#### [Requirements](https://roundly-consulting.com/open-source/docs/imports-for-laravel/requirements.md)

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 crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## 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.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source.md)