Running Imports

Once an importer is defined and registered, you can start an import process in several ways, depending on your use case.

Artisan Commands

Laravel Ingest provides several Artisan commands for managing imports.

ingest:run

The ingest:run command is perfect for manual or scheduled imports where the source file is accessible on a local or configured filesystem disk.

php artisan ingest:run {slug} {--file=} {--dry-run}

# Run a product import from a file on the default disk
php artisan ingest:run product-importer --file="imports/products.csv"

# Perform a dry run to check for errors
php artisan ingest:run product-importer --file="imports/products.csv" --dry-run

ingest:list

List all registered importers and their configurations.

php artisan ingest:list

ingest:status

Check the status of a specific import run.

php artisan ingest:status {id}

ingest:cancel

Cancel a running import. This will stop processing new chunks but won't roll back already processed rows.

php artisan ingest:cancel {id}

ingest:retry

Retry failed rows from a previous import run.

php artisan ingest:retry {id} {--dry-run}

ingest:prune-files

Clean up old temporary and uploaded files to free disk space.

php artisan ingest:prune-files {--hours=24}

This command removes files from the ingest-temp and ingest-uploads directories that are older than the specified number of hours.

Scheduling File Cleanup

Add to your routes/console.php or scheduler:

// Clean up files older than 24 hours, daily
Schedule::command('ingest:prune-files')->daily();

// Clean up files older than 6 hours, every hour
Schedule::command('ingest:prune-files --hours=6')->hourly();

Row Log Pruning

To automatically prune old row logs (stored in ingest_rows table), add Laravel's model pruning command to your scheduler:

// In routes/console.php or App\Console\Kernel
Schedule::command('model:prune')->daily();

The retention period is configured via prune_days in config/ingest.php (default: 30 days).

2. Via API

Laravel Ingest automatically registers API endpoints to trigger and manage imports. These are ideal for integrations or when providing a user interface for uploads.

File Uploads (UPLOAD source)

To start an import that uses SourceType::UPLOAD, send a multipart/form-data POST request.

• Endpoint: POST /api/v1/ingest/upload/{importerSlug}
• Body: Must contain a file field with the uploaded file. You can also include an optional dry_run field set to 1 or true.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/users.csv" \
  -F "dry_run=1" \
  https://myapp.com/api/v1/ingest/upload/user-importer

Triggering Other Sources (FTP, URL, etc.)

For importers that don't require a file upload (like FTP or URL sources), you can trigger them with a simple POST request.

• Endpoint: POST /api/v1/ingest/trigger/{importerSlug}

curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://myapp.com/api/v1/ingest/trigger/daily-stock-importer

3. Programmatically (Facade)

You can start an import directly from your application code using the Ingest Facade. This is useful for complex workflows, scheduled jobs, or custom controllers.

use LaravelIngest\Facades\Ingest;
use Illuminate\Support\Facades\Auth;

$slug = 'product-importer';
$filePath = 'imports/products.csv'; // Path on a configured disk
$user = Auth::user();

// Start the import
$ingestRun = Ingest::start(
    importer: $slug, 
    payload: $filePath, 
    user: $user,
    isDryRun: false
);

// $ingestRun is the Eloquent model for the newly created run.
echo "Started ingest run with ID: " . $ingestRun->id;