Engine Laravel Helper Laravel Package

Product Decisions This Supports

• Platform upgrade sequencing (PHP/Laravel roadmap). v6.0.2 is the first release in the 6.x line that is verified against PHP 8.2–8.5 and Laravel 10/11/12 with Passport 11/12. This package is therefore no longer the blocker for a PHP 8.5 / Laravel 12 migration — but it is the trigger: adoption of the framework upgrade and adoption of this package release must be scheduled as one workstream, not two.
• Multi-tenant correctness (data isolation). The tenant global scope (Scopes\Tenant, BelongsToTenant) now qualifies the filter as tabela.tenant_id, fixing DB-level "ambiguous column" failures on JOINed queries (e.g. _fields=orders->code). This is a functional defect on any tenant-scoped listing/reporting endpoint — a PM should treat it as a bug-fix justification for the upgrade rather than an optional improvement.
• Multi-registry tenants (integration breadth). Services\Tenant\Updater now always writes engine_api_access_token to the engine registry, and the NFe TaxInvoice\Indexer prefers the nfe registry. This confirms multi-registry-per-tenant is a supported topology — relevant if the roadmap includes tenants with more than one ERP/engine connection, or mixed NFe + non-NFe tenants. Previously these credentials silently landed on "the first registry," which is a misconfiguration class of bug, not a crash.
• Build vs buy. This is vendor-supplied integration glue to the Betalabs Engine backend, covering regulated domain logic (NFe tax invoicing, tenant registry, OAuth via Passport). Do not rebuild — the value is in the maintained contract with the Engine API (betalabs/engine-phpsdk ^3.0), not the code volume.
• Release hygiene as a gate. The v6.0.0 tag points at stale code; v6.0.2 supersedes the whole 6.x line. Any decision to adopt must include exact-version pinning and a lockfile audit, not a ^6.0 constraint.

When to Consider This Package

Adopt when all of the following hold:

• The product is a multi-tenant SaaS whose domain requires NFe/tax-invoice emission or ERP integration through the Betalabs Engine platform.
• The application is on PHP ≥ 8.2 and Laravel 10, 11, or 12, with Passport 11 or 12 as the auth stack.
• You can absorb the 5.x → 6.x breaking changes as a discrete migration: PHP floor raised to ^8.2, engine-phpsdk raised to ^3.0, package routes registered in bootstrap/app.php (Laravel 11/12), removal of Passport::routes() calls, and publishing passport-migrations on databases that lack the oauth_* tables.
• You need the tenant-scope JOIN fix or the multi-registry credential fix — i.e. you are currently blocked by ambiguous-column errors or by tokens being written to the wrong registry.

Look elsewhere / defer when:

• You are on PHP 8.1 or engine-phpsdk 2.x — stay on the 5.x line; 6.x is not available to you and 5.x has now diverged (note the tenant-scope hotfix exists there separately as v3.0.2-equivalent behaviour).
• You are not on Betalabs Engine — the tenant/registry model and NFe services are Engine-specific and carry no reuse value.
• You do not use Passport for API auth; the 6.x line is explicitly coupled to Passport 11/12 configuration, guards, and migrations, so the migration cost is paid without benefit.
• Your risk tolerance does not accommodate a vendor whose test suite was non-functional from v4 through v6.0.x. The suite is restored (45 tests, 158 assertions) and CI now runs on PRs, but that is a recovery signal, not a maturity signal — 45 tests is thin coverage for tenant scoping plus fiscal document generation.
• You need capabilities not evidenced in this release: there are no new features here, only compatibility, correctness, and test/doc restoration.

How to Pitch It (Stakeholders)

To executives: v6.0.2 is a stabilization release for our Betalabs Engine integration, not a feature release. Its business value is twofold: it unblocks our PHP 8.5 / Laravel 12 upgrade path, and it fixes a real multi-tenant correctness bug where JOINed tenant-scoped queries (reporting and order listings) could be rejected by the database. It also fixes credential placement for tenants with more than one registry, which removes a silent misconfiguration risk for our more complex accounts. Cost is a bounded migration sprint, gated on our PHP floor being at 8.2 or above.

To engineering: treat this as a planned migration, not a version bump. Scope: raise PHP to ^8.2 and engine-phpsdk to ^3.0; register the package routes in bootstrap/app.php and delete any Passport::routes() calls; publish passport-migrations where oauth_* tables are absent; pin the dependency to exactly v6.0.2 (the v6.0.0 tag references stale code — do not trust floating constraints). Verify the tenant-scope fix against at least one real JOINed query in our codebase, and confirm behaviour for tenants with multiple registries. Also note the vendor's test suite was broken from v4 onward and has only just been repaired — we should compensate with our own integration coverage around tenant isolation and NFe indexing rather than relying on upstream tests.