NewWe open-sourced 50+ Laravel packages
Custom AI apps, agents and automation — Roundly ConsultingRoundly
All packages
Imports for Laravel

DI and actions

The facade is the recommended default, not the only way in. Every operation is an action, the manager exposes each one and the facade is sugar over the manager — all three run the same code. The manager is RoundlyConsulting\Imports\ImportsManager, the facade’s root, bound as a container singleton:

use RoundlyConsulting\Imports\Actions\Sessions\UploadImportAction;
use RoundlyConsulting\Imports\DataTransferObjects\{ImportSource, UploadData};
use RoundlyConsulting\Imports\Facades\Imports;
use RoundlyConsulting\Imports\ImportsManager;

// 1. Facade
$session = Imports::for($team)->by($user)->upload('assets', $request->file('file'));

// 2. Dependency injection — the same object the facade resolves (a container singleton)
public function __construct(private ImportsManager $imports) {}
$session = $this->imports->for($team)->by($user)->upload('assets', $request->file('file'));

// 3. The raw action — returns the model, not a handle
$model = app(UploadImportAction::class)->execute(
    new UploadData('assets', $team, $user, ImportSource::upload($request->file('file'))),
);
$session = Imports::session($model);   // wrap it in a handle (trusted path)

Inject the manager

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use RoundlyConsulting\Imports\ImportsManager;

final class AssetImportController
{
    public function __construct(private ImportsManager $imports) {}

    public function store(Request $request): JsonResponse
    {
        $session = $this->imports->for($request->user()->currentTeam)->by($request->user())
            ->upload('assets', $request->file('file'))
            ->preview();

        return response()->json($session->counts()->toArray());
    }
}

The manager is not final on purpose — the fake extends it, so code that injects ImportsManager still type-checks under Imports::fake() and is faked too.

Call an action

Actions are final readonly classes with one execute(). Resolve them from the container. They take and return models, not handles — wrap a model with Imports::session($model) or Imports::batch($model) when you need one:

use RoundlyConsulting\Imports\Actions\Commit\CommitImportAction;
use RoundlyConsulting\Imports\Actions\Mapping\SaveMappingAction;
use RoundlyConsulting\Imports\Actions\Templates\BuildTemplateAction;
use RoundlyConsulting\Imports\DataTransferObjects\SaveMappingData;
use RoundlyConsulting\Imports\Enums\TemplateFormat;

$template = app(BuildTemplateAction::class)->execute('assets', TemplateFormat::Csv, 'sk');
$batch = app(CommitImportAction::class)->execute($sessionModel, $user);   // an ImportBatch model

app(SaveMappingAction::class)->execute(
    SaveMappingData::fromColumns($team, 'assets', 'ERP', ['Inventárne č.' => 'asset_tag'], $user),
);

Facade method → action

Namespaces are relative to RoundlyConsulting\Imports\Actions:

Actionexecute(…)ReturnsFacade path
Templates\BuildTemplateAction(string $importer, TemplateFormat $format, ?string $locale = null)Templatetemplate() · importer()->template()
Sessions\UploadImportAction(UploadData $data)ImportSessionfor()->upload()
Sessions\UploadFilesAction(UploadFilesData $data)ImportSessionfor()->uploadFiles()
Sessions\ConfigureSourceAction(ImportSession $session, ?Model $actor, $sheet = null, ?string $delimiter = null, ?int $headerRow = null)ImportSessionuseSheet() · useDelimiter() · useHeaderRow()
Sessions\DiscardImportAction(ImportSession $session, ?Model $actor)ImportSessiondiscard()
Mapping\SuggestMappingAction(ImportSession $session, ?Model $actor)MappingSuggestionsuggestMapping()
Mapping\ApplyMappingAction(ImportSession $session, array|ColumnMapping $mapping, ?Model $actor)ImportSessionmap()
Mapping\SaveMappingAction(SaveMappingData $data)SavedMappingsaveMapping() · mappings()->save()
Mapping\DeleteSavedMappingAction(Model $owner, string $importer, string $name, ?Model $actor)boolmappings()->delete()
Preview\PreviewImportAction(ImportSession $session, ?Model $actor, ?bool $queue = null)ImportSessionpreview()
Preview\ChooseModeAction(ImportSession $session, DuplicateMode $mode, ?Model $actor)ImportSessionmode()
Preview\BuildErrorReportAction(ImportSession $session, TemplateFormat $format, ?Model $actor)TemplateerrorReport()
Commit\CommitImportAction(ImportSession $session, ?Model $actor)ImportBatchcommit()
Commit\CancelImportAction(ImportBatch $batch, ?Model $actor)ImportBatchcancel()
Commit\ResumeImportAction(ImportBatch $batch, ?Model $actor)ImportBatchresume()
Rollback\RollbackImportAction(ImportBatch $batch, ?Model $actor)ImportBatchrollback()
Maintenance\PruneImportsAction · SweepImportsAction()PruneReport · SweepReportprune() · sweep()
  • The facade and the manager resolve every action from the container, so binding your own subclass of an action applies to all three styles.
  • Imports::fake() records calls made through the facade, the manager, every handle and the model conveniences ($session->handle(), $batch->handle()).
  • Internal building blocks — ValidateRowsAction, ClassifyRowsAction, PreviewFilesAction, ProcessChunkAction, FinishImportAction, FailImportAction, RollbackChunkAction and FinishRollbackAction, run by the jobs and the sweep — are not for app code.

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

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