Engine Laravel Helper Laravel Package

Technical Evaluation

Architecture fit

• The package is a Laravel service-layer wrapper around betalabs/engine-phpsdk ^3.0, exposing two capability clusters: multi-tenant identity/registry management (Scopes\Tenant, Models\BelongsToTenant, Services\Tenant\Updater) and Brazilian fiscal document handling (Services\NFe\TaxInvoice\Indexer).
• It assumes a specific application topology: a shared-schema, tenant_id-scoped database, OAuth2 via Laravel Passport, and an upstream "Engine" API as the system of record for credentials and fiscal operations. This is not a general-purpose utility — it is opinionated infrastructure glue.
• Fit is strong only if we are already (or are deliberately committing to) the Betalabs Engine ecosystem. It is a poor fit as a standalone tax-invoice abstraction, since the fiscal logic lives behind engine-phpsdk, not in this package.
• Runtime envelope is deliberately aggressive: PHP 8.2–8.5 (tested on 8.5), Laravel 10/11/12 (target 12), Passport 11/12. The 8.5 target is ahead of typical production fleets and should be read as the vendor's CI environment, not a recommendation.

Integration feasibility

• Installation is conventional Composer + service provider + route registration. The Laravel 11/12 route-registration change (routes declared in bootstrap/app.php instead of the package's service provider) is the only non-obvious wiring step.
• Passport 11+ removes Passport::routes(), so any existing bootstrap or provider code calling it must be deleted — this is a code-path change we must own, not something the package can fix for us.
• Passport 12 may require publishing oauth_* migrations if the target database predates them; this is a schema-mutating step on a live auth table set and needs a change window.
• Feasibility is high, but the package is a hard transitive dependency on a vendor platform. Any evaluation should treat engine-phpsdk version policy as part of the package's risk surface, not as an implementation detail.

Technical risk

• Release engineering red flag (high): the notes state the v6.0.0 tag points at old code and that v6.0.2 supersedes the entire 6.x line. A mistagged major release in a package that touches credentials and fiscal documents means we must pin exact versions (6.0.2), commit composer.lock, and verify the installed artifact rather than trusting a range constraint.
• Test-suite credibility gap (high): the suite "was broken since v4" and six tests asserted nothing. The repair is welcome and the new tests are the right ones (qualified tenant SQL with a real JOIN, multi-registry tenants, the enum), but 45 tests / 158 assertions is thin coverage for a package mediating OAuth credentials and tax document issuance. We cannot treat green CI as evidence of fiscal correctness.
• Silent behavior changes in credential routing (high): Tenant\Updater previously wrote engine_api_access_token to the tenant's first registry; it now writes exclusively to the engine registry and throws RuntimeException when that registry is absent. Tenants with multiple registries may have tokens in the wrong place today, and will start failing loudly post-upgrade. This is a data-migration problem disguised as a bug fix.
• Fiscal routing change (medium-high): NFe\TaxInvoice\Indexer now prefers the nfe registry over the first registry. In an environment where tenants hold multiple registries, this can shift which credentials sign or transmit a fiscal document. The blast radius is regulatory (rejected or misattributed invoices), not merely technical.
• Tenant scope fix (medium, security-adjacent): qualifying the global scope as table.tenant_id resolves ambiguous-column failures on JOINed queries (e.g. _fields=orders->code). The prior failure mode was a hard DB error rather than cross-tenant leakage, which is the better failure — but tenant scoping is a security boundary, and a scope that fails closed on JOINs may have driven teams to bypass it (withoutGlobalScope). We should audit for such workarounds.
• PHP 8.5 targeting (medium): if we test on 8.5 and deploy on 8.2/8.3, we are validating an environment we do not ship. Conversely, adopting 8.5 in production to match the vendor is an unscheduled platform upgrade.
• Vendor coupling (medium): engine-phpsdk ^3.0 is a major-version floor. The 5.x → 6.x boundary is defined by that dependency, so our upgrade calendar is now partly owned by the vendor.

Key questions

1. How many of our tenants have more than one registry, and how many of those lack an engine registry entirely? (Determines backfill scope and RuntimeException exposure.)
2. For multi-registry tenants, which registry currently holds engine_api_access_token, and is it the one the engine registry should own?
3. Which registry are our fiscal calls actually using today, and does the nfe-preferred routing change the signing identity for any tenant?
4. Do any of our queries rely on withoutGlobalScope to work around the pre-fix ambiguous-column errors?
5. What PHP version runs in production versus CI, and is an 8.5 move funded this cycle?
6. Is the package maintained by an internal team or the vendor, and what is the observed cadence/quality (the mistagged v6.0.0 and the multi-release broken suite suggest a small team with limited release discipline)?
7. What is the rollback story for a fiscal document issued with the wrong registry credentials?
8. Do we have a compliance requirement (NF-e audit trail) that mandates contract-level testing of the fiscal path beyond the vendor's 45 tests?

Integration Approach

Stack fit

• Route registration moves to bootstrap/app.php on Laravel 11/12; Passport::routes() must be removed from all bootstrap paths.
• Dev toolchain is Testbench 8–10 and PHPUnit 10.5/11 — relevant only if we intend to write contract tests against package internals (we should, for the registry and tenant-scope behavior).

Migration path (5.x → 6.x)

1. Pin and verify. Target 6.0.2 explicitly; do not allow ^6.0 in any manifest until the v6.0.0 tag issue is understood. Verify the installed tag/commit post-install.
2. Platform prerequisites. Ensure PHP ≥ 8.2 in the target environment and engine-phpsdk ^3.0 resolvable. If either fails, the app stays on 5.x — this is a hard gate, not a soft one.
3. Auth refactor. Delete Passport::routes() calls; register package routes in bootstrap/app.php for Laravel 11/12; publish and run Passport 12 migrations where oauth_* tables are absent. Verify the api guard config survives.
4. Registry backfill. Before enabling the new code, create/verify the engine registry for every tenant and ensure engine_api_access_token lands there. For tenants with an nfe registry, confirm the intended fiscal credential.
5. Regression pass on JOINed tenant queries. Exercise the _fields=orders->code-style eager/list endpoints that previously hit ambiguous-column errors; grep for withoutGlobalScope workarounds and retire them.
6. Cut over behind a feature flag or canary tenant set; keep 5.x releasable for at least one full billing/fiscal cycle.

Compatibility notes

• The 6.x line is a breaking change against 5.x on three axes simultaneously: language floor, SDK major, and auth wiring. Treat as a platform upgrade, not a patch bump.
• Passport 11 vs 12 is not transparent — the routes API and migration set differ. Standardize on one across environments.
• No upgrade path is offered for PHP 8.1 or engine-phpsdk 2.x; those apps are pinned to 5.x indefinitely, which is a long-term fork risk if the vendor stops backporting.

Sequencing

• Sequence the work as: pin → platform prerequisites → auth/route wiring → data backfill → tenant-scope regression → fiscal canary → full rollout.
• The registry backfill and the fiscal canary must not be parallelized with unrelated releases. Fiscal issuance failures are externally visible to customers and to the tax authority.
• If we cannot complete the backfill for all tenants, stage the rollout per-tenant rather than globally — but note the RuntimeException is a hard failure, so an un-backfilled tenant will break, not degrade.

Operational Impact

Maintenance

• Steady-state maintenance is low: no migrations of our own, no scheduled jobs, no runtime services added. The package is request-scoped glue.
• Real maintenance burden is version chase: PHP, Laravel, Passport, and engine-phpsdk all move independently, and 6.x has already demonstrated that the vendor's release quality is uneven (stale v6.0.0 tag, suite broken across four major versions).
• We should budget a recurring review cadence (per Laravel/PHP release) and own our own smoke tests for registry routing and tenant-scoped JOINs, because we cannot rely on the upstream suite to catch our specific data shapes.

Support

• Documentation improved materially in this release: README now covers requirements, Laravel 11/12 route registration, Passport 12 migrations, and an "Upgrading to 6.x" guide. That is a meaningful maturity step and reduces onboarding cost.
• Documentation is Portuguese-only, which is appropriate for the target market but is a constraint if the platform team is distributed or non-Portuguese-speaking.
• Support is effectively vendor-mediated: bugs in the fiscal path live in engine-phpsdk or the Engine API, not in this package. Our internal team can triage but not fix. Confirm the vendor SLA before this becomes a tier-1 dependency.

Scaling

• The qualified table.tenant_id scope is a performance-positive change: it makes tenant-scoped JOIN queries valid, which means they can use composite indexes on (tenant_id, ...) instead of failing or being rewritten. Verify index coverage on tenant_id for all joined tables, since the fix will enable query patterns that previously errored and are therefore unbenchmarked.
• Registry resolution now performs a lookup against a named registry rather than "first registry" — negligible cost, but confirm it is not issuing an extra API round-trip per tenant operation under load.
• Fiscal document indexing is I/O-bound against the Engine API; scaling is governed by upstream rate limits, not by this package. Capacity planning belongs with the vendor contract.

Failure modes

• The dominant risk pattern is late detection: registry-routing errors surface as fiscal rejections or delayed auth failures, not as exceptions at deploy time. Instrument a post-upgrade reconciliation of issued fiscal documents and auth success rates per tenant for the first full cycle.

Ramp-up

• Engineering ramp-up is low-to-moderate: standard Laravel idioms (service provider, global scopes, Passport) with a small surface area. A mid-level Laravel engineer is productive in under a day.
• The real ramp-up cost is domain, not code: understanding registry semantics, the engine vs nfe distinction, tenant scoping invariants, and Brazilian fiscal document lifecycle. That knowledge currently lives in the vendor's docs and this changelog, not in our codebase.
• Recommend: capture the registry model as an internal ADR, add a short runbook for "tenant has no engine registry," and write our own integration tests for the two registry-routing paths before any tenant with multiple registries is exposed.
• Overall recommendation: adopt v6.0.2, pinned exactly, gated on registry backfill and a fiscal canary — the tenant-scope and enum fixes are genuinely valuable, but the release's history argues for treating the vendor as a dependency to be verified rather than trusted.