Laravel Chunk Cursor Laravel Package

Product Decisions This Supports

Feature feasibility — bulk/large-dataset features stop being scary. Any roadmap item that means "process every row in a big table" is now a smaller estimate. Concretely, this unblocks or de-risks:

• Exports and data portability — CSV/XLSX exports of orders, users, invoices, audit logs where each row needs a related record (customer, line items, org). This is the classic case where cursor() OOMs on relations (N+1) and chunk() blows the query budget.
• Scheduled syncs and integrations — nightly pushes to a warehouse, CRM, ERP, or accounting system that must be idempotent, resumable-ish, and memory-bounded inside a queue worker.
• Backfills and migrations of data, not schema — recomputing a denormalized column, re-tagging records, retroactively applying a new business rule to historical rows.
• Search/recommendation re-indexing — streaming rows into Meilisearch/Elasticsearch/Algolia with their relations hydrated.
• Nightly reporting jobs — aggregations that must run in a worker with a hard memory ceiling rather than a dedicated analytics pipeline.

Build vs. buy — this is really "adopt vs. copy." At ~2 stars, 0 dependents, a single maintainer, and no release since April 2024, this is not a dependency decision; it's a snippet decision. The honest framing for the team: the concept (chunked cursor + eager loading) is worth adopting; this specific artifact is worth reading, not necessarily installing. Budget roughly half a day to a day to implement the equivalent as an internal base-repository trait or query macro, which removes the supply-chain and upgrade risk entirely.

What it buys you against the framework baseline: Laravel's chunk()/chunkById() support eager loading but issue a query per chunk (and chunk() can skip/duplicate rows if the dataset mutates underneath it); cursor() is memory-optimal but cannot eager load, so relations degrade to N+1. This package targets the gap between those two. That gap is real — validate it against your actual slowest job before committing.

Success metrics to instrument before and after: peak worker memory (MB), wall-clock runtime, query count per 10k rows, and failure/timeout rate on the largest job. If you can't show a memory or query-count win on a real job, don't adopt it.

When to Consider This Package

Good fit:

• You can point to a specific job that currently OOMs, times out, or fires an unacceptable number of queries — not a hypothetical one.
• The rows you iterate need related models (otherwise plain cursor() already solves it and you need nothing).
• You're on a Laravel/PHP version the package actually supports and are willing to pin the exact version and verify in a branch.
• You have a fork-and-own posture: MIT license, small surface area, so vendoring or reimplementing is cheap.
• Your dependency policy tolerates low-maturity packages when they're wrapped behind an internal interface.

Look elsewhere / pass:

• Mutation during iteration matters. If rows are being inserted or deleted while you iterate, you want chunkById/lazyById semantics (strict id > last keyset pagination) with explicit ordering guarantees. Confirm the package gives you keyset behavior, not offset, before relying on it.
• You need true resumability. If a 40-minute job must restart from a checkpoint after a deploy, neither this nor Laravel's built-ins give you that for free — you need a stored watermark. Design that yourself.
• Unsupported stack. Last release April 2024; verify Laravel 12 / PHP 8.4 before assuming it runs. No maintainer activity means no upgrade path.
• Unbuffered cursor + writes on the same connection. If the job writes back to the same DB connection while streaming (MySQL especially), unbuffered queries can conflict. Test this pattern explicitly.
• Strict procurement / SOC2 / dependency-review environments. Two stars and zero dependents will not clear review; reimplement instead.
• Very large scale (hundreds of millions of rows). At that point the answer is a warehouse or streaming pipeline, not an ORM-level optimization.

How to Pitch It (Stakeholders)

To executives: There's a small open-source utility that makes "process every record in a large table" jobs cheaper and safer — lower memory, fewer database round-trips, no midnight timeouts. It's not a strategic bet and it's not a platform commitment; it's a pattern worth ~one engineer-day. The package itself is immature (tiny community, single maintainer, no recent release), so the recommendation is to adopt the technique internally rather than take a dependency on it. Expect a modest reduction in incidents on export and sync jobs, and slightly better estimates on bulk-data features.

To engineering: It fills a genuine gap — chunked iteration with eager loading, which cursor() can't do and chunk() does wastefully. Risk profile is low because the code is small and MIT: read it, benchmark it against lazyById() on our worst-performing job, and if it wins, either pin it behind an internal ChunkedCursor interface with a fallback implementation, or reimplement it in the base repository. Do not let it leak into feature code directly — that keeps the swap-out cost near zero if it goes unmaintained.