Download the PHP package cocosport/rybbit-sdk-for-laravel without Composer

A simple, elegant Laravel package for integrating Rybbit analytics into your application. This SDK provides a clean, Laravel-native way to add Rybbit's privacy-friendly, open-source analytics to your app.

Table of Contents

• Features
• Feature Coverage
• Installation
  • Publishing the Configuration File
• Configuration
• Usage
  • Injecting the tracking script
  • Sending events server-side
  • Querying users
  • Querying overview stats
  • The tunnel
  • Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Features

• @rybbit Blade directive — injects the Rybbit tracking script with a single tag, with support for the data-debounce, data-tag, data-skip-patterns, data-mask-patterns, and session replay script options.
• Server-side event tracking — the Rybbit facade sends pageviews, custom events, performance metrics, outbound clicks, and errors straight to Rybbit's /api/track endpoint from your backend.
• User queries and deletion — look up a site's users, a specific user's profile and devices, and their daily session counts through Rybbit's read API, or delete a user's tracked data.
• Overview stats — headline KPIs, bucketed time series, live visitor count, and dimension breakdowns (pages, countries, browsers, ...) for the configured site, e.g. for a daily-active-users chart.
• First-party tunnel — proxies tracking requests (script, track, identify, session replay, site config) through your own domain instead of Rybbit's, so the script isn't blocked by ad blockers or browser tracking protections.
• Client IP forwarding — the tunnel resolves the real visitor IP from X-Forwarded-For and forwards it to Rybbit, so proxied traffic is still attributed correctly.
• Resilient forwarding — failed tunnel requests are retried, optionally logged, and never cache a failed response; session replay data is forwarded through a queued job so it never blocks the request/response cycle.
• Rybbit::fake() — swap in an in-memory fake for your tests, with assertions for every tracking and user-query method and no real HTTP requests made.
• Laravel Boost skill — ships a rybbit-development Agent Skill that Laravel Boost auto-installs for your AI coding agent when you run php artisan boost:install, so it already knows how to use this package correctly.

Feature Coverage

This SDK wraps the slice of Rybbit's platform our organization actually uses: embedding the tracking script, tunneling it through your own domain, sending events server-side, and reading back user data. Rybbit's full API and dashboard cover a lot more ground that this package doesn't touch, notably:

• Goals & Funnels — conversion and drop-off analysis.
• Sessions, Session Replay, Insights, Performance, Errors, and Bots queries — analytics read endpoints beyond what Rybbit::users() and Rybbit::overview() expose (the tunnel forwards session replay recording, but nothing here queries it back).
• Organizations, Teams, Sites, API Keys, and Data Import — account and site administration endpoints.

We don't plan to cover all of Rybbit's features anytime soon, since this package tracks what we actually need. If you need one of the above (or anything else Rybbit offers), open an issue describing your use case and we'll add it, or send a pull request — see Contributing.

Installation

You can install the package via Composer:

You may publish all of the package's resources at once:

Or, you may publish each resource individually:

Publishing the Configuration File

Configuration

At a minimum, set your site ID:

By default the package points at Rybbit Cloud (https://app.rybbit.io). If you self-host Rybbit, point the SDK at your instance instead:

See the published config/rybbit.php for every available option (script attributes, tunnel behavior, logging, queueing, ...) — each one is documented inline.

Usage

Injecting the tracking script

Add the @rybbit Blade directive to your layout, typically right before </head> or </body>:

It renders nothing unless RYBBIT_SITE_ID is set. Otherwise, it outputs:

The src points at your own tunnel (see below) when the tunnel is enabled, or straight at your configured RYBBIT_HOST when it's disabled.

Set any of the script config options to add the matching data-* attribute:

Session replay attributes (data-replay-*) live under script.replay in the same config file, and only apply when session replay is enabled in your Rybbit site settings.

See the full tracking script documentation for every attribute and what it does.

Sending events server-side

Use the Rybbit facade to send tracking events straight to Rybbit's /api/track endpoint from your backend — useful for events that don't happen in the browser, like webhook-driven purchases or background jobs. Set RYBBIT_SITE_SEQ_ID (your site's internal numeric ID, shown in the Rybbit dashboard) and, for authenticated tracking that bypasses bot detection, RYBBIT_API_KEY.

Each method accepts an optional trailing array $data of additional top-level fields from the request body (user_id, hostname, referrer, ...). For full control over the payload, or to send a type not covered by a dedicated method, call send() directly:

pathname, hostname, user_agent, ip_address, and querystring default to the current request, and user_id defaults to the authenticated user's ID — so a call made from a controller or middleware doesn't need to repeat them. Pass any of them in $data to override, and they're dropped entirely when empty (e.g. user_id when nobody's authenticated, or when running outside an HTTP request).

Configure how user_id is resolved via RYBBIT_USER_GUARD (which auth guard to check) and RYBBIT_USER_KEY (an attribute or method to read off the resolved user, e.g. uuid or publicKey, instead of the default getAuthIdentifier()):

Every method returns the decoded JSON response as an array (e.g. ['success' => true]), or null if the request couldn't reach Rybbit at all. Failed requests are logged (see RYBBIT_LOGS) and, when RYBBIT_THROW_ON_ERROR is enabled, raise a RequestException or ConnectionException instead of failing silently.

Querying users

Use Rybbit::users() to read a site's users through Rybbit's API — this always requires RYBBIT_API_KEY.

list() returns every user for the site, paginated; sessionCount() returns a user's daily session counts, keyed by date; find() returns one user's full profile — traits, locations, devices, and linked devices; delete() removes a user's tracked data from the site. Like the tracking methods above, each returns the decoded JSON response as an array, or null if the request couldn't reach Rybbit at all — see the linked docs for the exact payload shape.

Querying overview stats

Use Rybbit::overview() to read the configured site's headline stats, time series, live visitor count, and dimension breakdowns through Rybbit's API — this always requires RYBBIT_API_KEY.

summary() returns headline KPIs (sessions, pageviews, unique users, bounce rate, ...) for the given range; timeSeries() returns the same KPIs bucketed over time — pass bucket as TimeBucket::Day for a daily-active-users chart (read the users field per bucket), or TimeBucket::Hour/Week/Month/Year for other granularities; liveVisitors() returns the number of unique visitors active right now; metric() breaks traffic down by a single FilterParameter dimension (Pathname, Country, Browser, EventName, ...); pageTitles() returns the site's most visited page titles. Omit the date range on summary(), timeSeries(), and metric() to query all time. Like the tracking and user methods above, each returns the decoded JSON response as an array, or null if the request couldn't reach Rybbit at all.

The tunnel

Browser tracking scripts and requests are frequently blocked by ad blockers and browser privacy features. To work around this, the package registers routes under RYBBIT_TUNNEL_URL (default /rybbit) that transparently proxy the script, track, identify, session replay, and site config requests through to Rybbit.

It's enabled by default — point the @rybbit directive's src at your own domain instead of Rybbit's for free. Disable it if you'd rather talk to Rybbit directly:

Customize the local path prefix, cache key prefix, and route middleware via config/rybbit.php.

Testing

Call Rybbit::fake() in your tests to swap in an in-memory fake — no real HTTP requests are made, and every call is recorded for assertions:

Without a stub, faked calls return a sensible default (['success' => true] for tracking calls and delete(), an empty data payload for the other user and overview queries) so code under test that reads the response doesn't have to handle null. Pass stubs keyed by symbolic call name (pageview, custom_event, performance, outbound, error, users.list, users.sessionCount, users.find, users.delete, overview.summary, overview.timeSeries, overview.liveVisitors, overview.metric, overview.pageTitles) to control what's returned:

Changelog

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

Contributing

Thank you for considering contributing to Rybbit Sdk For Laravel! Please review our contributing guide to get started.

Security Vulnerabilities

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

Credits

• Carlo Eusebi
• All Contributors

License

Rybbit Sdk For Laravel is open-sourced software licensed under the MIT license.