Engine Workflow Helper Laravel Package

Product Decisions This Supports

• Build vs. buy for Engine integration: This package is the vendor-maintained Laravel binding to betalabs/engine-phpsdk. Choosing it over a hand-rolled HTTP client removes the need to own auth, request dispatch, and payload shaping for Engine endpoints — a decision that trades a small amount of flexibility for a maintained upgrade path.
• E-commerce/ERP roadmap sequencing: Order lifecycle operations (e.g. Order\UpdateMultipleStatuses) and the AppDispatcher HTTP verbs (Get/Post/Put/Delete) map directly to customer-facing flows like status tracking, fulfillment updates, and catalog sync. Their presence and test coverage are a proxy for which Engine capabilities are safe to commit to a release.
• Platform support policy: The explicit support matrix (PHP 8.2–8.5, Laravel 10/11/12) is the input for deciding when to schedule framework upgrades and when to freeze the fleet. It answers "can we move to Laravel 12 this quarter?" with a maintenance-cost answer rather than a guess.
• Integration risk register: The 1.x/2.x → 3.x cutoff gives a concrete deprecation horizon. Apps on PHP <8.2, Laravel ≤9, or engine-phpsdk 2.x are stranded on 2.x and accumulate security and support debt — a trackable line item, not an unknown.
• Vendor dependency concentration: Because Laravel dependencies were previously implicit and are now declared (illuminate/support, illuminate/http), the package is now honest about its footprint. That is the kind of signal that informs a "single vendor, single SDK" risk call.
• Release-gate criteria for internal services: 25 tests across three Laravel majors running in CI on every PR is a quality bar we can cite when arguing that internal wrappers need comparable coverage before they gate a launch.

When to Consider This Package

Adopt when:

• The product runs on Betalabs Engine and is built on Laravel 10, 11, or 12 with PHP 8.2+ — i.e. you are inside the v3 support window.
• You want vendor-maintained event/listener wiring and dispatcher plumbing rather than bespoke glue, and you value a stable public API (v3 explicitly preserves classes, constants, and outbound payloads from 2.x).
• You are starting a new Engine integration and can begin on the current major, avoiding a migration later.
• You want upgrade confidence: the 2.x → 3.x move is a dependency-and-runtime bump, not a code rewrite.

Look elsewhere or defer when:

• You are on PHP 8.1 or below, or Laravel 9 or earlier. You stay on 2.x by design; plan the runtime upgrade first, or budget for a maintained fork.
• You are pinned to betalabs/engine-phpsdk 2.x for reasons outside this package (another service, a shared contract). Coordinate the SDK bump before touching this one.
• You need Engine endpoints or resources this wrapper does not expose — it is a binding, not an API expansion, and v3 adds no new surface area.
• You are not on Betalabs Engine at all, or you need a multi-provider abstraction layer. A single-vendor binding will not give you portability.
• You require first-class typed DTOs or contract testing beyond what the SDK provides; the v3 changes here are docblock corrections, not a typing overhaul — treat docblock fixes as accuracy, not as a type-safety guarantee.

How to Pitch It (Stakeholders)

To executives: The Engine integration has a new major version. It is a maintenance release, not a feature release — the same business capabilities ship, with a cleaner dependency story and a real test suite. The strategic point is the upgrade clock: v3 supports PHP 8.2–8.5 and Laravel 10–12, and anything older stays on 2.x permanently. Staying behind means running unsupported runtime and framework versions on revenue-adjacent order flows. The ask is a scheduled upgrade, not new budget.

To engineering: v3.0.0 pins betalabs/engine-phpsdk to ^3.0, requires PHP ^8.2 and Laravel 10+, and now declares illuminate/support and illuminate/http explicitly instead of relying on implicit Laravel presence. There are no API changes — classes, constants, and outbound Engine payloads are identical to 2.x — so the migration is a composer and runtime bump, not a refactor. The release also fixes incorrect and swapped docblocks across event/listener types and adds 25 tests covering Order\UpdateMultipleStatuses step parameters, AppDispatcher Get/Post/Put/Delete, and enums, verified green on Laravel 10, 11, and 12 in any order via GitHub Actions on PHP 8.5.

Positioning: Treat this as the moment to align the runtime fleet, not to re-litigate the build-vs-buy decision. The package is a thin, vendor-owned binding with a stable API and now an honest dependency contract; the cost of v3 is an upgrade window, and the cost of skipping it is an unsupported platform underneath order and catalog operations.