README

Server-side PHP SDK for Ripples.sh analytics.

Install

composer require ripples/ripples-php

Add to your .env:

RIPPLES_SECRET_KEY=priv_your_secret_key

Usage

use Ripples\Ripples;

$ripples = new Ripples();

$ripples->revenue(49.99, 'user_123');
$ripples->signup('user_123', ['email' => 'jane@example.com']);
$ripples->track('created a budget', 'user_123', ['area' => 'budgets']);
$ripples->identify('user_123', ['email' => 'jane@example.com']);

That's it.

Track product usage

Call track() only for significant product usage — actions that prove a user got real value (created a budget, sent a message, invited a teammate). This is not a generic event log like PostHog or Mixpanel: do not send pageviews, banner impressions, button clicks, or "viewed X" events. Every track() call feeds the Activation dashboard, so noise here pollutes your funnel. Ripples auto-detects activation (first occurrence per user), computes adoption rates, and correlates with retention and payment.

$ripples->track('created a budget', 'user_123', ['area' => 'budgets']);
$ripples->track('shared a list', 'user_123', ['area' => 'sharing', 'via' => 'link']);
$ripples->track('exported report', 'user_123', ['area' => 'reports', 'format' => 'csv']);

Use area to group actions into product areas. Use activated => true to mark the specific moment a user activates — it flags this occurrence, not the event type:

// User added their 10th transaction — we consider this their activation moment
$ripples->track('added transaction', 'user_123', [
    'area'      => 'transactions',
    'activated' => true,  // only on THIS occurrence
]);

Track subscriptions (MRR)

Call subscription() when a subscription is created, upgraded, downgraded, or canceled. This powers the MRR metric on your dashboard.

Stripe / Paddle users: MRR is tracked automatically via the integration. Only use this method if you use a payment provider without a native Ripples integration.

// User subscribes to Pro Monthly ($29/mo)
$ripples->subscription('sub_123', 'user_456', 'active', 29.00, 'month', [
    'name' => 'Pro',
    'currency' => 'EUR',
]);

// User upgrades to Business Annual ($499/yr)
$ripples->subscription('sub_123', 'user_456', 'active', 499.00, 'year', [
    'name' => 'Business',
]);

// User cancels
$ripples->subscription('sub_123', 'user_456', 'canceled', 0);

Parameters:

• subscriptionId (string, required) — stable identifier for the subscription
• userId (string, required) — your internal user ID
• status (string, required) — one of: active, canceled, past_due, trialing, paused
• amount (float, required) — amount per billing cycle (e.g. 29.00), pass 0 when canceling
• interval (string, optional) — month (default), year, week, or day
• attributes (array, optional) — currency, name or plan, interval_count

Track revenue

$ripples->revenue(49.99, 'user_123');

Any key you pass that isn't a known field becomes a custom property automatically:

$ripples->revenue(49.99, 'user_123', [
    'email'          => 'jane@example.com',
    'currency'       => 'EUR',
    'transaction_id' => 'txn_abc123',
    'name'           => 'Pro Plan',
    'plan'           => 'annual',       // custom property
    'coupon'         => 'WELCOME20',    // custom property
]);

Refunds are just negative revenue:

$ripples->revenue(-29.99, 'user_123', ['transaction_id' => 'txn_abc123']);

Track signups

$ripples->signup('user_123', [
    'email'    => 'jane@example.com',
    'name'     => 'Jane Smith',
    'referral' => 'twitter',    // custom property
    'plan'     => 'free',       // custom property
]);

Identify users

Update user traits at any time:

$ripples->identify('user_123', [
    'email'   => 'jane@example.com',
    'name'    => 'Jane Smith',
    'company' => 'Acme Inc',   // custom property
    'role'    => 'admin',      // custom property
]);

Backfill historical events

Pass a DateTimeInterface as the last argument to any tracking method to override the event's timestamp — useful when importing from a CSV, replaying from another analytics tool, or catching up after an outage.

foreach ($csvRows as $row) {
    $ripples->track(
        $row['action'],
        $row['user_id'],
        ['area' => $row['area']],
        new DateTimeImmutable($row['occurred_at']), // any tz — converted to UTC
    );
}
$ripples->flush(); // guarantee delivery at end of script

Naive behavior (no timestamp passed) uses "now" in UTC. Non-UTC timezones are converted automatically.

Error handling

use Ripples\RipplesException;

try {
    $ripples->revenue(49.99, 'user_123');
} catch (RipplesException $e) {
    // handle error
}

Configuration

The SDK reads RIPPLES_SECRET_KEY from your environment automatically. You can override everything:

$ripples = new Ripples('priv_explicit_key', [
    'base_url' => 'https://your-domain.com/api', // self-hosted
    'timeout'  => 10, // seconds (default: 5)
]);

Self-hosted URL can also be set via env:

RIPPLES_URL=https://your-domain.com/api

Custom HTTP client

Extend the class and override post() to use Guzzle, Symfony HTTP, or anything else:

class MyRipples extends \Ripples\Ripples
{
    protected function post(string $path, array $data): array
    {
        // your custom implementation
    }
}

Requirements

• PHP 8.1+
• ext-curl
• ext-json

License

MIT