Download the PHP package crumbls/subscriptions without Composer

Crumbls Subscriptions

A flexible plans and subscription management system for Laravel. Manage SaaS plans, features, and subscriber usage tracking without coupling to any payment provider.

Inspired by rinvex/laravel-subscriptions, which is now abandoned. This package modernizes the codebase for Laravel 11/12/13, PHP 8.3+, and current Laravel conventions.

Features

• Plan management with trial, grace, and invoice periods
• Standalone features with many-to-many plan relationships
• Per-plan feature values (e.g. Basic gets 5 users, Pro gets 50)
• Feature-based usage tracking with automatic resets
• Polymorphic subscriptions — attach to any model
• Grace period support — subscriptions stay active during grace window
• Lifecycle events — hook into created, canceled, renewed, plan changed
• Translatable plan/feature names and descriptions (via Spatie)
• Sortable plans and features (via Spatie)
• Configurable table names and swappable models
• Route middleware for feature gating
• Artisan command to prune expired subscriptions

Requirements

All combinations in the matrix above are exercised in CI on every push and pull request.

Installation

Publish config and migrations (optional):

Run migrations:

Migrations autoload by default. Set autoload_migrations to false in config/subscriptions.php to disable this.

Database Structure

Features are standalone entities. The value (limit) is set per-plan on the plan_features pivot. This lets a single "Users" feature have different limits across plans.

Usage

Add subscriptions to a model

Works on any Eloquent model — User, Tenant, Team, Organization, etc.

Create a plan

Intervals accept: hour, day, week, month, year.

Create features

Features are standalone — create them once, attach to many plans:

Attach features to plans with values

The value is set per-plan on the pivot — this is how different plans get different limits:

Factories

Every model ships with a factory for testing and seeding:

Subscribe

Subscription slugs are unique per subscriber, not globally, so both a User and a Tenant can hold a main subscription at the same time.

Check subscription status

Feature usage

If you call recordFeatureUsage with a slug that isn't attached to the subscription's plan, it throws Crumbls\Subscriptions\Exceptions\UnknownFeatureException — the featureSlug and plan are exposed as readonly properties on the exception.

Enforcing limits (example: user count)

Plan lifecycle

Scopes

Events

These events are plain dispatchable events — they do not implement ShouldBroadcast out of the box. If you want a broadcast version, extend the event in your application and add implements ShouldBroadcast there.

Middleware

Gate routes by feature or subscription:

Pruning expired subscriptions

Schedule it:

Configuration

Publish the config to customize table names or swap model classes:

Extending models

Every model is resolved through config. Extend the base model and update the config:

All relationships, scopes, traits, middleware, and the prune command resolve models through config — your custom models are used everywhere automatically.

Models

Considerations

• Payments are out of scope. This package handles plan/subscription logic only. Integrate with Stripe, Paddle, etc. separately via events or model overrides.
• Translatable fields: name and description on plans, features, and subscriptions are stored as JSON and support multiple locales via spatie/laravel-translatable.
• Soft deletes: Plans, features, subscriptions, and usage all use soft deletes. The prune command only soft-deletes; use forceDelete() if you need permanent removal.
• Features are standalone: Create a feature once, attach it to multiple plans with different values. This avoids duplicating feature definitions across plans.

Coming from rinvex/laravel-subscriptions

This package started as a modern reboot of rinvex/laravel-subscriptions, so the mental model is similar but a few things are worth knowing if you're porting an existing app:

• Namespace: Crumbls\Subscriptions\... (was Rinvex\Subscriptions\...).
• Config key: subscriptions (was rinvex.subscriptions).
• Subscribing: prefer $user->subscribe('main', $plan) — newPlanSubscription() also works. Rinvex's mix of newSubscription() / subscribe() is unified.
• Features are standalone. Rinvex defines features inline on the plan; here a Feature is its own row, and the value (limit) lives on the plan_features pivot. That's how you get "Basic: 5 users, Pro: 50 users" from a single users feature.
• *No `rinvex:artisan commands.** Use plainphp artisan migrateandphp artisan vendor:publish`.
• No model-level validation. Use Form Requests in your own app.
• Events. Four Laravel events (SubscriptionCreated, SubscriptionCanceled, SubscriptionRenewed, SubscriptionPlanChanged) in place of rinvex's trait-based hooks.

Upgrading

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

License

MIT