README

A flexible and customizable package for managing subscriptions with modular features in Laravel applications.

Installation

Install the package via Composer:

composer require hoceineel/laravel-modular-subscriptions

Publish the configuration file:

php artisan vendor:publish --provider="HoceineEl\LaravelModularSubscriptions\ModularSubscriptionsServiceProvider" --tag="config"

Publish the migrations:

php artisan vendor:publish --provider="HoceineEl\LaravelModularSubscriptions\ModularSubscriptionsServiceProvider" --tag="migrations"

Run the migrations:

php artisan migrate

Configuration

After publishing the configuration file, you can find it at config/modular-subscriptions.php. Here you can customize the model classes used by the package and define default modules if needed.

return [
    'modules' => [
        // Add your default modules here
    ],
    'models' => [
        'plan' => HoceineEl\LaravelModularSubscriptions\Models\Plan::class,
        'subscription' => HoceineEl\LaravelModularSubscriptions\Models\Subscription::class,
        'module' => HoceineEl\LaravelModularSubscriptions\Models\Module::class,
        'usage' => HoceineEl\LaravelModularSubscriptions\Models\ModuleUsage::class,
    ],
];

Usage

Creating a Module

Create a new module by extending the BaseModule class:

use HoceineEl\LaravelModularSubscriptions\Modules\BaseModule;
use HoceineEl\LaravelModularSubscriptions\Models\Subscription;

class SubscribersModule extends BaseModule
{
    public function getName(): string
    {
        return 'subscribers';
    }

    public function getLabelKey(): string
    {
        return 'Subscribers'; // we will use it like __('Subscribers')
    }

    public function calculateUsage(Subscription $subscription): int
    {
        return $subscription->subscribable->subscribers()->count();
    }

    public function getPricing(Subscription $subscription): float
    {
        $subscriberCount = $this->calculateUsage($subscription);
        return $subscriberCount * 0.5; // $0.50 per subscriber
    }

    public function canUse(Subscription $subscription): bool
    {
        $usage = $this->calculateUsage($subscription);
        $limit = 1000; // Example limit
        return $usage < $limit;
    }
}

Using the Subscribable Trait

Add the Subscribable trait to your model:

use HoceineEl\LaravelModularSubscriptions\Traits\Subscribable;

class User extends Model
{
    use Subscribable;
    // ...
}

Managing Subscriptions

Create a new subscription:

$user->newSubscription($planId, $trialDays);

Check subscription status:

if ($user->hasSubscription()) {
    // User has an active subscription
}

if ($user->onTrial()) {
    // User is on trial
}

$daysLeft = $user->daysLeft();

Cancel a subscription:

$user->cancel();

Renew a subscription:

$user->renew(30); // Renew for 30 days

Change subscription plan:

$user->changePlan($newPlanId);

Managing Module Usage

Record module usage:

$user->recordUsage('subscribers', 5);

Check if a module can be used:

if ($user->canUseModule('subscribers')) {
    // User can use the subscribers module
}

Advanced Usage

Extending Trial Periods

$user->extendTrial(7); // Extend trial by 7 days

Ending Trial Periods

$user->endTrial();

Calculating Total Usage and Pricing

use HoceineEl\LaravelModularSubscriptions\Facades\ModularSubscriptions;

$subscription = $user->activeSubscription();
$totalUsage = ModularSubscriptions::totalUsage($subscription);
$totalPricing = ModularSubscriptions::totalPricing($subscription);

Extending the Package

You can extend the functionality of this package by:

Creating custom modules for specific features
Extending the base models (Plan, Subscription, Module, ModuleUsage)

Testing

Run the tests with:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email contact@hoceine.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ by Hoceine El Idrissi

hoceineel / laravel-modular-subscriptions

Maintainers

Details