Filament Billing Provider for Laravel Cashier

https://github.com/maartenpaauw/filament-cashier-billing-provider
Admin
Integrates Laravel Cashier Stripe support into Filament's multi-tenant panels, enabling billing...
Tokens:24,769
Snippets:168
Trust Score:9.6
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/README.md

Install the package via Composer. After installation, ensure your Billable model matches your Filament tenant model.

```bash
composer require maartenpaauw/filament-cashier-billing-provider
```

--------------------------------

### Resolving plans through the container

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/PlanRepository.md

Basic usage example showing how to resolve the PlanRepository from the container and call its methods. The default implementation is ConfigPlanRepository.

```php
use Maartenpaauw\Filament\Cashier\PlanRepository;

$repository = app(PlanRepository::class); // ConfigPlanRepository by default

$plan = $repository->get(name: 'default');  // Plan
$plans = $repository->all();                 // array<int|string, Plan>
```

--------------------------------

### Manual registration in bootstrap/providers.php

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/FilamentCashierServiceProvider.md

Example of manually registering the service provider when auto-discovery is disabled.

```php
// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    Maartenpaauw\Filament\Cashier\FilamentCashierServiceProvider::class,
];
```

--------------------------------

### PlanRepository interface with all() and get() methods

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/types.md

Defines the contract for retrieving billing plans. The `all()` method returns an array of `Plan` objects, and `get(string $name)` returns a single `Plan` by name. Implemented by `ConfigPlanRepository` and bound in the container by `FilamentCashierServiceProvider`.

```php
interface PlanRepository
{
    /**
     * @return array<int, Plan>
     */
    public function all(): array;

    public function get(string $name): Plan;
}
```

--------------------------------

### Configure cashier.plans in config/cashier.php

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/configuration.md

Canonical example of the `cashier.plans` configuration array in `config/cashier.php`. Each plan key maps to an options array; `product_id` and `price_id` are required at runtime (empty values throw `InvalidArgumentException`), while `type`, `trial_days`, `has_generic_trial`, `allow_promotion_codes`, `collect_tax_ids`, and `metered_price` are optional. `has_generic_trial` is mutually exclusive with `trial_days`.

```php
// config/cashier.php
'plans' => [
    'default' => [
        'product_id' => ENV('CASHIER_STRIPE_SUBSCRIPTION_DEFAULT_PRODUCT_ID'),
        'price_id' => ENV('CASHIER_STRIPE_SUBSCRIPTION_DEFAULT_PRICE_ID'),
        'type' => 'default',          // Optional, defaults to the array key.
        'trial_days' => 14,           // Optional
        'has_generic_trial' => true,  // Optional; mutually exclusive with trial_days.
        'allow_promotion_codes' => true, // Optional
        'collect_tax_ids' => true,    // Optional
        'metered_price' => true,      // Optional
    ],
],
```

--------------------------------

### Basic usage: resolve and use the current tenant

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/TenantRepository.md

Basic usage example: resolve the current tenant and use it to check subscription status and create a new subscription if not subscribed. Requires a panel/tenant context.

```php
use Maartenpaauw\Filament\Cashier\TenantRepository;
use Laravel\Cashier\Cashier;

// In a panel/tenant context:
$tenant = TenantRepository::make()->current();

if (! $tenant->subscribed()) {
    $tenant->newSubscription('default', 'price_x')->create();
}
```

--------------------------------

### Non-trivial: making a Stripe customer on demand

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/TenantRepository.md

Non-trivial example: creates a Stripe customer on demand if the tenant lacks a Stripe ID, then redirects to the billing portal. Mirrors the closure returned by `BillingProvider::getRouteAction()`.

```php
use Maartenpaauw\Filament\Cashier\TenantRepository;

$tenant = TenantRepository::make()->current();

if ($tenant->hasStripeId() === false) {
    $tenant->createAsStripeCustomer();
}

$tenant->redirectToBillingPortal(returnUrl: url('/dashboard'));
```

--------------------------------

### PlanRepository::get() method signature

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/PlanRepository.md

The signature of the get() method, which takes a plan name and returns a Plan instance. Throwing behavior is implementation-defined.

```php
public function get(string $name): Plan
```

--------------------------------

### createPlanFromArray() method implementation

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/ConfigPlanRepository.md

Private method that maps config array keys to Plan constructor parameters with defaults. Used internally by get().

```php
private function createPlanFromArray(array $plan, string $name): Plan
{
    return new Plan(
        type: Arr::get($plan, key: 'type', default: $name),
        productId: Arr::get($plan, key: 'product_id', default: ''),
        priceId: Arr::get($plan, key: 'price_id', default: ''),
        trialDays: Arr::get($plan, key: 'trial_days', default: false),
        hasGenericTrial: Arr::get($plan, key: 'has_generic_trial', default: false),
        allowPromotionCodes: Arr::get($plan, key: 'allow_promotion_codes', default: false),
        collectTaxIds: Arr::get($plan, key: 'collect_tax_ids', default: false),
        isMeteredPrice: Arr::get($plan, key: 'metered_price', default: false),
    );
}
```

--------------------------------

### get() method implementation

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/ConfigPlanRepository.md

Public method that retrieves a plan by name from the 'cashier.plans' config array. Throws InvalidArgumentException when the entry is missing product_id/price_id.

```php
#[Override]
public function get(string $name): Plan
{
    return $this->createPlanFromArray(
        plan: $this->config->array(key: "cashier.plans.$name"),
        name: $name,
    );
}
```

--------------------------------

### Error handling: misconfigured tenant model

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/TenantRepository.md

Error handling example: catches `LogicException` thrown by `current()` when the tenant model is misconfigured, and aborts with a 500 status and the exception message.

```php
use Maartenpaauw\Filament\Cashier\TenantRepository;
use LogicException;

try {
    $tenant = TenantRepository::make()->current();
} catch (LogicException $e) {
    // Either:
    // 'Filament tenant does not match the Cashier customer model'
    // 'Tenant model does not use Cashier Billable trait'
    abort(500, 'Billing tenant misconfiguration: '.$e->getMessage());
}
```

--------------------------------

### Overriding the plan repository binding in AppServiceProvider

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/FilamentCashierServiceProvider.md

Example of overriding the PlanRepository binding in your own service provider to customize the implementation.

```php
use Illuminate\Support\ServiceProvider;
use Maartenpaauw\Filament\Cashier\ConfigPlanRepository;
use Maartenpaauw\Filament\Cashier\PlanRepository;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(PlanRepository::class, function ($app) {
            // wrap the default with caching/logging, or return your own
            // PlanRepository implementation
        });
    }
}
```

--------------------------------

### Resolve ConfigPlanRepository via app() and get 'default' plan

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/ConfigPlanRepository.md

Resolve the ConfigPlanRepository through Laravel's container and fetch the 'default' plan. The comment notes that Laravel injects the Illuminate Config\Repository automatically.

```php
use Maartenpaauw\Filament\Cashier\ConfigPlanRepository;

// Laravel injects the Illumine Config\Repository automatically:
$repository = app(ConfigPlanRepository::class);

$plan = $repository->get(name: 'default');
```

--------------------------------

### Catching InvalidArgumentException from Plan constructor

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/errors.md

Example of catching InvalidArgumentException when constructing a Plan with an empty priceId. The exception message is 'Price ID cannot be empty.' and is logged via logger()->error().

```php
use InvalidArgumentException;
use Maartenpaauw\Filament\Cashier\Plan;

try {
    $plan = new Plan(
        type: 'default',
        productId: 'prod_x',
        priceId: '',
        trialDays: false,
        hasGenericTrial: false,
        allowPromotionCodes: false,
        collectTaxIds: false,
        isMeteredPrice: false,
    );
} catch (InvalidArgumentException $e) {
    // 'Price ID cannot be empty.'
    logger()->error('Invalid billing plan', ['error' => $e->getMessage()]);
}
```

--------------------------------

### Basic: constructing a plan directly

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/Plan.md

Creates a Plan instance with named arguments for type, productId, priceId, trialDays, hasGenericTrial, allowPromotionCodes, collectTaxIds, and isMeteredPrice. Public properties like type and trialDays are then echoed to show the assigned values.

```php
use Maartenpaauw\Filament\Cashier\Plan;

$plan = new Plan(
    type: 'default',
    productId: 'prod_0JkO18GJx0Vtux',
    priceId: 'price_Fxp5y8x0qjrm2jjk2nzuMpSF',
    trialDays: 14,
    hasGenericTrial: false,
    allowPromotionCodes: true,
    collectTaxIds: true,
    isMeteredPrice: false,
);

echo $plan->type;       // 'default'
echo $plan->trialDays;  // 14
```

--------------------------------

### Run tests

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/README.md

Run the package test suite.

```bash
composer test
```

--------------------------------

### Instantiate BillingProvider with BackedEnum plans

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/configuration.md

Shows how to pass a BackedEnum or an array of BackedEnum cases to BillingProvider; the enum value is used as the plan name.

```php
new BillingProvider(plans: Plan::Basic);       // Plan is your \BackedEnum
new BillingProvider(plans: Plan::cases());     // all cases
```

--------------------------------

### Non-trivial usage: multiple plans from a backed enum

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

Shows how to use `plan()` with a backed enum to gate a route group on any of the plans. The `handle()` method receives the plan values as variadic parameters.

```php
use Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed;

enum Membership: string
{
    case Basic = 'basic';
    case Advanced = 'advanced';
}

// Route group gated on ANY of the plans:
Route::middleware([
    RedirectIfUserNotSubscribed::plan(plans: Membership::cases()),
])->group(function (): void {
    Route::get('/reports', ReportsController::class);
});

```

--------------------------------

### Plan::__construct

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/Plan.md

Creates a new Plan instance with the given billing configuration. Validates that type, productId, and priceId are non-empty, and that trialDays is not negative and not combined with hasGenericTrial.

```APIDOC
## Plan::__construct

### Description
Creates a new Plan instance with the given billing configuration. Validates that type, productId, and priceId are non-empty, and that trialDays is not negative and not combined with hasGenericTrial.

### Method
Constructor

### Signature
```php
public function __construct(
    public string $type,
    public string $productId,
    public string $priceId,
    public int|false $trialDays,
    public bool $hasGenericTrial,
    public bool $allowPromotionCodes,
    public bool $collectTaxIds,
    public bool $isMeteredPrice,
)
```

### Parameters
- **type** (string) - Required - Subscription type, passed as `newSubscription(type: ...)` and `subscribedToProduct(type: ...)`. Must be non-empty.
- **productId** (string) - Required - Stripe product ID, used by `subscribedToProduct(products: ...)` in the middleware. Must be non-empty.
- **priceId** (string) - Required - Stripe price ID, passed as `prices` to `newSubscription()` (unless `isMeteredPrice`, where it is passed to `meteredPrice()`). Must be non-empty.
- **trialDays** (int|false) - Required - Number of trial days. `false` disables the fixed trial. Mutually exclusive with `hasGenericTrial`; must not be negative.
- **hasGenericTrial** (bool) - Required - When `true`, the middleware passes the tenant through while `$tenant->onGenericTrial()` is `true`, and the `trialDays()` builder call is skipped.
- **allowPromotionCodes** (bool) - Required - When `true`, `allowPromotionCodes()` is chained on the `SubscriptionBuilder`.
- **collectTaxIds** (bool) - Required - When `true`, `collectTaxIds()` is chained on the `SubscriptionBuilder`.
- **isMeteredPrice** (bool) - Required - When `true`, `newSubscription()` is called with an empty `prices` array and the price is attached via `meteredPrice(price: $plan->priceId)`.

### Return Type
`Plan` — a fully validated immutable instance.

### Throws
- **InvalidArgumentException** - If `type` is an empty string — message `Type cannot be empty.`
- **InvalidArgumentException** - If `productId` is an empty string — message `Product ID cannot be empty.`
- **InvalidArgumentException** - If `priceId` is an empty string — message `Price ID cannot be empty.`
- **InvalidArgumentException** - If `trialDays` is not `false` **and** `hasGenericTrial` is `true` — message `Only "trial days" or "has generic trial" can be used.`
- **InvalidArgumentException** - If `trialDays` is not `false` and is negative — message `Trial days must be greater than 0.`
```

--------------------------------

### getSubscribedMiddleware()

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Returns a middleware-alias string of the form `Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed:<plans>`, built by `RedirectIfUserNotSubscribed::plan()`. The plans are derived from the constructor input.

```APIDOC
## getSubscribedMiddleware()

### Description
Returns a middleware-alias string of the form `Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed:<plans>`, built by `RedirectIfUserNotSubscribed::plan()`. The plans are derived from the constructor input.

### Method
GET

### Endpoint
N/A (Method)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **string** - Middleware alias string.

#### Response Example
`Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed:default`

### Throws
None.
```

--------------------------------

### ConfigPlanRepository::all() method

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/ConfigPlanRepository.md

Returns an array of Plan objects from the 'cashier.plans' config key, preserving string keys. Throws InvalidArgumentException for invalid plan entries.

```php
#[Override]
public function all(): array
{
    return Arr::map(
        array: $this->config->array(key: 'cashier.plans'),
        callback: fn (array $plan, string $name) => $this->createPlanFromArray(plan: $plan, name: $name),
    );
}
```

--------------------------------

### Non-trivial: multiple plans via backed enum

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Gates the panel on any of several plans using a backed enum. The subscription check passes if the tenant is subscribed to any of the listed plans.

```php
use Maartenpaauw\Filament\Cashier\Stripe\BillingProvider;

enum Plan: string // your application enum
{
    case Basic = 'basic';
    case Advanced = 'advanced';
    case Premium = 'premium';
}

return $panel
    ->tenantBillingProvider(new BillingProvider(plans: Plan::cases()))
    ->requiresTenantSubscription();
```

--------------------------------

### Basic usage: register middleware on a route

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

Shows how to use `plan()` to register the middleware on a route. The generated alias is `...RedirectIfUserNotSubscribed:default`.

```php
use Illuminate\Support\Facades\Route;
use Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed;

Route::middleware([
    RedirectIfUserNotSubscribed::plan(), // -> ...RedirectIfUserNotSubscribed:default
])->get('/dashboard', DashboardController::class);

```

--------------------------------

### register() method binding PlanRepository to ConfigPlanRepository

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/FilamentCashierServiceProvider.md

The register() method binds the PlanRepository interface to the ConfigPlanRepository implementation using a transient binding.

```php
#[Override]
public function register(): void
{
    $this->app->bind(abstract: PlanRepository::class, concrete: ConfigPlanRepository::class);
}
```

--------------------------------

### Custom PlanRepository implementation

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/PlanRepository.md

Shows a custom implementation of PlanRepository that reads plans from a database table. Includes the class definition and the container binding to override the default.

```php
use Illuminate\Support\ServiceProvider;
use Maartenpaauw\Filament\Cashier\Plan;
use Maartenpaauw\Filament\Cashier\PlanRepository;

class DatabasePlanRepository implements PlanRepository
{
    /** @return array<int, Plan> */
    public function all(): array
    {
        return app('db')->table('plans')->get()
            ->map(fn (object $row): Plan => $this->toPlan($row))
            ->values()
            ->all();
    }

    public function get(string $name): Plan
    {
        $row = app('db')->table('plans')->where('name', $name)->firstOrFail();

        return $this->toPlan($row);
    }

    private function toPlan(object $row): Plan
    {
        return new Plan(
            type: (string) $row->type,
            productId: (string) $row->product_id,
            priceId: (string) $row->price_id,
            trialDays: $row->trial_days === null ? false : (int) $row->trial_days,
            hasGenericTrial: (bool) $row->has_generic_trial,
            allowPromotionCodes: (bool) $row->allow_promotion_codes,
            collectTaxIds: (bool) $row->collect_tax_ids,
            isMeteredPrice: (bool) $row->metered_price,
        );
    }
}

// In your AppServiceProvider::register():
$this->app->bind(PlanRepository::class, DatabasePlanRepository::class);
```

--------------------------------

### Instantiate BillingProvider with a single plan

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/configuration.md

Shows three ways to instantiate BillingProvider with a single plan: no arguments (defaults to 'default'), a single plan name, or a comma-separated string of plan names.

```php
new BillingProvider();                            // 'default'
new BillingProvider(plans: 'basic');
new BillingProvider(plans: 'basic,advanced,premium'); // single comma-separated string
```

--------------------------------

### TenantRepository::make() factory method signature

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/TenantRepository.md

Static factory method signature for creating a new TenantRepository instance. It returns a new instance via `return new self;` and takes no parameters.

```php
public static function make(): self
```

--------------------------------

### new Plan()

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/Plan.md

Constructs a Plan instance with the given parameters. The constructor validates that only one of trialDays or hasGenericTrial is set, and throws an InvalidArgumentException otherwise.

```APIDOC
## new Plan()

### Description
Constructs a Plan instance representing a billing plan. The constructor accepts various parameters to define the plan's type, product, price, trial settings, and other billing options.

### Method
Constructor

### Endpoint
`Maartenpaauw\Filament\Cashier\Plan::__construct`

### Parameters
#### Constructor Parameters
- **type** (string) - Required - The type of the plan (e.g., 'default', 'usage').
- **productId** (string) - Required - The Stripe product ID.
- **priceId** (string) - Required - The Stripe price ID.
- **trialDays** (int|false) - Required - Number of trial days, or `false` if not applicable. Cannot be used together with `hasGenericTrial`.
- **hasGenericTrial** (bool) - Required - Whether the plan uses a generic trial. Cannot be used together with `trialDays`.
- **allowPromotionCodes** (bool) - Required - Whether promotion codes are allowed.
- **collectTaxIds** (bool) - Required - Whether tax IDs should be collected.
- **isMeteredPrice** (bool) - Required - Whether the price is metered.

### Request Example
```php
use Maartenpaauw\Filament\Cashier\Plan;

$plan = new Plan(
    type: 'default',
    productId: 'prod_0JkO18GJx0Vtux',
    priceId: 'price_Fxp5y8x0qjrm2jjk2nzuMpSF',
    trialDays: 14,
    hasGenericTrial: false,
    allowPromotionCodes: true,
    collectTaxIds: true,
    isMeteredPrice: false,
);
```

### Response
#### Success Response
Returns a `Plan` instance with the provided properties accessible as public properties (e.g., `$plan->type`, `$plan->trialDays`).

#### Error Handling
Throws `InvalidArgumentException` if both `trialDays` and `hasGenericTrial` are set (or both are not `false`/`true` respectively). The error message is: 'Only "trial days" or "has generic trial" can be used.'

### Example: Invalid Combination
```php
use Maartenpaauw\Filament\Cashier\Plan;
use InvalidArgumentException;

try {
    $plan = new Plan(
        type: 'default',
        productId: 'prod_x',
        priceId: 'price_y',
        trialDays: 14,
        hasGenericTrial: true,
        allowPromotionCodes: false,
        collectTaxIds: false,
        isMeteredPrice: false,
    );
} catch (InvalidArgumentException $e) {
    // 'Only "trial days" or "has generic trial" can be used.'
    report($e);
}
```

### Example: Metered Price
```php
use Maartenpaauw\Filament\Cashier\Plan;

$metered = new Plan(
    type: 'usage',
    productId: 'prod_usage',
    priceId: 'price_metered',
    trialDays: false,
    hasGenericTrial: false,
    allowPromotionCodes: false,
    collectTaxIds: false,
    isMeteredPrice: true,
);
```
```

--------------------------------

### PlanRepository::all() method signature

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/PlanRepository.md

The signature of the all() method, which returns an array of Plan instances. The default implementation returns plans keyed by their config name.

```php
/**
 * @return array<int, Plan>
 */
public function all(): array
```

--------------------------------

### Configure plans in cashier.php

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/README.md

Add plans to your cashier.php config file. Only recurring subscriptions are supported. The 'type' key defaults to the array key; 'trial_days' and 'has_generic_trial' are mutually exclusive.

```php
'plans' => [
    'default' => [
        'product_id' => ENV('CASHIER_STRIPE_SUBSCRIPTION_DEFAULT_PRODUCT_ID'),
        'price_id' => ENV('CASHIER_STRIPE_SUBSCRIPTION_DEFAULT_PRICE_ID'),
        'type' => 'default', // Optional, by default it uses the array key as type.
        'trial_days' => 14, // Optional
        'has_generic_trial' => true, // Optional, only `trial_days` OR `has_generic_trial` can be used.
        'allow_promotion_codes' => true, // Optional
        'collect_tax_ids' => true, // Optional
        'metered_price' => true, // Optional
    ],
],
```

--------------------------------

### Validate all configured plans at boot with PlanRepository::all()

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/ConfigPlanRepository.md

Iterates over all configured plans via PlanRepository::all(). Invalid plans throw InvalidArgumentException during iteration; $name is the config key and $plan->type is logged.

```php
use Maartenpaauw\Filament\Cashier\PlanRepository;

foreach (app(PlanRepository::class)->all() as $name => $plan) {
    // $name is the config key ('default', 'basic', ...); invalid plans
    // surface here as InvalidArgumentException.
    Log::info("Loaded plan {$name}", ['type' => $plan->type]);
}
```

--------------------------------

### plan() method signature

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

The method signature for `plan()`, showing the parameter type and default value. It accepts a string, a BackedEnum, or an array of strings/BackedEnums, defaulting to 'default'.

```php
/**
 * @param  string|BackedEnum|array<array-key, string|BackedEnum>  $plans
 */
public static function plan(string|BackedEnum|array $plans = 'default'): string

```

--------------------------------

### Plan constructor signature (PHP)

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/Plan.md

Constructor for the Plan value object. Accepts the subscription type, Stripe product and price IDs, trial days, and checkout flags. Throws an InvalidArgumentException when type is an empty string. All arguments become public readonly properties because the class is readonly with promoted properties.

```php
public function __construct(
    public string $type,
    public string $productId,
    public string $priceId,
    public int|false $trialDays,
    public bool $hasGenericTrial,
    public bool $allowPromotionCodes,
    public bool $collectTaxIds,
    public bool $isMeteredPrice,
) {
    if ($this->type === '') {
        throw new 
InvalidArgumentException('Type cannot be empty');
    }
}
```

--------------------------------

### RedirectIfUserNotSubscribed::plan()

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

Static factory method that builds a middleware alias string for the RedirectIfUserNotSubscribed middleware, accepting a plan name, a backed enum case, or an array of plans.

```APIDOC
## `plan()`

### Description
Static factory building the framework-resolvable middleware alias string.

### Method
`plan`

### Signature
```php
public static function plan(string|BackedEnum|array $plans = 'default'): string
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `plans` | `string\|BackedEnum\|array<array-key, string\|BackedEnum>` | No | `'default'` | Plan name; a `BackedEnum` case (its `$value` is used, stringified via `strval`); or any combination wrapped by `Collection::wrap`. A comma-separated string such as `'basic,advanced'` is treated as a single element and output unchanged. |

### Return Type
`string` in the format `<class-name>:<comma-joined plan values>`, e.g. `Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed:basic,advanced`.

### Throws
None.

### Usage Examples

#### Basic: register the middleware manually on a route

```php
use Illuminate\Support\Facades\Route;
use Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed;

Route::middleware([
    RedirectIfUserNotSubscribed::plan(), // -> ...RedirectIfUserNotSubscribed:default
])->get('/dashboard', DashboardController::class);
```

#### Non-trivial: multiple plans from a backed enum

```php
use Maartenpaauw\Filament\Cashier\Stripe\RedirectIfUserNotSubscribed;

enum Membership: string
{
    case Basic = 'basic';
    case Advanced = 'advanced';
}

// Route group gated on ANY of the plans:
Route::middleware([
    RedirectIfUserNotSubscribed::plan(plans: Membership::cases()),
])->group(function (): void {
    Route::get('/reports', ReportsController::class);
});
```

The alias string resolves via the container to an instance whose `handle()` receives `'basic'` and `'advanced'` as variadic plan parameters.
```

--------------------------------

### BillingProvider constructor with $plans parameter

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Constructor for the Stripe billing provider. Accepts a plan name, enum case, or array of either, defaulting to 'default'. Validation of plan names is deferred to Plan/PlanRepository.

```php
/**
 * @param  string|BackedEnum|array<array-key, string|BackedEnum>  $plans
 */
public function __construct(
    private string|BackedEnum|array $plans = 'default',
)
```

--------------------------------

### Basic: single default plan with BillingProvider

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Registers the BillingProvider on a Filament panel with a single default plan. The tenant is placed behind the subscription middleware via requiresTenantSubscription().

```php
use Maartenpaauw\Filament\Cashier\Stripe\BillingProvider;
use Filament\Panel;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            // ...
            ->tenantBillingProvider(new BillingProvider())
            ->requiresTenantSubscription();
    }
}
```

--------------------------------

### RedirectIfUserNotSubscribed constructor

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

Constructor for the middleware. The PlanRepository is injected via the container and is used to convert plan names passed to handle() into Plan objects.

```php
public function __construct(
    private PlanRepository $repository,
)
```

--------------------------------

### RedirectIfUserNotSubscribed::__construct

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

Constructor for the RedirectIfUserNotSubscribed middleware. It accepts a PlanRepository instance used to resolve plan names into Plan objects.

```APIDOC
## Constructor

### Description
Creates a new instance of the middleware with the given plan repository.

### Method
__construct

### Signature
```php
public function __construct(
    private PlanRepository $repository,
)
```

### Parameters
- **repository** (`Maartenpaauw\Filament\Cashier\PlanRepository`) - Required - Plan lookup source used to convert each plan name passed to `handle()` into a `Plan`. Bound by default to `ConfigPlanRepository` (see `FilamentCashierServiceProvider`); intermediate middleware is resolved through the container, so the binding is injected automatically.

### Return Type
`RedirectIfUserNotSubscribed`

### Throws
None at construction.
```

--------------------------------

### Add product_id to cashier.php plans

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/UPGRADING.md

Add the required 'product_id' configuration to each plan in the cashier.php configuration file when upgrading from v1 to v2. The 'product_id' is necessary because the middleware now checks subscription using ->subscribedToProduct(...) instead of ->subscribed().

```diff
'plans' => [
    'default' => [
+        'product_id' => ENV('CASHIER_STRIPE_SUBSCRIPTION_DEFAULT_PRODUCT_ID'),
        'price_id' => ENV('CASHIER_STRIPE_SUBSCRIPTION_DEFAULT_PRICE_ID'),
    ],
],
```

--------------------------------

### ConfigPlanRepository constructor

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/ConfigPlanRepository.md

Constructor for ConfigPlanRepository. Accepts Laravel's config repository, which is injected automatically when resolving through the container.

```php
public function __construct(
    private Repository $config,
)
```

--------------------------------

### Bind PlanRepository to ConfigPlanRepository in service provider

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/PlanRepository.md

Shows the container binding performed by FilamentCashierServiceProvider::register(), which binds the PlanRepository interface to the default ConfigPlanRepository implementation.

```php
$this->app->bind(abstract: PlanRepository::class, concrete: ConfigPlanRepository::class);
```

--------------------------------

### Plan constructor validation checks

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/errors.md

Validation checks thrown from the Plan constructor. Empty checks are strict (=== ''), so whitespace-only strings pass. Validation order matters: type, productId, priceId, trial combination, then negative trial; the first failing check is thrown. trialDays = 0 is legal.

```php
if ($this->type === '') {
    throw new InvalidArgumentException(message: 'Type cannot be empty.');
}

if ($this->productId === '') {
    throw new InvalidArgumentException(message: 'Product ID cannot be empty.');
}

if ($this->priceId === '') {
    throw new InvalidArgumentException(message: 'Price ID cannot be empty.');
}

if ($this->trialDays !== false && $this->hasGenericTrial === true) {
    throw new InvalidArgumentException(message: 'Only "trial days" or "has generic trial" can be used.');
}

if ($this->trialDays !== false && $this->trialDays < 0) {
    throw new InvalidArgumentException(message: 'Trial days must be greater than 0.');
}
```

--------------------------------

### getSubscribedMiddleware() signature

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Signature of the getSubscribedMiddleware() method, copied from lines 39–42. It returns a string.

```php
#[Override]
public function getSubscribedMiddleware(): string
```

--------------------------------

### TenantRepository::current() method with validation

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/TenantRepository.md

The `current()` method resolves the current tenant via `Filament::getTenant()`, validates it against the Cashier customer model and the `Billable` trait, and returns it. Throws `LogicException` on mismatch or missing trait. Note: no null-guard exists, so a null tenant causes a fatal PHP `Error`.

```php
/**
 * @return Model & Billable
 */
public function current(): Model
{
    $tenant = Filament::getTenant();

    if ($tenant::class !== Cashier::$customerModel) {
        throw new LogicException(message: 'Filament tenant does not match the Cashier customer model');
    }

    if (! in_array(needle: Billable::class, haystack: class_uses_recursive($tenant), strict: true)) {
        throw new LogicException(message: 'Tenant model does not use Cashier Billable trait');
    }

    return $tenant;
}
```

--------------------------------

### Plan value object class definition

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/types.md

Defines the Plan value object with promoted public properties. The constructor performs validation (not shown) and rejects empty strings for type, productId, and priceId. trialDays accepts int|false, where false means no fixed trial, and is mutually exclusive with hasGenericTrial.

```php
final readonly class Plan
{
    public function __construct(
        public string $type,
        public string $productId,
        public string $priceId,
        public int|false $trialDays,
        public bool $hasGenericTrial,
        public bool $allowPromotionCodes,
        public bool $collectTaxIds,
        public bool $isMeteredPrice,
    ) { /* validation, see below */ }
}
```

--------------------------------

### Catching LogicException from TenantRepository::current()

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/errors.md

Catch the LogicException thrown by TenantRepository::current() and abort with a 500 response using the exception message. The comments show the two possible messages: 'Filament tenant does not match the Cashier customer model' and 'Tenant model does not use Cashier Billable trait'.

```php
use LogicException;
use Maartenpaauw\Filament\Cashier\TenantRepository;

try {
    $tenant = TenantRepository::make()->current();
} catch (LogicException $e) {
    // 'Filament tenant does not match the Cashier customer model'
    // 'Tenant model does not use Cashier Billable trait'
    abort(500, $e->getMessage());
}
```

--------------------------------

### Handle missing config keys with InvalidArgumentException

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/ConfigPlanRepository.md

Shows the InvalidArgumentException thrown when a plan config lacks required keys (product_id, price_id). The exception message 'Product ID cannot be empty.' comes from the Plan constructor via createPlanFromArray() because defaults resolve to ''.

```php
use Maartenpaauw\Filament\Cashier\ConfigPlanRepository;
use InvalidArgumentException;

config()->set('cashier.plans', [
    'incomplete' => [ // no product_id, no price_id
    ],
]);

try {
    app(ConfigPlanRepository::class)->get(name: 'incomplete');
} catch (InvalidArgumentException $e) {
    // 'Product ID cannot be empty.' — thrown by the Plan constructor
    // via createPlanFromArray(), because both defaults resolve to ''.
    report($e);
}
```

--------------------------------

### RedirectIfUserNotSubscribed::handle() signature

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

Signature of the handle() method in the RedirectIfUserNotSubscribed middleware. It accepts the incoming request, the next middleware closure, and variadic plan names. The docblock declares an Exception throw and documents the $next parameter type.

```php
/**
 * @param  Closure(Request): (Response)  $next
 *
 * @throws Exception
 */
public function handle(Request $request, Closure $next, string ...$plans): Response
```

--------------------------------

### BillingProvider::__construct

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Constructor for the BillingProvider class. Accepts plan name(s) used to build the subscription middleware. The class is final and readonly, so all state is fixed at construction time.

```APIDOC
## BillingProvider::__construct

### Description
Constructor for the BillingProvider class. Accepts plan name(s) used to build the subscription middleware. The class is final and readonly, so all state is fixed at construction time.

### Method
Constructor

### Signature
```php
public function __construct(
    private string|BackedEnum|array $plans = 'default',
)
```

### Parameters
- **plans** (`string|BackedEnum|array<array-key, string|BackedEnum>`) - Optional - Default: `'default'` - Plan name(s) used to build the subscription middleware. A single plan name (`string`), an enum case (`BackedEnum`), an array of either, or a comma-separated string (e.g. `'basic,advanced,premium'`).

### Return Type
`BillingProvider` (the class itself). The class is `readonly`, so all state is fixed at construction time.

### Throws
None. Construction only stores the value; validation of plan names happens later in `Plan` / `PlanRepository` when the middleware resolves plans.
```

--------------------------------

### Composer auto-discovery configuration for FilamentCashierServiceProvider

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/FilamentCashierServiceProvider.md

JSON configuration in composer.json that enables Laravel's auto-discovery of the service provider.

```json
"extra": {
    "laravel": {
        "providers": [
            "Maartenpaauw\\Filament\\Cashier\\FilamentCashierServiceProvider"
        ]
    }
}
```

--------------------------------

### Catch Exception in RedirectIfUserNotSubscribed::handle()

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/errors.md

Catch broad Exception around the middleware handle call to handle Stripe/Cashier exceptions. The middleware calls $tenant->newSubscription(...), chains SubscriptionBuilder options, and invokes ->checkout()->redirect(), which can raise API errors, invalid price IDs, or metered-price misuse. The catch block reports the exception and redirects to the Filament admin dashboard.

```php
use Exception;

try {
    $response = $middleware->handle($request, $next, 'default');
} catch (Exception $e) {
    report($e);

    return redirect()->route('filament.admin.dashboard');
}
```

--------------------------------

### TenantRepository::current() guard clauses throwing LogicException

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/errors.md

Two guard clauses in TenantRepository::current() that throw LogicException when the Filament tenant does not match the Cashier customer model or when the tenant model does not use the Cashier Billable trait. The mismatch guard compares the tenant class to Cashier::$customerModel (config('cashier.model')); the trait guard uses class_uses_recursive to check for the Billable trait in the class hierarchy. Both run on every call of current(), which is invoked by the billing route action and subscription middleware, so misconfiguration surfaces as a 500 during those requests.

```php
if ($tenant::class !== Cashier::$customerModel) {
    throw new LogicException(message: 'Filament tenant does not match the Cashier customer model');
}

if (! in_array(needle: Billable::class, haystack: class_uses_recursive($tenant), strict: true)) {
    throw new LogicException(message: 'Tenant model does not use Cashier Billable trait');
}
```

--------------------------------

### RedirectIfUserNotSubscribed checkout redirect logic

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/RedirectIfUserNotSubscribed.md

Builds a Stripe Checkout session when the tenant does not qualify for any of the given plans. Uses the first plan from $plans and conditionally applies meteredPrice(), trialDays(), allowPromotionCodes(), and collectTaxIds() based on plan flags. Redirects to the Dashboard on success and cancel URLs.

```php
return $tenant
    ->newSubscription(type: $plan->type, prices: $plan->isMeteredPrice ? [] : $plan->priceId)
    ->when(
        value: $plan->isMeteredPrice === true,
        callback: static fn (SubscriptionBuilder $subscription): SubscriptionBuilder => $subscription->meteredPrice(price: $plan->priceId),
    )
    ->when(
        value: $plan->hasGenericTrial === false && $plan->trialDays !== false,
        callback: static fn (SubscriptionBuilder $subscription): SubscriptionBuilder => $subscription->trialDays(trialDays: $plan->trialDays),
    )
    ->when(
        value: $plan->allowPromotionCodes === true,
        callback: static fn (SubscriptionBuilder $subscription): SubscriptionBuilder => $subscription->allowPromotionCodes(),
    )
    ->when(
        value: $plan->collectTaxIds === true,
        callback: static fn (SubscriptionBuilder $subscription): SubscriptionBuilder => $subscription->collectTaxIds(),
    )
    ->checkout(sessionOptions: [
        'success_url' => Dashboard::getUrl(),
        'cancel_url' => Dashboard::getUrl(),
    ])
    ->redirect();
```

--------------------------------

### Register BillingProvider in panel provider

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/README.md

Add the billing provider to your AdminPanelProvider (or other panel providers). The requiresTenantSubscription() call is optional and can be removed if you do not want to require a subscription.

```php
use Maartenpaauw\Filament\Cashier\Stripe\BillingProvider;

// ...

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->tenantBillingProvider(new BillingProvider('default'))
        ->requiresTenantSubscription()
        // ...
}
```

--------------------------------

### getRouteAction() closure body

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Body of the Closure returned by getRouteAction(). It resolves the current Filament tenant, ensures a Stripe customer ID exists (creating one if needed), then redirects to the Stripe billing portal with the Dashboard URL as the return URL. Indirectly throws LogicException when the tenant class does not match Cashier::$customerModel or the tenant model lacks the Billable trait; a fatal Error occurs if Filament::getTenant() resolves to null.

```php
$tenant = TenantRepository::make()->current();

if ($tenant->hasStripeId() === false) {
    $tenant->createAsStripeCustomer();
}

return $tenant->redirectToBillingPortal(returnUrl: Dashboard::getUrl());
```

--------------------------------

### getRouteAction()

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Returns a Closure that is invoked by Filament at the panel's billing route. It resolves the current tenant, ensures it has a Stripe customer ID, and redirects to the Stripe billing portal with the Dashboard URL as the return URL.

```APIDOC
## getRouteAction()

### Description
Returns a Closure that is invoked by Filament at the panel's billing route. It resolves the current tenant, ensures it has a Stripe customer ID, and redirects to the Stripe billing portal with the Dashboard URL as the return URL.

### Method
GET

### Endpoint
N/A (Closure)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **RedirectResponse** - Redirects to the Stripe billing portal.

#### Response Example
N/A

### Throws
- **LogicException** - When the tenant class does not match `Cashier::$customerModel` or when the tenant model does not use the `Billable` trait.
- **Error** - When `Filament::getTenant()` resolves to `null`.
```

--------------------------------

### getRouteAction() signature

Source: https://github.com/maartenpaauw/filament-cashier-billing-provider/blob/main/_autodocs/api-reference/BillingProvider.md

Signature of the getRouteAction() method, copied from lines 25–37 of the source. It returns a string, Closure, or array.

```php
#[Override]
public function getRouteAction(): string|Closure|array
```
Tokens:
Raw