Module Manager

Appearance

Stripe Module ​

Overview ​

The Stripe Module integrates Stripe payment processing and subscription management into your Filament application. It provides a seamless way to handle subscriptions, trials, and billing through the Stripe payment gateway.

Process to Use ​

1. Add Billable Trait ​

Add the Billable trait from Laravel Cashier to the model where you want to have subscription functionality:

php
use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;

    // ...
}

2. Configuration ​

The module includes configuration options that determine how it behaves. One important setting is the billable_type:

php
'billable_type' => null, // user or tenant or null

By default (null), the billable type is automatically determined based on your application's configuration. If the multi_tenancy setting in the module manager is true, the billable type will be set to tenant; otherwise, it will be set to user.

If you need to manually set the billable type (for example, if your system is multi-tenancy but you want to charge per user instead of per tenant), you can set this value explicitly. After changing the billable type, you need to run the migrations again.

3. Configure Promotion Codes and Trial Settings ​

You can configure whether to allow promotion codes and how to handle trial periods:

php
'allow_promotion_codes' => false,

'has_generic_trial' => false,

'trial_days' => 7, // null by default

There are two different trial options available, each with a different purpose:

  • has_generic_trial: This option enables manual trial management where you set the expiration date when creating the billable model. This is useful when you want users to test your system without providing a credit card.

  • trial_days: This option lets Stripe handle the trial period automatically, but will require a credit card from the user.

When configuring your application, you can set both options in your configuration:

php
'has_generic_trial' => false,
'trial_days' => 7,

However, during checkout (when the user subscribes), only one will be used:

php
// In Stripe.php, during checkout:
$billable->newSubscription($plan->type(), $price->id())
    ->when(
        ! $this->hasGenericTrial() && filled($this->trialDays()),
        fn (SubscriptionBuilder $subscription): SubscriptionBuilder => $subscription->trialDays($this->trialDays()),
    )

This means that if has_generic_trial is true, the trial_days setting will be ignored during checkout.

When creating a billable model, you can use both settings to determine the trial end date:

php
MyBillableModel::create([
    'trial_ends_at' => Stripe::fromConfig()->hasGenericTrial()
                ? now()->addDays(Stripe::fromConfig()->trialDays())
                : null,
    // other data...
])

This code sets the trial_ends_at field based on whether generic trial is enabled, and if so, uses the configured trial days to calculate the end date.

4. Configure Subscription Plans ​

Configure your subscription plans in the config file:

php
'plans' => [
    'default' => [
        'type' => 'default',
        'name' => 'Standard',
        'short_description' => __('A standard plan'),
        'product_id' => '', // Your Stripe product ID
        'prices' => [
            'monthly' => [
                'period' => 'monthly',
                'id' => '', // Your Stripe price ID for monthly billing
                'price' => 0, // Price in cents (e.g., 1000 for $10.00)
            ],
            'yearly' => [
                'period' => 'yearly',
                'id' => '', // Your Stripe price ID for yearly billing
                'price' => 0, // Price in cents (e.g., 10000 for $100.00)
            ],
        ],
        'features' => [
            __('Feature 1'),
            __('Feature 2'),
            __('Feature 3'),
        ],
    ],
],

5. Set Environment Variables ​

Add the necessary Stripe environment variables to your .env file:

STRIPE_KEY=your_stripe_publishable_key
STRIPE_SECRET=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

6. Dashboard Integration ​

The module extends the default Filament PHP dashboard and adds the Subscribe trait, which provides subscription modals. If you're using the default dashboard, no additional configuration is needed.

If you have a custom dashboard, make sure to add the Subscribe trait:

php
use Modules\Stripe\Filament\Traits\Subscribe;

class MyDashboard extends Dashboard
{
    use Subscribe;
}

7. Custom Dashboard Configuration ​

If you're using a custom dashboard, you'll need to update the following files:

  1. In VerifyBillableIsSubscribed.php, change line 35:
php
return redirect(MyDashboard::getUrl(['action' => 'subscribe']));
  1. In BillingProvider.php, change line 35:
php
return $billable->redirectToBillingPortal(MyDashboard::getUrl()); // or any URL you want users to be redirected to after visiting the Stripe portal
  1. In Stripe.php, change lines 93-94:
php
'success_url' => MyDashboard::getUrl(['action' => 'subscribed']),
'cancel_url' => MyDashboard::getUrl(),

8. Custom Pricing Pages ​

If you want to create custom pricing pages, you may need to modify:

  • The configuration in the plans section
  • The DTOs in the Data directory
  • Create your own views and components

Note that different pricing page components may require different configuration structures, so be prepared to adapt the configuration accordingly.