PHP SDK

Track revenue, signups, product usage, and user identity from your PHP backend using the official Ripples SDK.

Install

composer require ripplesanalytics/ripples-php

Add your secret key to your .env:

RIPPLES_SECRET_KEY=priv_your_secret_key

Your secret key can be found in your Ripples dashboard under Settings → API Keys.

Quick start

use Ripples\Ripples;

$ripples = new Ripples();

// Track a payment
$ripples->revenue(49.99, 'user_123');

// Track a signup
$ripples->signup('user_123', ['email' => '[email protected]']);

// Track product usage
$ripples->track('created a budget', 'user_123', ['area' => 'budgets']);

// Identify / update a user
$ripples->identify('user_123', [
    'email' => '[email protected]',
    'signed_up_at' => $user->created_at->toIso8601String(),
]);

Track revenue

Call revenue() whenever a payment is processed on your server:

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

Pass extra context as a third argument. Any key that isn’t a known field becomes a custom property automatically:

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

Refunds are negative revenue. Give each refund its own transaction_id (your refund’s id, or the payment’s id plus a suffix) and point at the payment with original_transaction_id. One call per refund, partial refunds included:

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

A refund sent under the payment’s own transaction_id is still recorded, keyed by the payment id and the refund’s time, so a retry of the same call is not counted twice. Its own id is still the safer contract: two refunds sent in the same second under the payment’s id would collapse into one.

Pass a DateTimeInterface as the fourth argument to record a payment or refund when the money actually moved, e.g. when importing history:

$ripples->revenue(99.00, 'user_123', ['transaction_id' => 'invoice:812'], new DateTimeImmutable('2021-03-01 10:00'));

Revenue for a user Ripples has not seen yet is kept on that user: Ripples creates the person under your user_id, and their later identify() or signup() (from your server or the browser) lands on the same person and still records their signup. So identify() and revenue() for a new user can go in the same flush, in either order. Pass signed_up_at to that identify() so the signup is dated correctly.

Parameters

Track subscriptions (MRR)

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

// 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);

When importing history, pass the real dates. Without canceled_at a cancel is dated the day Ripples receives it, which puts every historical churn on the import day:

$ripples->subscription('sub_123', 'user_456', 'canceled', 29.00, 'month', [
    'started_at'  => new DateTimeImmutable('2021-01-05'),
    'canceled_at' => new DateTimeImmutable('2023-05-10'),
]);

Trials (trialing) are not counted in MRR: they show beside it until the subscription turns active. past_due still counts, since the payment is owed.

Auto-renew off is not a cancel

canceled means the subscription has ended: nothing grants access and nothing will bill. Ripples drops it from MRR and dates the churn at canceled_at. A subscriber who switched auto-renew off has not churned yet: they are paid up, or still in their trial, until the period ends. Report that as the live status plus renews => false and the date the period ends:

// Free trial started: report the price it will bill at, not the trial's 0
$ripples->subscription('sub_123', 'user_456', 'trialing', 9.99, 'month', [
    'renews'         => true,
    'period_ends_at' => new DateTimeImmutable('2026-10-14T08:10:00Z'),
]);

// They turned auto-renew off during the trial: still trialing, won't convert
$ripples->subscription('sub_123', 'user_456', 'trialing', 9.99, 'month', [
    'renews'         => false,
    'period_ends_at' => new DateTimeImmutable('2026-10-14T08:10:00Z'),
]);

// The period ran out: now it is canceled, dated when access ended
$ripples->subscription('sub_123', 'user_456', 'canceled', 9.99, 'month', [
    'canceled_at' => new DateTimeImmutable('2026-10-14T08:10:00Z'),
]);

A paid subscription with renews => false stays in MRR until it ends and is also counted as ending_mrr. A trial with renews => false is left out of trial_mrr, since it will not convert. If you never send the final canceled, Ripples ends a non-renewing subscription itself at period_ends_at, which covers a webhook that never arrived. Leaving renews out keeps the last value Ripples was told; a subscription that never reported it is treated as renewing.

Reporting state is idempotent: send the whole current state on every store notification and every reconcile, not only on changes.

amount is what the next billing cycle charges: Apple’s renewalPrice, not the trial transaction’s 0, so that trial_mrr and the MRR a trial converts into are both right.

Apple has no renewalPrice once auto-renew is off, since there is no next period. For a trial that will not convert, or a subscription that has ended, send 0: no number reads that amount, and Ripples keeps the plan it already has on a cancel. Do not skip the call, because the state is what changed.

Parameters

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.

// Significant product usage — user created something
$ripples->track('created a budget', 'user_123', [
    'area' => 'budgets',   // optional: group into a product area
]);

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

Parameters

Track milestones

A milestone is a moment in a person’s lifecycle that you count once per person, date by when they first reached it, and attribute to how they were acquired: mql, sql, demo_requested, demo_held, email_verified, onboarding_completed. It is not product usage, so it never feeds activation or retention. See Track Milestones for the rule of thumb and the recommended names.

// A known user, dated by when it happened (the CRM's stage-change time)
$ripples->milestone('mql', userId: (string) $user->id, properties: ['source' => 'hubspot'], timestamp: $changedAt);

// A lead with no account yet: the tracker cookie (read automatically under PHP-FPM) or a verified email
$ripples->milestone('demo_requested', email: $form->email, properties: ['company_size' => $form->size]);

Parameters

At least one of userId, a visitor (cookie, setVisitorId() or visitorId) or email is required; a milestone naming nobody is not sent and is passed to on_error. In a request that is not the person’s own (an admin marking a user as SQL), the cookie belongs to the admin: send it from a queue job, where no cookie is read.

Track signups

Call signup() when a new user registers:

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

Laravel example

use Ripples\Ripples;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $user = User::create([...]);

        // Same request as the form submit: the SDK reads the tracker's
        // _rpl_vid cookie by itself, so the signup keeps its traffic source.
        $ripples = new Ripples();
        $ripples->signup($user->id, [
            'email' => $user->email,
            'name'  => $user->name,
        ]);

        return $user;
    }
}

Identify users

Call identify() to update user traits at any time — on login, plan change, profile update, etc.:

$ripples->identify('user_123', [
    'email'        => '[email protected]',
    'name'         => 'Jane Smith',
    'avatar_url'   => 'https://example.com/avatars/jane.jpg',
    'signed_up_at' => $user->created_at->toIso8601String(),
    'company'      => 'Acme Inc',  // custom property
    'role'         => 'admin',      // custom property
]);

Properties

Track companies

For B2B products: say which company a user works in with group(). Call it at signup, when a user joins or switches company, and when the company’s traits change:

$ripples->group($user->id, $team->id, [
    'name'  => $team->name,   // shown instead of the id
    'plan'  => 'business',
    'seats' => 25,
]);

// No company needed on later calls: this counts for $team.
$ripples->track('created a report', $user->id);

Ripples remembers who works where, so nothing has to be passed on each call. Traits merge into what the company already has. Pass null as the user to update a company’s traits only, e.g. from a nightly sync. Use your own id for the company, never its name. See Track Companies for how it works.

Error handling

use Ripples\RipplesException;

try {
    $ripples->revenue(49.99, 'user_123');
} catch (RipplesException $e) {
    // Log or handle gracefully — never block the user flow
    Log::warning('Ripples error: ' . $e->getMessage());
}

Configuration

The SDK reads RIPPLES_SECRET_KEY from your environment automatically. You can also pass it explicitly:

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

The self-hosted URL can also be set via env:

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

Configuration options

Queue workers and long-running processes

The SDK sends its queue when PHP shuts down and whenever 100 events have accumulated. A queue worker (php artisan queue:work, Horizon, a daemon) never shuts down between jobs, so its events wait for the 100th, and are lost if the worker is killed first. Call flush() at the end of every job:

public function handle(Ripples $ripples): void
{
    $ripples->revenue($this->payment->amount, (string) $this->payment->user_id, [
        'transaction_id' => 'payment:' . $this->payment->id,
    ]);

    $ripples->flush();
}

Or construct the client with 'max_queue_size' => 1 so every call is sent as it is made.

Custom HTTP client

Extend the class and override post() to use Guzzle, Symfony HttpClient, or any other HTTP library:

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

Requirements

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