Download the PHP package saadmajeed/laravel-entitlements without Composer

Laravel Entitlements

A feature/entitlement engine for Laravel 11, 12, and 13. Define plans, features, limits, metered usage, and conditional access rules — then check them anywhere in your app.

Features

• Boolean features — on/off feature flags per plan
• Numeric limits — caps like "max 5 projects"
• Metered usage — countable consumption with daily/monthly/yearly resets
• Time-based entitlements — features that expire after a date
• Conditional entitlements — access gated by subject attributes (role, region, etc.)
• Plan inheritance — child plans inherit values from parent plans
• Per-subject overrides — override plan values for individual users
• Audit logging — tracks changes to entitlements, plans, and overrides
• Caching — resolution cache with configurable TTL (defaults to the array store; set ENTITLEMENTS_CACHE_STORE for production)
• Fluent definition API, Facade, Middleware, Blade directive

Installation

Publish the config and migrations:

Or run everything in one step:

Configuration

See config/entitlements.php for all options:

Quick Start

1. Add the trait to your subject

The HasPlan trait adds a plan() relationship and convenience methods.

2. Create a plan

Assign the plan to a user:

3. Create entitlements

4. Assign values to a plan

4b. Define a plan fluently (recommended)

The manual steps above are fine, but the fluent Entitlements facade hides the pivot-format details and keeps your seeding idempotent:

You can also pass a callback instead of chaining:

Entitlements::plan() finds-or-creates the Plan and each referenced Entitlement, then updates the per-plan pivot value on every run — so it is safe to call from a seeder over and over. A full example plan tree lives in database/seeders/EntitlementsSeeder.php.

Removing entitlements

To revoke an entitlement from a plan, detach it (the global Entitlement row is kept so other plans can still use it):

5. Check entitlements

value() is a convenience getter for the resolved value of why($key)->value. consume() is an alias of use() for recording metered/limit usage.

Entitlement Types

Boolean

Simple on/off feature flag. The pivot value should be ['enabled' => true] or ['enabled' => false].

Limit

A numeric cap. The value is a number or ['max' => N].

Metered

Countable usage that resets on a period (daily, monthly, yearly).

Soft limits

Set soft_limit: true in the entitlement's metadata to allow usage beyond the limit (fires event instead of throwing):

An LimitReached event is fired, but the use() call succeeds.

Time-based

A feature that expires at a specific date.

If expired, an ExpiredEntitlementException is thrown.

Conditional

Access depends on subject attributes.

Supported operators: =, ==, ===, !=, !==, <>, >, >=, <, <=, in, not_in, contains.

Security: by default conditional rules may read any subject attribute. To restrict which attributes rules may reference, set conditional.allowed_fields in config/entitlements.php. When the allowlist is non-empty, any rule referencing a field outside it causes that conditional entitlement to be denied ("deny unknown"). You can also provide a custom conditional.attribute_resolver (a class implementing SaadMajeed\Entitlements\Contracts\AttributeResolver) to control how attribute values are read.

Config

A generic configuration value (always allowed, returns the raw value).

Plan Inheritance

Plans can have a parent. Child plans inherit entitlement values from the parent unless overridden.

The resolution pipeline checks:

1. Per-subject override (if any)
2. Expiry (for time-based)
3. Conditional rules
4. Subject's direct plan value
5. Parent plan chain (walk up)
6. Entitlement's default value

Overrides

Override an entitlement for a specific subject:

Overrides have the highest priority in the resolution pipeline. They can optionally expire.

Caching

Entitlement decisions are cached per subject per key. The cache is automatically invalidated when:

• An override is created, updated, or deleted (OverrideApplied event)
• A subject's plan changes (PlanChanged event)
• Usage is recorded (UsageRecorded event)

Manually flush the cache:

Warm the cache:

Events

Listeners are auto-registered to invalidate the cache on OverrideApplied, PlanChanged, and UsageRecorded.

Usage Tracking

Usage is recorded synchronously and atomically — no queue, no background jobs. When you call use(), a single database transaction:

1. Acquires a per-entitlement named advisory lock (serializing concurrent consumers on MySQL/PostgreSQL),
2. Inserts the UsageRecord row,
3. Reads and increments the UsageSummary for the current period inside a SELECT ... FOR UPDATE row lock,
4. Checks the limit (hard limit rejects with LimitExceededException; soft limit records but fires LimitReached),
5. Commits — and only then fires the LimitReached event outside the transaction.

Because the read-modify-write of the summary happens under a lock within one transaction, there is no double-counting and no lost update even under high concurrency.

For real-time accuracy, you can query remaining usage directly:

Concurrency

Usage recording is safe under concurrency on MySQL and PostgreSQL, where it uses a named advisory lock plus SELECT ... FOR UPDATE row locking, with automatic retry on deadlock (up to 3 attempts). SQLite is single-writer, so it is also safe but does not exercise the lock paths. The package ships with a parallel-consumer test (tests/Concurrency) that is run against real MySQL/PostgreSQL in CI.

API Reference

Entitlement::for($subject)

Returns a cloned EntitlementManager scoped to the subject.

Entitlements facade (defining plans)

The returned PlanBuilder exposes feature(), limit(), meter(), conditional(), time(), and parent() — all chainable and idempotent — plus remove(), removeMany(), only() (keep only the given keys), and withoutParent(), for revoking entitlements and clearing inheritance.

HasPlan trait methods

Decision object

Explanation object (from why())

A detailed trace of how an entitlement was resolved, including:

• The resolution steps and their results
• Plan info (id, name, slug)
• Override info (value, expires_at, reason)
• Expiry info (expires_at, expired)
• Usage info (used, limit, remaining)

Artisan Commands

The subject argument accepts ModelClass:id syntax (e.g. User:1, App\Models\User:42).

entitlement:explain prints the same resolution trace as why() but in a readable form — the final result (ALLOWED / DENIED), the source, plan, override, expiry and usage details, and the ordered resolution steps. Pass --json to get the raw Explanation as JSON (identical to entitlement:check).

Middleware

Protect routes with the entitlement middleware:

If the subject (authenticated user) doesn't have the entitlement, the middleware aborts with 403 (or redirects if a redirect path is provided).

Blade Directive

Requires the user to be authenticated.

Exceptions

Extend your exception handler to map these to HTTP codes as needed:

Testing

The suite runs against SQLite by default:

Concurrency tests (parallel consumers, advisory/row locking) run against real MySQL / PostgreSQL and are isolated in their own process:

The CI matrix covers Laravel 11, 12, and 13 across MySQL 8.4 and PostgreSQL 16.