Batch Laravel Package

Technical Evaluation

Architecture fit. yokai/batch is a Spring Batch–inspired abstraction layer for PHP: Job → Step → (ItemReader / ItemProcessor / ItemWriter) or Tasklet, with a persisted JobRepository tracking JobExecution/StepExecution and execution context for restart-from-failure. The core is framework-agnostic and interface-driven; framework concerns (Doctrine, Symfony Serializer, League CSV, Symfony console/framework bundle) live in separate satellite packages in the monorepo. That decomposition is good news for Laravel: we can consume only yokai/batch (plus the CSV bridge if useful) and avoid dragging Symfony/Doctrine bridges into a Laravel dependency tree. Conceptually it fits the "nightly ETL / chunked import-export / restartable data pipeline" slot that Laravel's native Bus::batch() does not cover — Laravel batching is queue-job fan-out, not chunk-oriented read/process/write with skip and retry policies.

Integration feasibility. No first-party Laravel bridge exists (the only framework integration is yokai/batch-symfony-framework). The integration work is bounded and well-defined but non-trivial:

• JobRepository persistence is the main lift. Upstream ships Doctrine ORM and in-memory implementations; for Laravel we must implement the repository contract over Eloquent/DB (including optimistic locking, since the interface assumes concurrent execution safety).
• Launcher/orchestration maps cleanly onto an Artisan command (batch:run {job}) plus a service provider binding readers/processors/writers into the container.
• Queue integration is not native. Chunk-level dispatch onto Laravel queues is possible but we own the coordination; the package assumes a synchronous launcher.
• Everything is Composer-installable, PHP 8.1+, no extensions — low environmental friction.

Technical risk. The dominant risk is not technical, it's sustainability: 12 stars, 0 dependents, a single-maintainer org, and a last release of December 2023 (≈2 years stale at time of review). Adopting this is effectively adopting a codebase we may need to vendor and maintain ourselves. Secondary risks: unknown compatibility with current PHP (8.4) and Laravel 11/12; no observable community answer base; and API stability is unproven at this adoption level. The concept risk is low — the abstractions mirror a 20-year-old, well-understood pattern, so the mental model survives even if the library doesn't.

Key questions.

• Is the JobRepository contract stable and documented well enough to implement correctly against Eloquent, including locking semantics?
• Does the current composer.json permit PHP 8.3/8.4 and coexist with Laravel's pinned Symfony components (relevant only if we touch any bridge)?
• What are the exact chunk transaction boundaries — commit-per-chunk, and are writers expected to be idempotent on retry?
• Is there a changelog / semver discipline, and what is the maintainer's stated commitment horizon?
• Does skip/retry policy granularity (per-exception-class) match our error-handling requirements, or will we be fighting it?
• What is the cost/benefit versus Laravel's native Bus::batch() for each pipeline we'd migrate?

Integration Approach

Stack fit. Good. Composer-only, PHP 8.1+, no C extensions, PSR-friendly interfaces, and a PHPStan extension in the monorepo (a positive quality signal). The Symfony/Doctrine satellites are optional and should be avoided — they are the most likely source of dependency-graph conflicts with Laravel's locked Symfony versions. Plan on: yokai/batch + yokai/batch-league-csv (if CSV I/O is needed) + our own Eloquent reader/writer and JobRepository adapters.

Migration path. Greenfield-first, strangler-fig later. Do not retrofit existing queued jobs. Pick a single non-critical, naturally chunked pipeline (nightly CSV import, catalog sync, report materialization) behind a feature flag, in an isolated module. If it proves out, expand pipeline-by-pipeline and only then consider replacing incumbent jobs.

Compatibility. Primary unknowns are PHP version ceiling and any transitive Symfony constraints. Mitigation: install the framework-agnostic core only, run composer why-not checks against the Laravel lock file, and pin exact versions. The PHPUnit bridge is useful — it implies jobs are unit-testable without a real data source, which shortens the feedback loop materially.

Sequencing.

1. Spike (1–2 days): in-memory JobRepository, one trivial reader/processor/writer, run a 2-step job from a test. Confirms API ergonomics and PHP/Laravel compatibility.
2. Thin internal adapter package: service provider + config, batch:run Artisan command, Eloquent-backed JobRepository (with locking + indexed execution tables), container bindings for job definitions.
3. Pilot pipeline in production behind a flag, with a parallel run against the incumbent implementation for output diffing.
4. Generalize: shared writers (Eloquent upsert, CSV), events/metrics hooks into Laravel logging + Horizon, failure alerting.
5. Fork-or-vendor decision if upstream shows no activity by the end of the pilot.

Operational Impact

Maintenance. Assume we own this. The surface is small and interface-heavy, which makes it cheap to maintain — but there is no upstream safety net, so budget roughly 0.1 FTE ongoing for the Laravel adapter plus occasional patches, and a defined policy for vendoring/forking under our org if the upstream stalls. Pin exact versions; do not float.

Support. No commercial support, minimal community, Symfony-flavored docs and examples. Internal ownership and internal documentation are mandatory. The compensating factor is that the pattern is standard enough that a competent engineer can reason about behavior without upstream help.

Scaling. Chunk-oriented processing gives bounded memory per worker — a genuine advantage over naive ->get() loops. Horizontal scale is ours to design: multiple workers over partitioned inputs, with the JobRepository as the coordination/contention point (needs proper indexing and correct optimistic locking). Restart-from-failure is the headline capability, and it works only if our repository implementation is correct.

Failure modes.

• Upstream abandonment → unpatched bugs, PHP/Laravel version drift over time.
• JobRepository bugs → duplicate processing, lost restart state, or corrupted execution history.
• Chunk commit boundaries without idempotent writers → duplicate side effects on retry. Writers must be designed as upserts.
• Long-running steps monopolizing queue workers → dedicate a queue/connection with explicit timeouts and --max-time style guards.
• Memory leaks in custom readers over very large datasets — must be load-tested, not assumed.
• No Laravel-native observability → we must emit events/metrics ourselves, or failures are silent.

Ramp-up. Spring Batch concepts (chunk vs. tasklet, skip/retry policies, execution context) are unfamiliar to most Laravel developers, whose mental model is jobs-and-queues. Expect ~1–2 weeks for a senior engineer to be independently productive, plus documentation effort. Weigh this against the opportunity score: the package is genuinely useful only where you need restartable, chunk-oriented ETL with skip/retry semantics — for plain fan-out batch work, Laravel's Bus::batch() remains the lower-risk default, and this package should be scoped narrowly to the pipelines that actually need it.