README

Disclaimer

Note: This is not an official Laravel package. This is a community-built package following Laravel Cashier principles and is currently a work in progress.

Introduction

Cashier Polar provides an expressive, fluent interface to Polar's subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading writing.

Requirements

• PHP 8.3+
• Laravel 10.0+ / 11.0+
• Polar account and API credentials (https://polar.sh)

Installation

composer require mafrasil/cashier-polar

php artisan vendor:publish --tag="cashier-polar-migrations"
php artisan migrate

php artisan vendor:publish --tag="cashier-polar-config"

Configuration

POLAR_API_KEY=your-api-key
POLAR_ORGANIZATION_ID=your-organization-id
POLAR_WEBHOOK_SECRET=your-webhook-secret
POLAR_SANDBOX=true # Set to false for production

Generate a webhook secret:

php artisan cashier-polar:webhook-secret

Basic Usage

Setup Billable Model

use Mafrasil\CashierPolar\Concerns\Billable;

class User extends Authenticatable
{
    use Billable;
}

Create a Checkout Session

// Simple checkout
$checkout = $user->checkout('price_id');

// With options
$checkout = $user->checkout('price_id', [
    'success_url' => route('checkout.success'),
    'cancel_url' => route('checkout.cancel'),
]);

// Redirect to checkout
return redirect($checkout['url']);

Access Subscriptions

// Get subscription details
$subscription = $user->subscription;

echo $subscription->name;            // Get subscription name
echo $subscription->price;          // Get formatted price (e.g., "10.00 USD")
echo $subscription->interval;       // Get billing interval (e.g., "month")
echo $subscription->description;    // Get subscription description

// Check status
if ($subscription->valid()) {
    // Active, on trial, or on grace period
}

if ($subscription->active()) {
    // Currently active
}

// Trial handling
if ($subscription->onTrial()) {
    echo $subscription->trialEndDate();      // "2024-01-21"
    echo $subscription->daysUntilTrialEnds(); // Days remaining
}

// Cancellation handling
if ($subscription->cancelled()) {
    if ($subscription->onGracePeriod()) {
        echo $subscription->endDate();        // "2024-01-21"
        echo $subscription->daysUntilEnds();  // Days remaining
    }
}

// Check specific plan
if ($user->subscribedToPlan('premium')) {
    // Subscribed to premium plan
}

Manage Subscriptions

// Cancel
$subscription->cancel();     // End of period

// Resume (during grace period)
$subscription->resume();

Webhook Events

The package automatically handles these webhook events:

• checkout.created
• checkout.updated
• order.created
• subscription.created
• subscription.updated
• subscription.active
• subscription.revoked
• subscription.canceled

Listen for Events

// EventServiceProvider.php
use Mafrasil\CashierPolar\Events\SubscriptionCreated;

Event::listen(function (SubscriptionCreated $event) {
    $subscription = $event->subscription;
    $user = $subscription->billable;

    // Handle event
});

Testing

composer test

Credits

• mafrasil
• All Contributors

License

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