Download the PHP package kazistm/subscriptions without Composer

KaziSTM Subscriptions

A flexible and extendable subscription and plan management system for Laravel applications, particularly suited for SaaS products. This package provides tools to manage recurring plans, features with usage limits, and subscription lifecycles.

This package is based on, and aims to enhance, the foundation laid by laravelcm/laravel-subscriptions.

Table of Contents

• Key Features & Enhancements
• Requirements
• Installation
• Configuration
• Database Migrations
• Core Concepts & Models
  • 1. Subscribable Model
  • 2. Plan (KaziSTM\Subscriptions\Models\Plan)
  • 3. Limitation (KaziSTM\Subscriptions\Models\Limitation)
  • 4. Feature (KaziSTM\Subscriptions\Models\Feature)
  • 5. Subscription (KaziSTM\Subscriptions\Models\Subscription)
  • 6. Subscription Usage (KaziSTM\Subscriptions\Models\SubscriptionUsage)
  • Note on Slugs vs Names/Titles
• Usage
  • Preparation
  • Managing Subscriptions
  • Managing Feature Usage
• Middleware
  • Registration (Laravel 11+)
  • Registration (Pre-Laravel 11)
  • Usage in Routes
  • Subscribable Entity Detection
• Extending Models
• Support & Issues
• License
• Credits

Key Features & Enhancements

• Manages Plans, Subscriptions, Features, and Usage tracking.
• Introduces a Limitation model: Logically groups related features (e.g., 'Build Minutes', 'Seats', 'Storage Size'), providing translatable titles and descriptions. Features now primarily hold the value or quota, inheriting context from the Limitation.
• Supports trial periods, grace periods, plan changes, cancellations, and renewals.
• Features can have usage recorded against them, with optional periodic resetting (e.g., monthly email quotas).
• Includes an artisan subscriptions:install command for easy setup (config, migrations, optional model stubs).
• Includes Middleware for checking active subscriptions (subscription.active) and plan features (subscription.feature).
• Provides helper relationships (limitations()) and scopes (scopeWhereHasLimitationSlug()) on the Plan model.
• Uses Spatie packages for core functionalities like slugs (spatie/laravel-sluggable), translatable fields (spatie/laravel-translatable), and sortable models (spatie/eloquent-sortable).
• Built with spatie/laravel-package-tools for standard package structure.

Requirements

• PHP: >= 8.2
• Laravel: >= 10.x

Installation

1. Install the package via Composer:

2. Run the installation command:

   This interactive command will:

   • Ask if you want to publish the configuration file (config/subscriptions.php). Defaults to yes.
   • Publish the necessary database migrations to your database/migrations folder (it checks for existing migrations with the same base name to avoid duplication).
   • Ask if you want to publish basic model stubs (Plan.php, Subscription.php, etc.) to your app/Models directory. This is optional and only needed if you plan to directly extend or override the package's models. Defaults to no.
   • Automatically run php artisan migrate to create the required database tables.

Configuration

The main configuration file is located at config/subscriptions.php after publishing.

• Publishing (if skipped during install):

• Options:
  • tables: Customize the names of the database tables used by the package. Defaults are usually fine.
  • models: Define which Eloquent models the package should use. This allows you to override the default models with your own extended versions (see Extending Models section).

Database Migrations

The subscriptions:install command handles publishing and running migrations. The following tables are created (using default names):

• plans: Stores subscription plans details.
• limitations: Defines types of features/limits (e.g., 'users', 'projects').
• features: Links Plans to Limitations and sets the value/quota.
• subscriptions: Links subscribable models (e.g., Users) to Plans and tracks lifecycle.
• subscription_usage: Tracks consumption of resettable features.

Core Concepts & Models

1. Subscribable Model

Your model that will have subscriptions (typically App\Models\User, but can be any model like App\Models\Company) needs to use the KaziSTM\Subscriptions\Traits\HasPlanSubscriptions trait.

2. Plan (KaziSTM\Subscriptions\Models\Plan)

Defines a subscription plan your users can subscribe to.

Relationships

• features()
• subscriptions()
• limitations() (HasManyThrough Features)

Scopes

• scopeWhereHasLimitationSlug(Builder $query, string $limitationSlug)

Methods

• hasLimitation(string $limitationSlug)
• isFree()
• hasTrial()
• hasGrace()
• getFeatureBySlug()
• activate()
• deactivate())

Note: The Interval Enum (KaziSTM\Subscriptions\Enums\Interval) typically uses values like Interval::DAY->value ('day'), Interval::MONTH->value ('month'), Interval::YEAR->value ('year') when interacting with these fields programmatically, although the database stores the string values.

3. Limitation (KaziSTM\Subscriptions\Models\Limitation)

Defines a category or type of feature/limit (the "what").

Attributes

Relationships

• features()

4. Feature (KaziSTM\Subscriptions\Models\Feature)

Links a Plan to a Limitation, defining the specific value/quota (the "how much").

Attributes

Relationships

• plan()
• limitation()
• usages()

Methods

• getResetDate()

5. Subscription (KaziSTM\Subscriptions\Models\Subscription)

Links a subscribable model to a Plan and tracks its lifecycle.

Attributes

Relationships

• subscriber() (MorphTo)
• plan()
• usage()

Methods

• active()
• inactive()
• onTrial()
• canceled()
• ended()
• cancel()
• changePlan()
• renew()
• recordFeatureUsage()
• reduceFeatureUsage()
• canUseFeature()
• getFeatureUsage()
• getFeatureRemainings()
• getFeatureValue()

Scopes

• ofSubscriber()
• findEndingTrial()
• findEndedTrial()
• findEndingPeriod()
• findEndedPeriod()
• findActive()

6. Subscription Usage (KaziSTM\Subscriptions\Models\SubscriptionUsage)

Tracks consumption of specific, resettable features.

Attributes

Relationships

• subscription()
• feature()

Scopes

• scopeByFeatureSlug()

Methods

• expired()

Note on Slugs vs Names/Titles

Throughout the package, slug attributes (on Plan, Limitation, and Subscription) serve as unique, immutable identifiers intended for programmatic use. These are what you'll use in your code when:

• Fetching specific records
• Checking features
• Applying middleware

For example:

Usage

Preparation

1. Add Trait

Ensure your subscribable model(s) (e.g., App\Models\User, App\Models\Company) use the KaziSTM\Subscriptions\Traits\HasPlanSubscriptions trait.

2. Create Plans, Limitations & Features

Define plans, limitations, and features in your database, typically using seeders.

Example Seeder Logic:

Managing Subscriptions

Managing Feature Usage

Interact with features using the slug of the Limitation model.

Middleware

Protect your application routes based on subscription status or included features. The middleware automatically attempts to detect the subscribable entity from Route Model Binding, Filament Tenancy, or the Authenticated User.

Registration (Laravel 11+)

Register the middleware aliases in your bootstrap/app.php file:

Registration (Pre-Laravel 11)

Register the middleware aliases in your app/Http/Kernel.php:

Usage in Routes

Check Active Subscription (subscription.active)

Verifies the relevant subscribable entity has an active subscription (not ended or canceled). Aborts with 403 (Forbidden) otherwise.

Check Plan Features (subscription.feature)

Verifies the relevant subscribable entity's active subscription plan includes all specified features (by Limitation slug). Aborts with 403 (Forbidden) otherwise. Implicitly checks for an active subscription first.

Subscribable Entity Detection

The middleware automatically attempts to determine the subscribable entity to check in the following order of precedence:

1. Route Model Binding
   Looks for a route parameter that resolves to a model using the HasPlanSubscriptions trait.

2. Filament Tenancy
   If filament/filament is installed, checks the current tenant model.

3. Authenticated User
   Falls back to Auth::user() as a default.

Extending Models

If you need custom logic or relationships on the package's models:

1. Run php artisan subscriptions:install.
2. Answer "yes" when asked to Publish model stubs...?

3. Edit the generated files in app/Models/ (e.g., app/Models/Plan.php). They extend the base package models using aliases.

4. Update config/subscriptions.php to use your models:

Support & Issues

If you discover any security-related issues, please email [email address removed] instead of using the issue tracker.

All other issues, feature requests, or questions should be submitted via the GitHub Issues page.

License

This package is open-sourced software licensed under the MIT license.

Credits

• Forked from and inspired by LaravelCM Subscriptions
• Inspired by patterns in Spatie open-source packages.
• Author: Nezrek Youcef