- How do I install masterix21/laravel-entitlements in a Laravel application?
- Install it with composer require masterix21/laravel-entitlements, then publish the package config and migrations and run php artisan migrate. Translations and the Filament plugin assets can be published optionally if you need them. No queue, service mesh or external service is introduced, so setup is standard Laravel package mechanics. Check the composer constraints for the supported Laravel and PHP versions before installing into an older application.
- What are plans, features, licenses and usages in laravel-entitlements?
- Plans are composed of typed items such as slot or computed features, and a license is the unit of allocation that ties a plan to a user, team or other Eloquent model. Usages are the consumption records that track how much of a limited feature has been used. PlanTransition acts as the state machine for upgrades, downgrades and cancellations, so entitlement state stays auditable instead of being recomputed ad hoc. This model fits seat-based and metered feature gating in SaaS products.
- How do I check if a user or team can access a feature?
- Attach features to a plan, assign a license to the model, then use the package's expressive API to check access before running the gated code path. The check tells you whether the entitlement exists and whether a limited feature still has remaining capacity. Because it reads persisted license and usage records, it is safe to call from controllers, policies, middleware or jobs. Keep the gate in one place, such as a policy or helper, so gating rules stay consistent across the application.
- How do I consume limited usage or track quotas with this package?
- Call the consumption API on the licensed model to record usage against a limited feature and the amount consumed. Slot consumption is guarded by re-check-and-lock logic so concurrent requests do not over-consume the same slot. In 1.3.1, forceRelease() decrements slot_used by the recorded usage amount instead of always by one, so reporting built on the previous behaviour should be re-baselined. Wrap consumption in a transaction when a single request touches several features.
- How do I upgrade or downgrade a plan for a license?
- Use changePlan() to move a license between plans, with PlanTransition recording the upgrade, downgrade or cancellation. In 1.3.1 the anchor license is locked during changePlan() and slot operations are re-checked under lock, which reduces race conditions but serialises plan changes for a license group. Heavy concurrent plan changes on the same anchor license will therefore queue on that row lock. Test upgrade and downgrade flows under load, since lock ordering between changePlan() and slot operations remains a deadlock surface.
- Is there a Filament plugin for managing plans and entitlements?
- Yes, the package ships a first-class Filament plugin for plan management, plan changes and force-release operations. It is a strong fit if your admin panel already standardizes on Filament; if your admin tooling is custom-built, skip the plugin and use only the core entitlement service. The plugin constrains filament-badgeable-column to ^4.0 in 1.3.1, so projects that pinned the transitive dependency at a Filament 3-compatible version may hit a composer conflict.
- The migration failed on a unique index for entitlement_plan_items. What should I do?
- Version 1.3.1 adds a unique index on entitlement_plan_items (plan_id, type) to enforce a database-level invariant. The migration fails if the table already contains duplicate rows for the same plan and item type, which is plausible in databases created before the Filament repeater validation existed. Query for the duplicates, merge or delete the redundant rows, then re-run the migration. Treat this as a one-way door and remediate the data before deploying to production.
- When are laravel-entitlements domain events dispatched?
- Since 1.3.1, domain events are dispatched inside DB::afterCommit, so listeners run only after the surrounding transaction commits successfully. Listeners are not invoked at all when the transaction rolls back, which is the correct behaviour but a silent change for any listener that previously read uncommitted state or fired side effects. Review all listeners that touch entitlement records. If you need pre-commit behaviour you must handle it in your own code rather than relying on the package.
- Can I customize the models and translations used by laravel-entitlements?
- Yes, the package exposes configurable models via entitlements.models.* plus a typed type_enum with label resolution, so you can extend behaviour without forking. In 1.3.1 translations must live under lang/vendor/laravel-entitlements/; customized copies left in the application root lang/ directory are silently ignored and produce untranslated UI rather than an error. Move any customized translation files to the vendor path during the upgrade. Publishing the config and migrations is the normal starting point for customization.
- How should I test feature gating and entitlements in my Laravel test suite?
- The package's own suite grew from 126 to 135 tests with 433 assertions and explicit regression tests for each 1.3.1 fix, which is a reasonable baseline to mirror. In your app, create plans and licenses during test setup, then assert access, consumption and force-release outcomes against the real service rather than mocking the package. Include tests that run consumption and changePlan() inside transactions so the post-commit event behaviour is exercised. Concurrency regressions are the hardest class to catch in a unit suite, so add at least one test that simulates parallel slot consumption.