Quest Laravel Package

Getting Started

Install the package with Composer and let Laravel's package discovery register the service provider:

composer require caneara/quest

v4.0.0 introduces configuration options, so the first thing to do after upgrading (or installing fresh) is publish and inspect the config file:

php artisan vendor:publish --tag=quest-config

Then read config/quest.php top to bottom before writing any quest — the defaults chosen by the package are the ones your first workflow will silently inherit.

Where to look first, in order:

1. config/quest.php — the new surface area in v4, and the cheapest place to change behaviour without touching code.
2. src/ — particularly the base quest/task classes and the service provider, which show what is bound into the container and what is macroable.
3. The package's own tests/ directory — the most reliable documentation of expected usage, especially for anything the README glosses over.

First use case: pick a multi-step process you already have smeared across a controller or a job — order fulfilment, onboarding, an import pipeline — and model it as a single quest with discrete tasks. Keep the first one to three or four steps so you can see the sequencing and failure behaviour clearly before adding branching or queueing.

Implementation Patterns

One quest per business process, one task per side effect. Quests stay thin and readable; tasks do exactly one thing and are independently testable. When a task grows a second responsibility, split it.

Pass a single payload/context object through the chain rather than reaching for globals or re-querying models. Tasks should read from and write to that context, which keeps them composable and makes assertions in tests trivial.

Queue anything with I/O. A quest that sends mail, hits a third-party API, or writes to several tables should run on a queue. Note that once queued, the payload must be serializable — pass IDs and primitives, not Eloquent models with loaded relations or closures.

Use the config file as your integration seam. The v4 config options are the right place for queue connection, retry/backoff policy, and table or table-prefix naming. Prefer environment-driven config over subclassing internals; it survives package upgrades.

Wire observability at the quest boundary, not inside tasks. Register listeners for the package's lifecycle events and log start/finish/failure with the quest name and payload identifier. This gives you an audit trail and a debugging trail in one place.

Test quests by asserting on the context and on side effects, not on internal call order. For anything nondeterministic, use Bus::fake(), Mail::fake(), and Http::fake() in the usual Laravel way.

Gotchas and Tips

• v4.0.0 is a major despite a small changelog. The only listed change is "Added configuration options," but the major version bump is your signal that defaults, config keys, or constructor signatures may have moved. Diff the published config against the previous version, and run your full suite — not just the quest tests — after upgrading.
• Republish, don't overwrite. Publish the config to a temp path and diff it against your existing copy so you actually see which keys are new in v4 rather than blowing away your tuned values.
• Config caching bites. If you run php artisan config:cache in deploy, changed config values won't apply until you re-cache. Most "the package is ignoring my settings" reports are this.
• Serialization failures surface late. A queued quest with a non-serializable payload often fails only when the worker picks it up, not at dispatch. Add a test that dispatches and processes synchronously (Bus::fake() plus a manual handle()) to catch it early.
• Idempotency is your responsibility. Retries and queue redelivery mean a task can run twice. Guard side effects with updateOrCreate, unique jobs, or an explicit "already done" check in the context.
• Debug a stuck quest by narrowing to one task. Run the quest with a single task in the list, confirm it completes, then add tasks back one at a time. Logging at the quest boundary alone won't tell you which step died.
• Extension points to prefer: custom task classes, your own abstract base quest holding shared config, and Laravel macros where the package exposes them. Avoid editing vendor/ or subclassing deep internals — those are exactly what a v5 will move.
• Pin the major version ("caneara/quest": "^4.0") and read the changelog before each bump; the jump from 3 to 4 with a one-line changelog suggests this package does not document breaking changes exhaustively.