README

A comprehensive SaaS metrics analyzer for Laravel that provides actionable insights for subscription-based businesses. Track MRR, churn rate, LTV, ARPU, and cohort analysis with support for Stripe, Paddle, and custom billing providers.

Highlights

• 📊 Pre-built Metric Calculators - MRR, churn rate, LTV, ARPU, and cohort analysis
• 🔌 Multi-Provider Support - Works with Stripe, Paddle, LemonSqueezy, or custom billing
• ⚡ Cache-First Architecture - Intelligent caching with automatic invalidation
• 🎨 Dashboard Components - Ready-to-use Blade components for Laravel
• 📈 Cohort Analysis - First-class cohort tracking with retention curves
• 🔄 Auto Recalculation - Background jobs keep metrics fresh

Installation

You can install the package via composer:

composer require plusinfolab/cashier-saas-metrics

You can publish and run the migrations with:

php artisan vendor:publish --tag="saas-metrics-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="saas-metrics-config"

This is the contents of the published config file:

return [
    'provider' => env('SAAS_METRICS_PROVIDER', 'stripe'),
    'base_currency' => env('SAAS_METRICS_BASE_CURRENCY', 'USD'),
    // ... other configuration
];

Usage

Basic Metrics

use PlusInfoLab\CashierSaaSMetrics\Facades\Metrics;

// Get current MRR
$mrr = Metrics::mrr()->calculate();
echo $mrr->formattedAsCurrency(); // "$42,500.00"

// Get churn rate
$churnRate = Metrics::churnRate()->calculate();
echo $churnRate->formattedAsPercentage(); // "4.25%"

// Get LTV
$ltv = Metrics::lifetimeValue()->calculate();
echo $ltv->formattedAsCurrency(); // "$1,200.00"

// Get ARPU
$arpu = Metrics::arpu()->calculate();
echo $arpu->formattedAsCurrency(); // "$85.00"

Filtering and Grouping

// Filter by period
$mrrThisMonth = Metrics::mrr()
    ->period('last_month')
    ->calculate();

// Filter by plan
$proMrr = Metrics::mrr()
    ->plan('pro')
    ->calculate();

// Group by field
$mrrByPlan = Metrics::mrr()
    ->groupBy('plan')
    ->calculate();

// Filter by currency
$usdMrr = Metrics::mrr()
    ->currency('USD')
    ->calculate();

Cohort Analysis

$cohorts = Metrics::cohorts()
    ->period('last_6_months')
    ->by('signup_month')
    ->retentionMetric('mrr')
    ->calculate();

// Returns cohort data with retention curves
foreach ($cohorts->value as $cohortKey => $cohortData) {
    foreach ($cohortData['periods'] as $period) {
        echo "Period {$period['period']}: {$period['retention_percentage']}% retention\n";
    }
}

Dashboard Components

<x-saas-metrics::metrics-panel title="SaaS Dashboard" />

Or use individual metric cards:

<x-saas-metrics::metric-card
    :title="'Monthly Recurring Revenue'"
    :value="$mrr"
    icon="heroicon-o-currency-dollar"
    color="green"
/>

All Metrics at Once

$dashboard = Metrics::dashboard('this_month');

/*
[
    'mrr' => MetricResult(42500),
    'churn_rate' => MetricResult(0.0425),
    'ltv' => MetricResult(1200),
    'arpu' => MetricResult(85),
    'period' => 'this_month',
    'currency' => 'USD',
]
*/

Subscription Providers

Stripe (using Laravel Cashier)

// config/saas-metrics.php
'provider' => 'stripe',

'providers' => [
    'stripe' => [
        'api_key' => env('STRIPE_SECRET'),
        'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
    ],
],

Paddle

'provider' => 'paddle',

'providers' => [
    'paddle' => [
        'vendor_id' => env('PADDLE_VENDOR_ID'),
        'auth_code' => env('PADDLE_AUTH_CODE'),
    ],
],

Custom Provider

'provider' => 'custom',

'providers' => [
    'custom' => [
        'models' => [
            'subscription' => App\Models\Subscription::class,
            'payment' => App\Models\Payment::class,
        ],
        'field_map' => [
            'id' => 'id',
            'status' => 'status',
            'amount' => 'amount',
            // ... map your model fields
        ],
    ],
],

Cache Invalidation

The package automatically invalidates cache when subscription events occur. You can dispatch events manually:

use PlusInfoLab\CashierSaaSMetrics\Events\SubscriptionCreated;
use PlusInfoLab\CashierSaaSMetrics\Events\SubscriptionCancelled;
use PlusInfoLab\CashierSaaSMetrics\Events\SubscriptionUpdated;

// When a subscription is created
event(new SubscriptionCreated($subscriptionId, $customerId));

// When a subscription is cancelled
event(new SubscriptionCancelled($subscriptionId, $customerId));

// When a subscription is updated
event(new SubscriptionUpdated($subscriptionId, $customerId, $changes));

Or clear cache manually:

// Clear all metrics cache
Metrics::clearCache();

// Clear specific metric cache
Metrics::clearMetricCache('mrr');

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• PlusInfoLab
• All Contributors

License

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