The Entitlements API lets you answer the question “what is this subscriber allowed to do?” without writing any plan-inspection logic yourself. It reads the features JSON on the billable’s active plan and exposes typed accessors for boolean flags, numeric limits, and arbitrary values. You can also aggregate entitlements across multiple named subscription slots, which is essential when a user holds both a base plan and an add-on plan simultaneously.
Getting an entitlement checker
use Pixelworxio\Subscribd\Facades\Subscribd;
$ent = Subscribd::entitlements()->for($user);
for($billable) returns an EntitlementCheck scoped to the billable’s default subscription. For multi-slot aggregation, use forAll() instead (see below).
Core methods
allows()
Returns true if the feature is enabled on the current plan.
$ent->allows('api_access'); // bool — feature flag check
$ent->allows(Report::class); // same, using a model FQCN
$ent->allows('support', 'priority'); // value comparison — true if feature equals 'priority'
limitOf()
Returns the numeric limit for a feature, or null when the plan grants unlimited access.
$ent->limitOf('projects'); // int|null (null = unlimited)
value()
Returns the raw value stored for a feature key, useful for non-boolean, non-numeric feature properties.
$ent->value('support'); // mixed — e.g. 'email', 'priority', 'none'
remaining()
Returns how many units of a limited feature the billable can still consume, based on recorded usage. Returns null when the limit is unlimited.
$ent->remaining('reports', $user); // int|null
remaining() reads from feature usage records populated by TrackFeatureUsage. This is distinct from metered billing usage reported by RecordUsage, which feeds into gateway invoices.
Aggregating across multiple subscriptions with forAll()
When a billable holds more than one active subscription (for example, a base plan and an add-ons slot), use forAll() to aggregate entitlements across all of them.
// True if any active plan grants the feature
Subscribd::entitlements()->forAll($user)->allows('reports');
// Sum of all numeric limits; null if any plan has unlimited
Subscribd::entitlements()->forAll($user)->limitOf('reports');
Use forAll() in authorization checks when you sell modular add-on plans that unlock additional features on top of a base subscription.
Gating a controller action
abort_unless(
Subscribd::entitlements()->for($user)->allows('api_access'),
403,
);
Registering feature mappings with FeatureMap
Feature keys can be a raw string, a model fully-qualified class name, or a registered alias. You register mappings once in AppServiceProvider::boot().
use Pixelworxio\Subscribd\Pricing\FeatureMap;
app(FeatureMap::class)
->map(Report::class, 'reports') // FQCN → feature key
->alias('report', 'reports'); // short alias → feature key
Subscribd::entitlements()->for($user)->allows('reports');
Subscribd::entitlements()->for($user)->allows(Report::class);
Subscribd::entitlements()->for($user)->allows('report');
Tracking feature usage with TrackFeatureUsage
TrackFeatureUsage records consumption of feature-limited resources (not metered billing). Use it any time a user creates a resource that counts against a plan limit.
use Pixelworxio\Subscribd\Actions\TrackFeatureUsage;
// Increment by 1
app(TrackFeatureUsage::class)->increment($user, 'reports');
// Increment by a specific amount using a model FQCN
app(TrackFeatureUsage::class)->increment($user, Report::class, 5);
// Decrement by 1
app(TrackFeatureUsage::class)->decrement($user, 'reports');
// Reset usage to zero (e.g., at billing period start)
app(TrackFeatureUsage::class)->reset($user, 'reports');
// Read the current usage count
app(TrackFeatureUsage::class)->used($user, 'reports'); // int
TrackFeatureUsage tracks discrete feature consumption (project count, report count, etc.). For billing usage reported to a gateway, use the RecordUsage action instead.Complete EntitlementCheck reference
| Method | Return type | Description | |
|---|
allows(string $feature, mixed $value = true) | bool | Feature flag or value comparison | |
limitOf(string $feature) | `int | null` | Numeric limit; null = unlimited |
value(string $feature) | mixed | Raw feature value from plan JSON | |
remaining(string $feature, Billable $billable) | `int | null` | Unused units; null = unlimited |
