← Larameter 12 / 12

Reference

Traits

Brings
Concerns\HasCredits credits(), meterAccount() Required. Enough alone for an application that sells bundles.
Concerns\HasPlans plan(), forgetPlan(), setPlanProviders(), flushPlanProviders() For accounts that can be on a plan.
Concerns\HasMeters quota(), meter(), flushRegisteredMeters() For plans that cap how many of something may exist.

$model->credits()

Asking
allows(string|int $what = 1) Enough for that many credits, or for what that action costs.
price(string $operation) Fixed price. Unpriced actions are free.
meterPrice(string $op, int $in, int $out = 0) What a metered call would cost, uncharged.
remaining() Headroom plus purchased credits.
headroom() The plan only, tightest window.
allowanceIn(string $window) What the plan grants there.
in(string $window) One WindowUsage. Throws if the window is not declared.
windows() Every declared window, keyed.
resetsAt() When spending is possible again, or null.
account() The Account row, created on first sight.

Writing
charge($operation, ?$actor, ?$subject, ?int $credits, array $metadata) Fixed price. Returns a UsageRecord.
meter($operation, $unit, $in, $out = 0, ?$actor, ?$subject, array $metadata) Priced per unit. Returns a UsageRecord.
deposit(int $credits, string $reason = 'purchase', ?$source, ?string $note, array $metadata) Credits in. Negative allowed. Returns a Deposit.
setPlan(?string $handle) Store a plan on the account. Fallback, not the source.

Querying
records() Eloquent builder over this account's usage.
deposits() Eloquent builder over this account's deposits.

$model->plan()

Returns a Plan, never null.
->handle 'pro', or '' when there is none.
->name Display name, falling back to the handle.
->price Whatever unit you wrote it in. Never charged.
->exists False when no provider answered.
is(string $handle)
allows(string $feature) Absent means off.
limit(string $resource) Absent means unlimited (-1).
credits() The whole allowance, before any window narrows it.
creditsIn(string $window) That figure times the window's share.
get(string $key, $default = null) Anything else in the definition, dot notation.
toArray() The raw definition.

Plans::all(), Plans::exists($handle), Plans::find($handle) reach the catalogue. Plans::UNLIMITED is -1.

$model->quota()
allows(string $handle, int $additional = 1) Unmetered resources are unlimited.
get(string $handle) The Meter, or null when unmetered.
all() Every meter, keyed by handle.
summary() ['handle', 'label', 'count', 'limit'] rows.

Meter

Extend EduLazaro\Larameter\Meter, not the contract: an implementation also needs a public $handle, which an interface could not declare before PHP 8.4.
public string $handle Matches the key under limits. Derived from the class name if empty.
count(): int Abstract. How many exist right now.
label(): string Str::headline($handle) unless overridden.
limit(): int The plan's ceiling. -1 unlimited.
fits(int $additional = 1): bool
toArray(): array

Declared with protected array $meters, #[MeteredBy(Class::class)], or Model::meter(Class::class). Interchangeable, and declaring one twice does not double it.

WindowUsage

Read-only. Reading never opens a window.
->key
allowance()
used() Zero for an expired window: reported full, not restarted.
remaining() PHP_INT_MAX when unlimited.
isUnlimited()
percentUsed() 0.0 when unlimited or when the allowance is zero.
startedAt() / endsAt() Carbon, or null when no window is running.
toArray()

UsageTracker

Bound scoped. Most applications never touch it.
charge(...) / meter(...) The same as through credits(), with the model first.
priceOf($op) / meteredPriceOf($op, $in, $out)
account($model) / headroom($model) / remaining($model) / allowanceIn($model, $w)
hasCredits($model, $credits = 1)
hasCreditsMemoized($model, $credits = 1) Once per instance. Does not see later spending, by design.

Contracts
Contracts\Meter label, count, limit, fits, toArray.
Contracts\PlanProvider provide(Model $model): ?Plan. Null lets the next provider answer.

Shipped providers: ForcedPlanProvider, CashierPlanProvider, StoredPlanProvider.

Config keys

Default
windows session, weekly, monthly Each takes minutes, hours, days, months, anchor, share. Empty opts out of allowances.
plans one free tier
default_plan 'free' null for none.
plans_from 'larameter.plans' Point it at your own file.
credits_key 'credits_monthly' May name a nested key.
plan_providers forced, cashier, stored The order is the policy.
override_column null Read by ForcedPlanProvider. Null switches it off.
price_id_key 'stripe_price_id'
subscription_type 'default'
prices empty By action name. Unlisted is free.
rates empty input and output per million units. '*' is the fallback. Indexed directly, not by dot notation.
fallback_units_per_credit 100 So metering an unknown model is not free.

Window anchors
rolling The next window starts on the next charge after the old one expired. Full length always available.
fixed A grid laid down from the first window, moving on whether it is used or not. The default.

Commands
php artisan make:meter <Name> [Model] Generates into App\Meters\<Model>.
php artisan vendor:publish --tag=larameter-config
php artisan vendor:publish --tag=larameter-migrations

Defaults worth remembering
An action you never priced Free.
A metered unit you never priced Costs fallback_units_per_credit.
A features key you never listed Off.
A limits key you never listed Unlimited.
A resource with no meter Unlimited.
No allowance figure on a plan No credits.
No windows declared No allowance metering. Purchased credits only.
-1 anywhere Unlimited, which is not 0.
PreviousThe data model

built and maintained by Edu Lazaro · MIT license