- How do I install sammyjo20/laravel-haystack?
- Install it with Composer using composer require sammyjo20/laravel-haystack. Laravel's package discovery registers the service provider automatically, so no manual registration is normally needed. Make sure your app is configured with a queue driver that supports delayed and sequenced dispatch, such as Redis, database, or SQS, and run a queue worker as usual. After that you can dispatch your first haystack from a controller, command, or listener.
- What is the difference between Laravel Haystack and Bus::chain()?
- Bus::chain() dispatches a fixed list of jobs sequentially and gives you limited ability to inspect, extend, or resume the chain mid-flight. Laravel Haystack persists the stack and its shared data in your configured store, so you can add jobs before or during execution, apply delays, and observe progress. It also provides a single catch handler for the whole workflow, which is useful when a mid-chain failure needs one recovery path rather than per-job error handling.
- How do I pass data between jobs in a Laravel Haystack?
- Each haystack has a shared data bag that every job in the stack can read and write, so you do not have to serialise state from one job's constructor into the next. A job can store a value when it finishes and a later job in the same haystack can read it back. This keeps individual job payloads small and makes the workflow's state observable while it is still running.
- Which Laravel versions and queue drivers does Laravel Haystack support?
- The package is a thin orchestration layer over Laravel's queue system, so it needs a driver that reliably supports sequenced and delayed dispatch, such as Redis, the database driver, or SQS. It targets modern Laravel releases, so check the composer.json constraint on the release you are installing for the exact Laravel and PHP versions supported. If you are pinned to an older Laravel version, install the matching Haystack release rather than forcing the latest one.
- Can I add jobs to a haystack while it is running?
- Yes. One of the main reasons to use Haystack instead of a plain chain is that jobs can be appended to the stack during execution. A job that discovers more work can add follow-up jobs to the haystack, and they run in order after the current job finishes. This is useful for paginated imports, dynamic fan-out followed by a summary job, and workflows where the total number of steps is not known up front.
- How do I handle failures in a Laravel Haystack?
- A haystack supports a catch callback that runs when a job in the stack fails, giving you one place to log, notify, or compensate instead of handling errors job by job. As of v2.2.0 the haystack record is retained on failure rather than deleted, so you can inspect it afterwards and decide whether to retry or clear it. Make sure the catch handler itself is idempotent and safe to run more than once.
- Why does my haystack record stay behind after a failure in v2.2.0?
- Version 2.2.0 changed failure semantics so a failed haystack is no longer removed from its persistence store, which makes post-mortems and retries much easier. The trade-off is that failed records are no longer self-cleaning, so a persistent failure loop could accumulate rows or cache keys. Add a retention or pruning policy for that store, and update any alerting or dashboards that inferred failure from a haystack record disappearing.
- How do I add delays between jobs in a haystack?
- You can apply delays so there is a gap before the haystack starts or between individual jobs, which is useful for rate-limited APIs and backoff-style workflows. Because the haystack is persisted, a delayed workflow survives worker restarts and deploys. Keep delays within what your queue driver supports, and remember that delayed jobs count against your queue's scheduled workload.
- How do I test a Laravel Haystack in my test suite?
- Set the queue connection to sync, or use Queue::fake(), so haystacks either execute inline or are asserted rather than hitting a real worker. Assert that jobs were dispatched in the expected order and that the shared data bag ends up in the state you expect. To test failure paths, force a job to throw and assert that your catch handler ran and the haystack state matches the post-v2.2.0 retention behaviour.
- Is Laravel Haystack production ready, and what are the alternatives?
- Haystack is designed for multi-step queued workflows in production, and it is actively maintained with regular releases, though you should review the release notes since some patch versions change failure semantics rather than just fixing bugs. Alternatives include Laravel's native Bus::chain() and Bus::batch(), Laravel Workflow, and full workflow engines such as Temporal. Haystack sits in the middle: more durable and inspectable than a plain chain, without the operational overhead of a dedicated workflow service.