Category: Uncategorized

Stop writing spaghetti code for imports.

Laravel Ingest is a robust, configuration-driven ETL (Extract, Transform, Load) framework for Laravel. It replaces
fragile, procedural import scripts with elegant, declarative configuration classes.

Whether you are importing 100 rows or 10 million, Laravel Ingest handles the heavy lifting: streaming, chunking,
queueing, validation, relationships, and error reporting.

Most import implementations suffer from the same issues: memory leaks, timeouts, lack of validation, and messy
controllers.

Laravel Ingest solves this by treating imports as a first-class citizen:

• ♾️ Infinite Scalability: Uses Generators and Queues to process files of any size with flat memory usage.
• 📝 Declarative Syntax: Define what to import, not how to loop over it.
• 🧪 Dry Runs: Simulate imports to find validation errors without touching the database.
• 🔗 Auto-Relations: Automatically resolves BelongsTo and BelongsToMany relationships (e.g., finding IDs by
  names).
• 🛡️ Robust Error Handling: Tracks every failed row and allows you to download a CSV of only the failures to fix
  and retry.
• 🔌 API & CLI Ready: Comes with auto-generated API endpoints and Artisan commands.

Full documentation is available at zappzerapp.github.io/laravel-ingest.

composer require zappzerapp/laravel-ingest

# Publish config & migrations
php artisan vendor:publish --provider="LaravelIngest\IngestServiceProvider"

# Create tables
php artisan migrate

Create a class implementing IngestDefinition. This is the only code you need to write.

namespace App\Ingest;

use App\Models\User;
use LaravelIngest\Contracts\IngestDefinition;
use LaravelIngest\IngestConfig;
use LaravelIngest\Enums\SourceType;
use LaravelIngest\Enums\DuplicateStrategy;

class UserImporter implements IngestDefinition
{
    public function getConfig(): IngestConfig
    {
        return IngestConfig::for(User::class)
            ->fromSource(SourceType::UPLOAD)
            ->keyedBy('email') // Identify records by email
            ->onDuplicate(DuplicateStrategy::UPDATE) // Update if exists
            
            // Map CSV columns to DB attributes
            ->map('Full Name', 'name')
            ->map(['E-Mail', 'Email Address'], 'email') // Supports aliases
            
            // Handle Relationships automatically
            ->relate('Role', 'role', Role::class, 'slug', createIfMissing: true)
            
            // Validate rows before processing
            ->validate([
                'email' => 'required|email',
                'Full Name' => 'required|string|min:3'
            ]);
    }
}

In App\Providers\AppServiceProvider:

use LaravelIngest\IngestServiceProvider;

public function register(): void
{
    $this->app->tag([UserImporter::class], IngestServiceProvider::INGEST_DEFINITION_TAG);
}

You can now trigger the import via CLI or API.

Via Artisan (Backend / Cron):

php artisan ingest:run user-importer --file=users.csv

Via API (Frontend / Upload):

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

Want to see Laravel Ingest in action? Check out our Laravel Ingest Demo repository for a complete working example.

# Clone the demo
git clone https://github.com/zappzerapp/Laravel-Ingest-Demo.git
cd Laravel-Ingest-Demo

# Start and benchmark
docker compose up -d
docker compose exec app php artisan benchmark:ingest

Ingest runs happen in the background. You can monitor and manage them easily:

The package automatically exposes endpoints for building UI integrations (e.g., React/Vue progress bars).

• GET /api/v1/ingest – List recent runs.
• GET /api/v1/ingest/{id} – Get status and progress.
• GET /api/v1/ingest/{id}/errors/summary – Get aggregated error stats (e.g., "50x Email invalid").
• GET /api/v1/ingest/{id}/failed-rows/download – Download a CSV of failed rows to fix & re-upload.

Hook into the lifecycle to send notifications (e.g., Slack) or trigger downstream logic.

• LaravelIngest\Events\IngestRunStarted
• LaravelIngest\Events\ChunkProcessed
• LaravelIngest\Events\RowProcessed
• LaravelIngest\Events\IngestRunCompleted
• LaravelIngest\Events\IngestRunFailed

To keep your database clean, logs are prunable. Add this to your scheduler:

$schedule->command('model:prune', [
    '--model' => [LaravelIngest\Models\IngestRow::class],
])->daily();

The IngestConfig fluent API handles complex scenarios with ease.

IngestConfig::for(Product::class)
    // Sources: UPLOAD, FILESYSTEM, URL, FTP, SFTP
    ->fromSource(SourceType::FTP, ['disk' => 'erp', 'path' => 'daily.csv'])
    
    // Performance
    ->setChunkSize(1000)
    ->atomic() // Wrap chunks in transactions
    
    // Logic
    ->keyedBy('sku')
    ->onDuplicate(DuplicateStrategy::UPDATE_IF_NEWER)
    ->compareTimestamp('last_modified_at', 'updated_at')
    
    // Transformation
    ->mapAndTransform('price_cents', 'price', fn($val) => $val / 100)
    ->resolveModelUsing(fn($row) => $row['type'] === 'digital' ? DigitalProduct::class : Product::class);

See the Documentation for all available methods.

We provide a Docker-based test environment to ensure consistency.

# Start Docker
composer docker:up

# Run Tests
composer docker:test

# Check Coverage
composer docker:coverage

We welcome contributions! Please see CONTRIBUTING.md for details.

The MIT License (MIT). Please see License File for more information.

You know that feeling when you’re building a Laravel app and you just need a tiny bit of reactivity? A counter. A toggle. Something that feels overkill for a full Vue component but too annoying for vanilla JavaScript?

I kept reaching for Alpine.js, which is great, but I wanted Vue’s Composition API. The ref(), the computed(), the familiar syntax I already know. So I built Vector.

What Even Is This?

Vector is a Laravel package that lets you write Vue directly in your Blade templates with zero ceremony:

<script setup>
 const i = ref(0);
</script>

<div>
 <button @click="i++">Click Me</button>
 <div>
 Count: @
 </div>
 <div v-if="i > 5">Success!</div>
</div>

That’s the whole thing. No build step for your components. No separate .vue files. No special directives wrapping your code. Just a <script setup> tag and you’re done.

How It Works

The <script setup> tag gets transformed at compile time. Vector treats the element immediately after the script tag as your Vue template. Everything inside that element becomes reactive, and anything outside it remains regular Blade.

1. Blade’s precompiler finds your <script setup> blocks
2. Extracts your variable declarations
3. Mounts Vue on the next sibling element

The key part is the variable extraction. It parses const, let, and var declarations and auto-returns them to the template. You write normal code, it figures out the rest.

Escaping Blade Syntax

Since Blade also uses for output, you need to prefix Vue’s mustache syntax with @ to prevent Blade from processing it:

@

Alternatively, use Vue directives like v-text which don’t conflict with Blade:

<span v-text="count"></span>

Installation

composer require brunoabpinto/vector

Add Vector to your Vite entry points in vite.config.js:

plugins: [
 laravel({
 input: [
 "resources/css/app.css",
 "resources/js/app.js",
 "resources/js/vendor/vector.js",
 ],
 // ...
 }),
],
resolve: {
 alias: {
 'vue': 'vue/dist/vue.esm-bundler.js',
 },
},

Add @vectorJs before your closing </body> tag in your layout:

<body>
 

 @vectorJs
</body>

That’s it. Vector auto-publishes its runtime, and @vectorJs loads it where you need it.

The Trade-offs

Let’s be real about what this is:

Good for:

• Quick interactive elements
• Prototyping
• When you want Vue’s API without Vue’s ceremony
• Laravel apps that are mostly server-rendered with islands of reactivity

Not great for:

• Complex component hierarchies
• When you need proper SFC features (scoped styles, etc.)
• Large-scale SPAs (just use Inertia at that point)

Try It

The package is available on GitHub. Star it, fork it, tell me it’s an abomination. Whatever feels right.

composer require brunoabpinto/vector