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:
| Action | execute(…) | Returns | Facade path |
|---|---|---|---|
Templates\BuildTemplateAction | (string $importer, TemplateFormat $format, ?string $locale = null) | Template | template() · importer()->template() |
Sessions\UploadImportAction | (UploadData $data) | ImportSession | for()->upload() |
Sessions\UploadFilesAction | (UploadFilesData $data) | ImportSession | for()->uploadFiles() |
Sessions\ConfigureSourceAction | (ImportSession $session, ?Model $actor, $sheet = null, ?string $delimiter = null, ?int $headerRow = null) | ImportSession | useSheet() · useDelimiter() · useHeaderRow() |
Sessions\DiscardImportAction | (ImportSession $session, ?Model $actor) | ImportSession | discard() |
Mapping\SuggestMappingAction | (ImportSession $session, ?Model $actor) | MappingSuggestion | suggestMapping() |
Mapping\ApplyMappingAction | (ImportSession $session, array|ColumnMapping $mapping, ?Model $actor) | ImportSession | map() |
Mapping\SaveMappingAction | (SaveMappingData $data) | SavedMapping | saveMapping() · mappings()->save() |
Mapping\DeleteSavedMappingAction | (Model $owner, string $importer, string $name, ?Model $actor) | bool | mappings()->delete() |
Preview\PreviewImportAction | (ImportSession $session, ?Model $actor, ?bool $queue = null) | ImportSession | preview() |
Preview\ChooseModeAction | (ImportSession $session, DuplicateMode $mode, ?Model $actor) | ImportSession | mode() |
Preview\BuildErrorReportAction | (ImportSession $session, TemplateFormat $format, ?Model $actor) | Template | errorReport() |
Commit\CommitImportAction | (ImportSession $session, ?Model $actor) | ImportBatch | commit() |
Commit\CancelImportAction | (ImportBatch $batch, ?Model $actor) | ImportBatch | cancel() |
Commit\ResumeImportAction | (ImportBatch $batch, ?Model $actor) | ImportBatch | resume() |
Rollback\RollbackImportAction | (ImportBatch $batch, ?Model $actor) | ImportBatch | rollback() |
Maintenance\PruneImportsAction · SweepImportsAction | () | PruneReport · SweepReport | prune() · 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 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.