PHPackages                             masterix21/laravel-subscriptions - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. masterix21/laravel-subscriptions

ActiveLibrary

masterix21/laravel-subscriptions
================================

Laravel subscriptions for an unopinionated payment system

1.2.2(1mo ago)10MITPHPPHP ^8.2|^8.3|^8.4|^8.5CI passing

Since Apr 15Pushed 1w ago1 watchersCompare

[ Source](https://github.com/masterix21/laravel-subscriptions)[ Packagist](https://packagist.org/packages/masterix21/laravel-subscriptions)[ Docs](https://github.com/masterix21/laravel-subscriptions)[ GitHub Sponsors]()[ RSS](/packages/masterix21-laravel-subscriptions/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (16)Versions (17)Used By (0)

Laravel Subscriptions
=====================

[](#laravel-subscriptions)

[![Latest Version on Packagist](https://camo.githubusercontent.com/385ad25ccaa024175ffa6ea67f91572166577bf8248c04d7164f85050febf739/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6173746572697832312f6c61726176656c2d737562736372697074696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/masterix21/laravel-subscriptions)[![GitHub Tests Action Status](https://camo.githubusercontent.com/5aaf5949ae930beb85e0c4b535350d6bb7ecf3f846fb4658c50f43c49611eb18/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6173746572697832312f6c61726176656c2d737562736372697074696f6e732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/masterix21/laravel-subscriptions/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/0821d3d646f770b0095f2a53a3be9b3b8c2dee105b0c4aef7dfc112710d15822/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6173746572697832312f6c61726176656c2d737562736372697074696f6e732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/masterix21/laravel-subscriptions/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/48e1775bb68a32609bf5b0e3b95714af757b9bc9cf2962112c1deaad4597c293/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6173746572697832312f6c61726176656c2d737562736372697074696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/masterix21/laravel-subscriptions)

A flexible, payment-agnostic subscription system for Laravel. Manage plans, features, trials, grace periods, and recurring billing with built-in Stripe support and Livewire admin views.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 12 or 13

Installation
------------

[](#installation)

```
composer require masterix21/laravel-subscriptions
```

Publish and run the migrations:

```
php artisan vendor:publish --tag="laravel-subscriptions-migrations"
php artisan migrate
```

Publish the config file:

```
php artisan vendor:publish --tag="laravel-subscriptions-config"
```

Setup
-----

[](#setup)

### Prepare your Subscriber model

[](#prepare-your-subscriber-model)

Your subscriber model (typically `User`) must implement `SubscriberContract` and use the `HasSubscriptions` trait.

The model also needs a `meta` JSON field for storing payment gateway data:

```
// Migration
$table->json('meta')->nullable();
```

```
use Illuminate\Database\Eloquent\Casts\AsArrayObject;
use LucaLongo\Subscriptions\Models\Concerns\HasSubscriptions;
use LucaLongo\Subscriptions\Models\Contracts\SubscriberContract;

class User extends Authenticatable implements SubscriberContract
{
    use HasSubscriptions;

    protected $fillable = [
        // ...
        'meta',
    ];

    protected function casts(): array
    {
        return [
            'meta' => AsArrayObject::class,
        ];
    }

    public function customerName(): string
    {
        return $this->name;
    }

    public function customerEmail(): string
    {
        return $this->email;
    }

    public function customerUniqueIdentifierKey(): string
    {
        return $this->getKeyName();
    }

    public function customerUniqueIdentifier(): string
    {
        return (string) $this->getKey();
    }
}
```

### Configuration

[](#configuration)

The config file (`config/subscriptions.php`) allows you to customize the subscriber model, payment gateway, and all model classes:

```
return [
    'subscriber' => \App\Models\User::class,
    'payment_gateway' => \LucaLongo\Subscriptions\Payments\Gateways\StripeGateway::class,

    'models' => [
        'plan' => \LucaLongo\Subscriptions\Models\Plan::class,
        'feature' => \LucaLongo\Subscriptions\Models\Feature::class,
        'plan_feature' => \LucaLongo\Subscriptions\Models\PlanFeature::class,
        'subscription' => \LucaLongo\Subscriptions\Models\Subscription::class,
    ],
];
```

Usage
-----

[](#usage)

### Creating Plans

[](#creating-plans)

```
use LucaLongo\Subscriptions\Models\Plan;
use LucaLongo\Subscriptions\Enums\DurationInterval;

$plan = Plan::create([
    'name' => 'Pro Monthly',
    'description' => 'Pro plan, billed monthly',
    'duration_period' => 1,
    'duration_interval' => DurationInterval::MONTH,
    'price' => 9.99,
    'trial_period' => 14,
    'trial_interval' => DurationInterval::DAY,
    'grace_period' => 3,
    'grace_interval' => DurationInterval::DAY,
]);
```

The `code` field is auto-generated from the `name` (e.g. `pro-monthly`).

#### Plan scopes

[](#plan-scopes)

```
Plan::active()->get();    // enabled = true
Plan::inactive()->get();  // enabled = false
Plan::visible()->get();   // hidden = false
Plan::invisible()->get(); // hidden = true
```

### Managing Features

[](#managing-features)

```
use LucaLongo\Subscriptions\Models\Feature;

$feature = Feature::create(['name' => 'API Access']);

// Attach features to a plan (with optional max usage)
$plan->features()->attach($feature, ['max_usage' => 1000]);
```

### Subscribing

[](#subscribing)

```
// From the plan
$subscription = $plan->subscribe($user);

// From the user
$subscription = $user->subscribe($plan);

// With options
$subscription = $plan->subscribe(
    subscriber: $user,
    status: SubscriptionStatus::TRIALING,
    autoRenew: false,
    data: [
        'next_billing_at' => now()->addMonths(2),
        'payment_provider' => 'stripe',
        'payment_provider_reference' => 'sub_xxx',
    ]
);
```

### Checking Subscription State

[](#checking-subscription-state)

```
$subscription->isActive();    // Currently active (or in grace period)
$subscription->onTrial();     // In trial period
$subscription->onGrace();     // In grace period
$subscription->isRevoked();   // Permanently revoked
$subscription->isRevokable(); // Can be revoked
```

### Checking Features

[](#checking-features)

```
// On the subscriber
$user->hasActiveFeature('api-access');
$user->hasAnyActiveFeatures(['api-access', 'export']);
$user->hasAllActiveFeatures(['api-access', 'export']);
$user->subscribedTo('pro-monthly'); // by code
$user->subscribedTo($plan);        // by model

// On the subscription
$subscription->hasFeature('api-access');
$subscription->hasAnyFeature(collect(['api-access', 'export']));
$subscription->hasAllFeature(collect(['api-access', 'export']));
```

### Managing Subscriptions

[](#managing-subscriptions)

```
// Cancel (ends at next billing date by default)
$subscription->cancel();
$subscription->cancel(now()->addDays(7)); // custom end date

// Renew
$subscription->renew();
$subscription->renew(now()->addMonths(3)); // custom next billing date

// Revoke (permanent, cannot be renewed)
$subscription->revoke();

// Auto-renewal
app(DisableAutoRenewSubscription::class)->execute($subscription);
app(EnableAutoRenewSubscription::class)->execute($subscription);
```

Middleware
----------

[](#middleware)

Three middleware are available to protect routes based on subscription features:

```
use LucaLongo\Subscriptions\Http\Middleware\RequiresFeatureMiddleware;
use LucaLongo\Subscriptions\Http\Middleware\RequiresAnyFeaturesMiddleware;
use LucaLongo\Subscriptions\Http\Middleware\RequiresAllFeaturesMiddleware;

// Single feature
Route::middleware(RequiresFeatureMiddleware::class . ':api-access')
    ->get('/api/data', DataController::class);

// Any of multiple features (comma, pipe, or space separated)
Route::middleware(RequiresAnyFeaturesMiddleware::class . ':export,api-access')
    ->get('/tools', ToolsController::class);

// All features required
Route::middleware(RequiresAllFeaturesMiddleware::class . ':export,api-access')
    ->get('/advanced', AdvancedController::class);
```

All middleware return a `403` response if the user doesn't meet the requirements.

Stripe Integration
------------------

[](#stripe-integration)

### Setup

[](#setup-1)

Add your Stripe credentials to `config/services.php`:

```
'stripe' => [
    'secret' => env('STRIPE_SECRET'),
    'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
],
```

Store the Stripe Price ID in the plan's `meta` field:

```
$plan->meta['stripe_id'] = 'price_xxx';
$plan->save();
```

### Creating a Checkout Session

[](#creating-a-checkout-session)

```
use LucaLongo\Subscriptions\Payments\Gateways\StripeGateway;

return app(StripeGateway::class)->subscribe(
    plan: $plan,
    subscriber: $user,
    successUrl: route('subscription.success'),
    cancelUrl: route('subscription.cancel'),
);
```

This redirects the user to Stripe Checkout. The webhook handler automatically syncs subscription state back to your database.

### Webhook

[](#webhook)

The package registers a webhook route at `POST /hooks/payments/stripe`. The handler processes these Stripe events:

- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `customer.deleted`

Livewire Admin Views
--------------------

[](#livewire-admin-views)

The package includes optional Livewire components for managing plans, features, and subscriptions using Filament Table Builder.

Install the required dependencies:

```
composer require livewire/volt filament/tables guava/filament-clusters
```

Publish the views:

```
php artisan vendor:publish --tag="laravel-subscriptions-views"
```

Available components:

```

```

Extending Models
----------------

[](#extending-models)

You can extend any model by creating your own class and updating the config:

```
// app/Models/Plan.php
class Plan extends \LucaLongo\Subscriptions\Models\Plan
{
    // Your customizations
}

// config/subscriptions.php
'models' => [
    'plan' => \App\Models\Plan::class,
    // ...
],
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Luca Longo](https://github.com/masterix21)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance96

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 84.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~48 days

Recently: every ~100 days

Total

16

Last Release

31d ago

Major Versions

0.0.9 → 1.0.02025-03-04

PHP version history (4 changes)0.0.1PHP ^8.2

0.0.2PHP ^8.2|^8.3

1.0.0PHP ^8.2|^8.3|^8.4

1.2.1PHP ^8.2|^8.3|^8.4|^8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/177020fc4adb5c08acee3e6fe0b65002a96665c5d5c522a3ef009b4105fd634f?d=identicon)[masterix](/maintainers/masterix)

---

Top Contributors

[![masterix21](https://avatars.githubusercontent.com/u/6555012?v=4)](https://github.com/masterix21 "masterix21 (130 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (15 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (9 commits)")

---

Tags

laravelmasterix21Luca Longolaravel-subscriptions

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/masterix21-laravel-subscriptions/health.svg)

```
[![Health](https://phpackages.com/badges/masterix21-laravel-subscriptions/health.svg)](https://phpackages.com/packages/masterix21-laravel-subscriptions)
```

###  Alternatives

[spatie/laravel-livewire-wizard

Build wizards using Livewire

4061.0M4](/packages/spatie-laravel-livewire-wizard)[vormkracht10/laravel-mails

Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app.

24149.7k](/packages/vormkracht10-laravel-mails)[spatie/laravel-prometheus

Export Laravel metrics to Prometheus

2651.3M6](/packages/spatie-laravel-prometheus)[hydrat/filament-table-layout-toggle

Filament plugin adding a toggle button to tables, allowing user to switch between Grid and Table layouts.

6292.3k1](/packages/hydrat-filament-table-layout-toggle)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[ralphjsmit/laravel-helpers

A package containing handy helpers for your Laravel-application.

13704.6k2](/packages/ralphjsmit-laravel-helpers)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)