PHPackages ripplesanalytics/ripples-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. ripplesanalytics/ripples-php ActiveLibrary[Utility & Helpers](/categories/utility) ripplesanalytics/ripples-php ============================ Official PHP SDK for Ripples.sh — server-side event tracking 027↓90.1%PHPCI failing Since Apr 19Pushed 2mo agoCompare [ Source](https://github.com/ripplesanalytics/ripples-php)[ Packagist](https://packagist.org/packages/ripplesanalytics/ripples-php)[ RSS](/packages/ripplesanalytics-ripples-php/feed)WikiDiscussions main Synced 4w ago READMEChangelogDependenciesVersions (1)Used By (0) Ripples PHP SDK =============== [](#ripples-php-sdk) Server-side PHP SDK for [Ripples.sh](https://ripples.sh) analytics. Install ------- [](#install) ``` composer require ripples/ripples-php ``` Add to your `.env`: ``` RIPPLES_SECRET_KEY=priv_your_secret_key ``` Usage ----- [](#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 ------------------- [](#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) ------------------------- [](#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 ------------- [](#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 ------------- [](#track-signups) ``` $ripples->signup('user_123', [ 'email' => 'jane@example.com', 'name' => 'Jane Smith', 'referral' => 'twitter', // custom property 'plan' => 'free', // custom property ]); ``` Identify users -------------- [](#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 -------------------------- [](#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 -------------- [](#error-handling) ``` use Ripples\RipplesException; try { $ripples->revenue(49.99, 'user_123'); } catch (RipplesException $e) { // handle error } ``` Configuration ------------- [](#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 ------------------ [](#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 ------------ [](#requirements) - PHP 8.1+ - ext-curl - ext-json License ------- [](#license) MIT ### Health Score 21 — LowBetter than 18% of packages Maintenance57 Moderate activity, may be stable Popularity8 Limited adoption so far Community6 Small or concentrated contributor base Maturity12 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/fd0fad0be5bdeb93f8acf6c59b9e1958fb0db9bd9ae9329baa705546e82c9f47?d=identicon)[zhavoronkov](/maintainers/zhavoronkov) --- Top Contributors [![zhavoronkov](https://avatars.githubusercontent.com/u/8795787?v=4)](https://github.com/zhavoronkov "zhavoronkov (3 commits)") ### Embed Badge ![Health badge](/badges/ripplesanalytics-ripples-php/health.svg) ``` [![Health](https://phpackages.com/badges/ripplesanalytics-ripples-php/health.svg)](https://phpackages.com/packages/ripplesanalytics-ripples-php) ``` ### Alternatives [michaels/data-manager Simple data manager for nested data, dot notation array access, extendability, and container interoperability. 121.9k2](/packages/michaels-data-manager) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)