Laravel Soulbscription

If you are upgrading an existing installation to version 2.x, you must publish and run the specific upgrade migrations to ensure your database schema is updated correctly:

php artisan vendor:publish --tag="soulbscription-migrations-upgrades-1.x-2.x"
php artisan migrate

Use the features() relationship on a Plan instance to attach features. When attaching a consumable feature, you must provide the charges value in the pivot data to define how many units the plan grants.

$deployMinutes = Feature::whereName('deploy-minutes')->first();
$subdomains    = Feature::whereName('subdomains')->first();

// Silver plan gets 15 minutes
$silver->features()->attach($deployMinutes, ['charges' => 15]);

// Gold plan gets 25 minutes and subdomain access
$gold->features()->attach($deployMinutes, ['charges' => 25]);
$gold->features()->attach($subdomains);

Install the package into your Laravel project using Composer:

composer require lucasdotvin/laravel-soulbscription

To allow an entity (like a User model) to have subscriptions, add the HasSubscriptions trait to the class.

<?php

namespace App\Models;

use LucasDotVin\Soulbscription\Models\Concerns\HasSubscriptions;

class User
{
    use HasSubscriptions;
}

The package migrations are loaded automatically. However, if you need to publish them manually to your application's migration folder, use the following commands:

php artisan vendor:publish --tag="soulbscription-migrations"
php artisan migrate

Plans define the subscription terms. Use the Plan model to create them:

• Periodic Plans: Define periodicity_type and periodicity (e.g., Monthly).
• Permanent/Free Plans: Set periodicity_type and periodicity to null.
• Grace Days: Set grace_days to allow users to retain access for a specific number of days after their plan expires before access is suspended.

// Monthly plan with 7 days grace period
$gold = Plan::create([
    'name'             => 'gold',
    'periodicity_type' => PeriodicityType::Month,
    'periodicity'      => 1,
    'grace_days'       => 7,
]);

// Permanent/Free plan
$free = Plan::create([
    'name'             => 'free',
    'periodicity_type' => null,
    'periodicity'      => null,
]);

The project provides a docker-compose.yml file to facilitate development using Docker. You can use the defined services to run Composer commands or PHP scripts within a containerized environment that mirrors the project's requirements.

Services

• composer: A service using the composer/composer image. It is configured to run composer install by default and mounts the current directory to /app inside the container.
• php: A service built from the local Dockerfile located at .docker/php/Dockerfile. It mounts the current directory to /app and uses php as the entrypoint.

# Example: Install dependencies using the composer service
docker-compose run --rm composer

# Example: Run a PHP command (e.g., artisan) using the php service
docker-compose run --rm php artisan migrate

For features marked as quota => true, use the setConsumedQuota() method on the subscriber to reflect the current state of the resource (e.g., total disk space used).

// Example: Updating storage quota in a controller
$usedSpace = collect(Storage::allFiles($userFolder))
    ->map(fn (string $subFile) => Storage::size($subFile))
    ->sum();

auth()->user()->setConsumedQuota('storage', $usedSpace);

Use the switchTo() method to change a user's current plan.

• Immediate Switch: Calling $user->switchTo($newPlan) suppresses the current subscription and starts the new one immediately. This fires a SubscriptionStarted event.
• Scheduled Switch: Calling $user->switchTo($newPlan, immediately: false) keeps the current plan active until its expiration, then starts the new one. This fires a SubscriptionScheduled event.

// Switch immediately
$student->switchTo($newPlan);

// Switch at the end of the current period
$user->switchTo($primeYearly, immediately: false);