Laravel Laravel Package

Getting Started

Start by confirming the installed version and where the package hooks into Eloquent:

composer show <vendor>/<package>
php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"

The first thing to inspect is the package's query entry point—typically a Query class, a trait applied to models, or a builder macro. In v2.1.0 the key addition is that the query method now supports Eloquent-style retrieval methods, including lazy(). That means you can move from:

$rows = Model::query()->get();

to:

Model::query()->lazy(500)->each(function ($row) {
    // process one model at a time
});

Use this first for any command, job, or export that currently loads thousands of models with get(). Confirm the package's retrieving method delegates to Eloquent correctly by checking that lazy() returns a LazyCollection and that the underlying SQL is executed only once.

Implementation Patterns

Chunked processing with lazy()

Use lazy($chunkSize) as the default retrieval method for large datasets. It keeps memory flat because each chunk is hydrated and released as you iterate:

Model::query()
    ->where('status', 'pending')
    ->lazy(1000)
    ->each(fn ($model) => $model->process());

Eager loading still applies

Chain with() before the retrieval method. The package passes the query through to Eloquent, so relationship loading and constraints behave as usual:

Model::query()
    ->with(['customer', 'lines'])
    ->lazy(250)
    ->each(fn ($order) => $order->sync());

Repository and pipeline integration

If you wrap queries in repositories, expose lazy() consistently rather than leaking get() everywhere:

class OrderRepository
{
    public function pending(): LazyCollection
    {
        return Order::query()
            ->where('status', 'pending')
            ->with('customer')
            ->lazy(500);
    }
}

Consumers can then compose with map(), filter(), takeWhile(), and other LazyCollection methods without loading everything into memory.

Jobs and commands

Use lazy() inside queued jobs or Artisan commands where memory limits are tight. Pair it with lazyById() if the package exposes that (or if the underlying Eloquent builder does) to avoid skipping or duplicating rows when records are updated during iteration.

Testing lazy retrieval

Because lazy() returns a LazyCollection, assertions differ from normal collections. Convert when needed or assert on iteration:

$results = Model::query()->lazy(10);
$this->assertInstanceOf(LazyCollection::class, $results);
$this->assertSame(3, $results->count());

Gotchas and Tips

• lazy() is not a Collection. It returns LazyCollection. Methods like count(), toArray(), and first() work but may consume the sequence. If you need multiple passes, materialize intentionally or re-query.
• Chunk size matters. Too small adds query overhead; too large defeats the memory benefit. Start around 500–1000 and measure.
• Do not mutate the builder after iteration starts. The retrieval method captures the query state. Adding where() clauses after calling lazy() will not affect the running query.
• Eager loading is per chunk. with() works, but relations are loaded chunk by chunk. Watch for constraint mismatches if you rely on global scopes that change between chunks.
• Long-running transactions. lazy() can hold a database connection open for the duration of iteration. Avoid wrapping large lazy loops in a single transaction unless necessary.
• Ordering and lazyById(). Plain lazy() with orderBy can skip rows if the ordering column changes mid-iteration. Prefer lazyById() for stable pagination when available.
• Debugging SQL. Use DB::listen() or the package's query logging to confirm the retrieval method is not accidentally calling get() internally. The v2.1.0 feature should produce chunked queries, not one large query.
• Config quirks. Check any package config for default chunk sizes or retrieval strategy. Clear cached config after upgrading: php artisan config:clear.
• Extension points. If the package exposes custom retrieving methods or builder macros, register them in a service provider rather than modifying vendor code. This keeps lazy() support consistent across your own abstractions.
• Version compatibility. v2.1.0 adds retrieval support; confirm your Laravel version matches the package's supported constraints, especially if you rely on LazyCollection behavior that changed across Laravel releases.