Laravel Entitlements Laravel Package

Product Decisions This Supports

• Plan catalog and packaging design. Plans are composed of items with a type; 1.3.1 makes "one item per type per plan" a database invariant and prevents duplicate type selection in the Filament form. PMs can now treat the plan catalog as authoritative — no ambiguous or double-configured entitlements leaking into pricing pages, quotes, or customer-facing feature matrices.
• Seat/slot-based packaging and usage monetization. The slot accounting fixes (requestRelease() lock-and-recheck, forceRelease() decrementing by usage amount) mean slot_used can be trusted for enforcement, dashboards, and upsell triggers. This is the difference between shipping a seat-based tier and holding it back over "our numbers might be wrong" risk.
• Self-serve upgrades and downgrades. Concurrent changePlan() locking, upfront rejection of transitions to empty plans, and downgrade validation against computed usage (including computed types) turn plan changes into a supportable product surface rather than a source of Failed transitions and manual cleanups.
• Support/CS tooling scope. The Filament fixes (force release across the whole license group, guarded single/bulk plan deletion, current plan visible in change-plan, TransitionAlreadyResolved surfaced as a notification) let you delegate entitlement operations to support without engineering babysitting or 500s.
• Integration and lifecycle roadmap. Domain events now dispatch after commit and never on rollback. That is the precondition for committing to webhooks, provisioning, notifications, and analytics without dual-write or reconciliation work — a roadmap unblock rather than a feature.
• Build vs buy and onboarding cost. Shipped Laravel Boost AI guidelines plus an expanded README (transition config keys, four transition events, full exceptions reference) reduce the cost of getting an internal or AI-assisted team productive on the package, which materially shifts the build-vs-buy math in favor of buying.
• Billing-adjacent decisions. nextBillingAt() now returns ends_at for non-recurring plans instead of projecting a phantom billing period — keep this package as the entitlement source of truth and keep invoicing elsewhere; don't let it imply recurring billing behavior it doesn't own.

When to Consider This Package

Consider it when most of these hold:

• You are on Laravel and need plans, licenses, entitlements, and slot/seat consumption modeled in-app — especially if you are replacing a homegrown set of plans/features/licenses tables.
• You need plan transitions (upgrade/downgrade/mid-cycle changes) with validation and a pending-transition model, not just static feature flags.
• You already run Filament for back-office admin, or plan to — a large share of 1.3.1's value is in the admin plugin.
• Downstream systems should react to entitlement changes (provisioning, CRM, analytics), and you want post-commit event guarantees rather than transactional listeners.
• You can accept the operating chores: publishing and running migrations, and adopting the standard lang/vendor/laravel-entitlements/ translations path.

Look elsewhere or defer when:

• You are not on Laravel, or you need a full billing engine — invoicing, tax, dunning, payment retries. This package enforces entitlements; it does not bill.
• You need high-volume, real-time metered usage aggregation. Slot accounting here is correctness-focused, not a streaming metering pipeline.
• You cannot run a schema migration against existing data. The new unique index on entitlement_plan_items (plan_id, type) will fail on dirty data, so existing catalogs need a dedupe pass first.
• Your roadmap depends on deep model or translation overrides — 1.3.1 improved entitlements.models.* honoring across service and strategies, but this remains a package you conform to.
• You need vendor SLA/commercial support. This is community OSS with a fast patch cadence; you need in-house Laravel maintenance capacity.
• You are on an older release and unwilling to upgrade: earlier slot release races and concurrent changePlan() could double-decrement or leave two pending transitions. Treat 1.3.1 as the minimum viable version for anything customer-visible.

How to Pitch It (Stakeholders)

For executives: this is a low-cost patch that hardens a package we would otherwise have to build and maintain ourselves — plan catalog, seat entitlements, and self-serve plan changes. 1.3.1 specifically removes correctness risk in concurrency and event timing (the two areas that produce billing-visible bugs and support tickets), adds database-level guardrails instead of relying on UI discipline, and ships AI-assistant guidelines that shorten onboarding. No public API breaks; the upgrade is an ops task, not a rewrite: republish migrations, run them, move customized translations to the vendor path, and validate existing plan data for duplicate item types before migrating.

For engineering: patch release, no deprecations or signature breaks. Changes that require action or review: (1) new migration and unique index — dedupe plan items first, then vendor:publish --tag="entitlements-migrations" and migrate; (2) domain events now fire via DB::afterCommit and are skipped entirely on rollback — audit existing listeners for reliance on in-transaction state or on rollback-time side effects; (3) translations moved to lang/vendor/laravel-entitlements/; (4) filament-badgeable-column pinned to ^4.0, fixing prefer-lowest builds that resolved a Filament 3 release and broke table rendering; (5) entitlements.models.* overrides are now honored consistently, which can change query behavior if overrides were partially effective before. Test suite is at 135 tests / 433 assertions with regressions for each fix. Recommended sequencing: upgrade → validate data → migrate → run suite → verify listeners → confirm admin panel flows (force release, plan delete guards, change plan).