Download the PHP package onaonbir/oo-subscription without Composer

OO-Subscription

A backend-only subscription management package for Laravel. Built by OnaOnbir.

Supports polymorphic subscribables, immutable subscription rows, multi-language content, multi-currency pricing, feature usage tracking with overage billing, and a pluggable payment gateway contract.

• PHP 8.2+
• Laravel 11 / 12
• Primary Keys: ULIDs on all models
• Polymorphic: Works with any model via morphTo (User, Team, etc.)
• Immutable Rows: Renewals and plan changes create new subscription rows
• Multi-language: JSON fields for slug, name, and description
• Multi-currency: JSON prices field on plans, per-currency overage pricing

Table of Contents

• Installation
• Configuration
• Models
• Enums
• HasSubscriptions Trait
• Actions
• State Guards
• Events
• Feature Types
• Plan Snapshots
• Overage Pricing
• Direct Feature Assignments
• Usage Cycle Reset
• Payment Gateway Integration
• Model Customization
• Table Customization
• Scheduled Commands
• Authorization
• Testing
• Quick Start
• License

Installation

Publish the configuration and migrations:

The service provider (OnaOnbir\Subscription\SubscriptionServiceProvider) is auto-discovered.

Configuration

The config file is published to config/subscription.php.

Models

The package provides 7 models. All use ULIDs as primary keys.

Plan

Represents a subscription plan with multi-language fields and multi-currency pricing.

Relationships: features() (BelongsToMany), planFeatures() (HasMany), subscriptions() (HasMany)

Uses SoftDeletes.

Feature

Represents a capability that can be attached to plans or assigned directly.

Uses SoftDeletes.

Subscription

An immutable record of a subscribable's subscription to a plan.

Methods: isActive(), isTrialing(), isPastDue(), isCanceled(), isExpired(), isValid(), onTrial(), onGracePeriod(), hasCancelScheduled(), isLifetime(), resolveCurrency(?string $override): string

PlanFeature (Pivot)

Pivot model connecting plans to features with plan-specific values.

SubscribableFeature

Direct feature assignment to a subscribable, independent of any plan.

Scopes: scopeCurrentlyValid() -- filters to features within their validity window.

FeatureUsage

Tracks current usage of a feature within a billing cycle.

UsageRecord

Immutable audit trail of individual usage events.

Enums

BillingInterval

Monthly, Yearly, Lifetime

Methods: addToDate(Carbon $date): ?Carbon -- calculates the next period end date.

SubscriptionStatus

Active, Trialing, PastDue, Canceled, Expired

Methods: activeStatuses(): array -- returns [Active, Trialing, PastDue].

FeatureType

Boolean, Quantity, Metered

HasSubscriptions Trait

Add to any Eloquent model to make it subscribable:

Subscription Methods

Feature Methods

Actions

All actions are resolved from the container and follow an immutable pattern.

CreateSubscription

• Creates a subscription with an immutable plan snapshot.
• Sets status to Trialing if plan.trial_days > 0, otherwise Active.
• Guard: Throws DuplicateSubscriptionException if the subscribable already has an active subscription for the same plan.
• Dispatches SubscriptionCreated and SubscriptionActivated (if no trial).

CancelSubscription

• Guard: Throws InvalidSubscriptionStateException if subscription is already canceled or expired.
• Dispatches SubscriptionCanceled.

RenewSubscription

• Creates a new subscription row (immutable pattern).
• Guard: Throws InvalidSubscriptionStateException if subscription is not valid (canceled/expired).
• Dispatches SubscriptionExpired and SubscriptionRenewed.

ChangePlan

• Guard: Throws InvalidSubscriptionStateException if subscription is not valid.
• Dispatches SubscriptionCanceled and PlanChanged.

RecordFeatureUsage

• Validation: Amount must be >= 1, feature must exist, feature must not be boolean type.
• Atomicity: Uses DB::transaction() with lockForUpdate() to prevent race conditions.
• With overage pricing: allows exceeding the limit.
• Without overage pricing: throws FeatureLimitExceededException.
• Dispatches UsageRecorded, FeatureLimitReached, and BillingCycleCompleted when applicable.

State Guards

Actions validate subscription state before executing. Invalid operations throw typed exceptions:

Events

Feature Types

Boolean

The subscribable either has the feature or does not. No usage tracking.

• Value: 'true' or 'false'
• Example: "Priority Support", "Code Editor"

Quantity

A limited number of items per billing cycle.

• Value: Numeric string (e.g., '100'). null = unlimited.
• Example: "10 S3 Connections", "500 Monthly Transfers"

Metered

Pay-as-you-go with an optional included amount.

• Value: Numeric string (included amount). null = unlimited included.
• Overage: When overage_prices is set, usage beyond the included amount is billed per unit.

Modeling Protocols (Boolean + Quantity Pattern)

For capabilities with both an on/off toggle and a numeric limit, use two features:

Then in your plan:

Check in your application:

Plan Snapshots

Each subscription stores an immutable snapshot of the plan at creation time. Plan changes never retroactively affect existing subscriptions.

Overage Pricing

• With overage pricing: Usage beyond the limit is allowed.
• Without overage pricing: FeatureLimitExceededException is thrown.
• Plan limits and direct feature limits are additive.

Direct Feature Assignments

Assign features directly to a subscribable without requiring a plan:

Direct feature limits are additive with plan limits.

Usage Cycle Reset

For resettable features, the used counter resets to 0 when the billing period expires. A BillingCycleCompleted event is dispatched on reset.

Payment Gateway Integration

This package manages subscription state -- it does not process payments. Implement the PaymentGateway contract in your application:

Register in config/subscription.php:

Webhook handling is your responsibility. Create your own webhook controller and call the package's Actions directly.

Model Customization

Swap any model by extending the base class and updating the config:

Table Customization

Override table names in the config:

Scheduled Commands

subscription:process

Processes all pending lifecycle transitions:

Supports --expired, --trials, --grace, --cancellations, --usage-reset, and --dry-run flags.

subscription:status

Displays a status report with subscription counts and pending warnings.

Authorization

This package does not include authorization policies. You are responsible for implementing gates, policies, or middleware to control who can subscribe, cancel, change plans, etc.

Testing

Quick Start

License

MIT - See LICENSE for details.

Built with care by OnaOnbir.