Engine Workflow Helper Laravel Package

Getting Started

Version context: this assessment reflects v3.0.0. Compared to 2.x, the only breaking changes are platform floors — no class, constant, or payload changes.

1. Confirm your platform. v3 requires PHP ^8.2 (built and tested against 8.5), Laravel 10/11/12, and betalabs/engine-phpsdk ^3.0. If you are on PHP 8.0/8.1, Laravel 9 or older, or pinned to engine-phpsdk 2.x, stay on 2.x — there is no partial upgrade path.
2. Install and publish config:

   composer require <vendor>/<package>:^3.0 betalabs/engine-phpsdk:^3.0
   php artisan vendor:publish --tag=<package>-config
   

   Bump engine-phpsdk explicitly rather than letting it come in transitively — a stale lockfile entry is the most common cause of a half-finished upgrade.
3. Where to look first, in this order:
   • config/ — credentials, base URL, and any dispatcher/HTTP options.
   • AppDispatcher — the single seam through which Get/Post/Put/Delete calls leave your app. Everything you do day-to-day routes through it.
   • Order\ steps — value objects describing the request body (e.g. Order\UpdateMultipleStatuses).
   • tests/ — 25 tests, order-independent, covering dispatcher verbs and enums. This is the best available documentation of exact payload shapes.
4. First use case: dispatch an order status update. Build the step explicitly, hand it to the dispatcher, assert the response:

   $step = new Order\UpdateMultipleStatuses(/* exact params — see the package test */);
   $response = app(AppDispatcher::class)->post($step);
   
   $response->successful();
   

   Run it against a sandbox/staging credential before wiring it into a controller.

Implementation Patterns

Encapsulate the dispatcher behind your own service. Inject AppDispatcher into a small EngineService (or per-domain action classes) bound in a service provider. Nothing in your domain layer should resolve it via app() or touch a facade — that keeps the upgrade blast radius to one file when the next major lands.

Model each operation as a step object, not an array. The package's own tests assert the exact parameters of Order\UpdateMultipleStatuses; treat that test as the contract. When you add an operation the package doesn't ship, write your own step class in the same shape rather than assembling an ad-hoc payload in a controller. Verb selection (Get/Post/Put/Delete) belongs in the step or its factory, not at the call site.

Push dispatches onto the queue. Network-bound operations should not sit in a request cycle. A job with $tries, backoff(), and failed() handling gives you retries and observability for free. Carry your own correlation ID (order ID + operation name) through the payload and into logs — the SDK will not give you an idempotency key for free.

Use the SDK enums, not strings. The v3 test suite explicitly exercises enums for events and verbs. Stringly-typed statuses are the most likely source of silent drift between your app and the Engine; type-hint against the enum in your action signatures and let static analysis catch typos.

Listeners can now be typed properly. v3 corrected malformed and swapped event/listener docblocks. If you register listeners for package events, re-check the expected event class and payload: code that "worked" in 2.x may have been relying on an incorrect annotation that your IDE or PHPStan was quietly ignoring. After upgrading, run your analyser before assuming nothing changed.

Mirror the package's test style. The dispatcher's Get/Post/Put/Delete surface is covered by the package tests; use the same fake-HTTP approach in your app tests so you assert the outgoing payload, not just the return value. Order-independence is guaranteed in the package's suite — your own suite should not lean on shared credential or config state either.

CI matrix. Given the package targets PHP 8.5 / Laravel 12, align your matrix accordingly (8.2, highest supported, × Laravel 10/11/12). This catches the illuminate constraint conflicts described below at PR time rather than at deploy time.

Gotchas and Tips

• The upgrade is dependency resolution, not code diff. Since there are no API changes, a failing upgrade is almost always a constraint conflict. Read the composer solver output carefully: illuminate/support and illuminate/http (^10||^11||^12) are now declared, where previously they were implicit. Anything in your tree that pins illuminate/* to ^9 will now conflict loudly instead of silently resolving.
• Laravel 9 is genuinely gone. There is no shim and no allow-plugins trick; plan the framework upgrade as a prerequisite, not a follow-up.
• Config caching. Credentials and base URLs live in config, which is cached in production. Always php artisan config:clear (or re-run config:cache) after touching .env — a surprising number of "the SDK isn't picking up my key" reports are this.
• Faking HTTP may not work the way you expect. If you use Http::fake() in tests, verify the SDK actually routes through Laravel's HTTP client rather than its own Guzzle client. If it doesn't, Http::fake() silently no-ops and your assertions pass for the wrong reason. Use the SDK's own mock handler in that case.
• Static analysis will produce new errors after upgrade, and that's expected. Corrected docblocks mean previously suppressed or mis-inferred types surface. Treat them as fixes, not regressions — but budget time for a PHPStan/Psalm pass in the upgrade PR.
• Debugging by payload. When a call fails, dump the step object's serialised form before dispatch and compare it field-by-field against the package's Order\UpdateMultipleStatuses test. That test encodes the exact expected parameter set, which makes it the fastest reference when the Engine rejects a request.
• Exception handling is yours. Wrap dispatcher calls in a domain-level try/catch and translate SDK exceptions into your own types; don't let SDK exception classes leak into controllers. Log the step payload on failure, redacting credentials.
• Extension point. AppDispatcher's four verb methods are the intended seam for operations the package doesn't ship. Build small step value objects on top of them rather than reaching into the SDK directly — that keeps you inside the package's abstraction and makes the eventual 4.x migration a single-file change.
• Watch for a 2.x branch maintenance assumption. The release notes state that older platforms "continue on 2.x," but do not commit to how long 2.x receives patches. If you cannot move to PHP 8.2 promptly, pin exactly and track the repo's branch activity rather than assuming indefinite support.