Engine Workflow Helper Laravel Package

Technical Evaluation

Context: No prior assessment existed for this package. This is the baseline assessment, derived solely from the v3.0.0 release notes. The package is a Laravel integration layer over the betalabs/engine-phpsdk client — it exposes Engine domain objects (classes, constants, enums, event/listener types) and dispatches HTTP calls through an AppDispatcher (Get/Post/Put/Delete). It is a thin, opinionated adapter, not a business-logic library.

Architecture fit: Good for teams already standardized on Laravel + a Betalabs/Engine payment backend. The explicit declaration of illuminate/support and illuminate/http (^10 || ^11 || ^12) is an architectural improvement: the Laravel coupling was previously implicit, which meant Composer could resolve the package into a non-Laravel or wrong-major context and fail at runtime rather than at install time. That is now a hard, checkable contract. Keeping the package thin (no API surface change in 3.0) is the right call for a payment-adjacent dependency — it keeps the blast radius of upgrades small.

Integration feasibility: High. Zero API change from 2.x means no code edits in consumer services — the upgrade is a version-constraint exercise plus validation. The real work is verifying the transitive jump to betalabs/engine-phpsdk ^3.0, which is not described in these notes and is the single largest unknown. "No API change" applies to this package's surface, not to the SDK's wire behavior (auth, retry, timeouts, error shapes, idempotency headers). Treat SDK 3.0 as an independent integration risk requiring its own review.

Technical risk:

Key questions for the maintainer:

1. What changed in betalabs/engine-phpsdk 3.0, and is it wire-compatible with 2.x for the calls we use?
2. Is 2.x still receiving security/maintenance patches, and for how long? What is the 3.x support window?
3. Will PHP 8.2/8.3/8.4 be added to the CI matrix so the declared floor is actually exercised?
4. Are the docblock corrections type-only, or do they change inferred generics/shapes that static analysis will surface downstream?
5. Is there a retry/timeout/idempotency configuration surface, or is that entirely delegated to the SDK?
6. What is the intended Laravel 13 / PHP 8.6 timeline, and is this package tracking framework releases proactively?

Integration Approach

Stack fit: Laravel 10, 11, or 12 on PHP 8.2–8.5, with betalabs/engine-phpsdk ^3.0. This maps cleanly onto currently supported Laravel majors; Laravel 9 and PHP < 8.2 are explicitly out of scope. Package targets Laravel 12 / PHP 8.5, which is the direction of travel — adopting 3.x now avoids being stranded later.

Compatibility: The constraint set is coherent and mutually satisfiable: php ^8.2, illuminate/* ^10||^11||^12, engine-phpsdk ^3.0. Consumers must confirm no other dependency pins engine-phpsdk to 2.x (common in monorepos where a shared internal package wraps the SDK). That is the most likely source of a blocked resolution.

Migration path (per service):

1. Bump require to ^3.0; run composer update <package> betalabs/engine-phpsdk --with-dependencies in a branch.
2. Confirm no resolution conflicts; if a sibling package pins SDK 2.x, sequence that package first or use composer why-not.
3. Run the application suite unchanged — expected green, since no API changed.
4. Diff static-analysis output (PHPStan/Psalm) against the pre-upgrade baseline; triage docblock-driven deltas.
5. Replay a sandbox transaction set (auth, order create, UpdateMultipleStatuses, error paths) against Engine to validate SDK 3.0 behavior.
6. Soak in staging for one settlement/refund cycle before production.

Sequencing:

• Wave 1 (pilot): one low-risk internal service or a staging-only deployment. Validates the SDK 3.0 wire behavior and static-analysis delta. Gate: sandbox transaction parity + clean analyzer diff.
• Wave 2: remaining services on Laravel 10–12 / PHP 8.2+.
• Wave 3 (deferred): any service on Laravel 9 or PHP < 8.2. These stay on 2.x by design; if 2.x maintenance is unclear, schedule the platform upgrade (Laravel/PHP) first, then pick up 3.x. Do not attempt to hold the package back — the PHP/Laravel floor is a platform decision, not a package-level override.
• Freeze window: avoid deploying during month-end/reconciliation periods if payment flows are in scope.

Estimated effort: 0.5–1 dev day per service for the mechanics; add 1–2 days for the pilot to cover SDK 3.0 sandbox validation and analyzer triage. Total is dominated by the pilot, not by per-service repetition.

Operational Impact

Maintenance: Low steady-state. The package is thin, has no API churn in this release, and now declares its framework dependencies explicitly — which reduces the frequency of "works on my machine" Composer surprises. The cost is concentrated in version-boundary events (Laravel majors, PHP minors, SDK majors). Pinning with ^3.0 and letting Renovate/Dependabot surface releases is appropriate; do not auto-merge SDK major bumps without the sandbox check above.

Support: The main gap. There is no stated support policy, EOL date for 2.x, or security disclosure process in the release notes. Mitigations: (a) pin to a known-good patch version and upgrade deliberately, (b) confirm 2.x's maintenance window before deferring any service, (c) treat the package as a forkable dependency — it is small enough that an internal fork is a credible contingency if the maintainer goes quiet. Assign a named owner for this dependency so a stalled release is noticed before it becomes urgent.

Scaling: Unchanged by this release — scaling characteristics are entirely inherited from the Engine API and the consuming application's queueing, retry, and rate-limit design. The changelog is silent on timeout/retry/backoff configuration, which suggests that remains an application/SDK concern. If your traffic profile is bursty (checkout spikes, batch settlement), confirm the SDK's connection pooling and retry semantics rather than assuming the package handles them. Adding the HTTP-verb tests for AppDispatcher is a modest positive signal for request-construction correctness, but it is construction-level, not load-level, testing.

Failure modes to watch:

• Silent wire-level regression via SDK 3.0 — succeeds at install, fails at settlement. Detected only by sandbox parity testing.
• Analyzer gate failures from corrected docblocks — CI blocks the upgrade even though runtime is fine. Pre-warn the team; expect a short triage session.
• Composer resolution deadlock in monorepos where another package pins SDK 2.x.
• Untested lower PHP bound — a defect surfaces only in the subset of services on 8.2/8.3.
• Unnoticed 2.x EOL for deferred services, creating a security-patch gap with no upgrade path that doesn't start with a framework upgrade.
• Unstated retry/error semantics — duplicate or dropped payment operations under partial failure; validate idempotency assumptions explicitly.

Ramp-up: Negligible for developers. The API is identical to 2.x, so existing code, docs, and muscle memory all transfer. Onboarding cost is procedural, not conceptual: document the version floor (PHP 8.2 / Laravel 10 / SDK 3.0), the pinned constraint, and the sandbox-validation step in the payment-flow runbook. One caveat for new team members — the package's docblocks were previously malformed and are now corrected, so anyone who learned the types from IDE hints in 2.x should re-check signatures against the 3.0 source rather than trusting stale autocomplete.

Recommendation: Adopt v3.0.0 — it is a low-code-risk, dependency-hardening release with a clear upgrade story. Gate adoption on two things this changelog cannot answer: engine-phpsdk 3.0 wire compatibility, and the 2.x support window for services that must defer.