PHP SDK

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

Server-side tracking. Use the PHP SDK to send events from your backend — ideal for tracking payments processed server-side, webhooks, or any event that shouldn't go through the browser.

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]']);

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:

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

Parameters

Parameter Type Description
amount required float Revenue amount in your default currency. Use negative values for refunds.
user_id required string Your internal user ID.
properties optional array Additional properties: email, currency, transaction_id, name, plus any custom keys.

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

Parameter Type Description
subscriptionId required string A stable identifier for the subscription (e.g. your database ID or payment provider's subscription ID). Must be the same across updates and cancellations.
userId required string Your internal user ID.
status required string One of: active, canceled, past_due, trialing, paused.
amount required float Amount per billing cycle (e.g. 29.00). Pass 0 when canceling.
interval optional string Billing interval: month (default), year, week, or day. Yearly plans are automatically normalized to monthly for MRR.
attributes optional array Additional properties: currency (3-letter code), name or plan (plan name), interval_count (e.g. 3 for quarterly).

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"
]);

How it works. Ripples auto-detects activation moments (first occurrence per user per action), computes adoption rates by product area, and correlates usage patterns with retention and payment.

Parameters

Parameter Type Description
actionName required string What the user did. Be specific: 'created a budget', not 'budgets'.
userId required string Your internal user ID.
area optional string Product area this action belongs to (e.g. 'budgets', 'reports'). Groups actions in the dashboard.
activated optional bool Set to true on the specific occurrence when activation happens for this user. This does not mark the event type as an activation event — it marks this particular moment as when the user activated. For example, 'sent message' is a regular event, but when a user sends their 10th message you may consider that their activation moment and send that occurrence with activated => true.

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([...]);

        $ripples = new Ripples();
        $ripples->signup($user->id, [
            'email'           => $user->email,
            'name'            => $user->name,
            'ripples_visitor_id' => $request->cookie('_rpl_vid'),
        ]);

        return $user;
    }
}

Tip: pass the visitor ID. Include ripples_visitor_id with the value from the _rpl_vid cookie to link this signup back to the anonymous browsing session and correct traffic source attribution.

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',
    'company'    => 'Acme Inc',  // custom property
    'role'       => 'admin',      // custom property
]);

Properties

Key Type Description
email optional string User's email address. Shown in the visitor profile and used for Stripe revenue attribution.
name optional string Display name shown in the visitor profile.
avatar_url optional string URL to the user's avatar image. Displayed in the visitor profile. Also accepted as avatar.
[custom] optional string | number Any additional traits you want to attach to the user (e.g. plan, company, role).

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

Option Default Description
base_url https://api.ripples.sh API endpoint. Override for self-hosted deployments.
timeout 5 HTTP request timeout in seconds.

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