README

kilden/laravel

Kilden is a customer data platform — analytics, campaigns and session replay on one event pipeline. This package wraps the PHP SDK for Laravel: a configured singleton, a facade, queued delivery, and the identity endpoint your frontend needs for identity verification.

Requires PHP 8.2+ and Laravel 11–13. For plain PHP (7.4+), use kilden/kilden-php directly.

Install

composer require kilden/laravel:@alpha kilden/kilden-php:@alpha

(Both @alpha flags are needed while we ship prereleases — Composer ignores stability flags on transitive requirements. They go away at 0.1.0.)

php artisan vendor:publish --tag=kilden-config

Set your secret write key — never the public wk_ one, which belongs in the browser SDK:

KILDEN_WRITE_KEY=sk_...

Track from anywhere

use Kilden\Laravel\Facades\Kilden;

Kilden::track($user->id, 'order_completed', ['revenue' => 99.9, 'currency' => 'CLP']);
Kilden::identify($user->id, ['plan' => 'pro', 'email' => $user->email]);

Events flush automatically at the end of the request (and on queue workers, when the job finishes). With KILDEN_QUEUE=true, calls dispatch a job instead of sending inline — the timestamp is stamped at call time, so nothing shifts.

Frontend in one line

@kildenScript renders the official web SDK loader in your layout — configured, identity-wired, and auto-identifying the logged-in user:

<head>
    ...
    @kildenScript
</head>

KILDEN_PUBLIC_WRITE_KEY=wk_...   # the PUBLIC key — never sk_ in a view

If your marketing site and your app live on different subdomains (example.com + app.example.com), one more env var makes the visitor survive the crossing — the anonymous id moves into a cookie both hosts can read, and first-touch attribution rides along:

KILDEN_COOKIE_DOMAIN=.example.com

Heads-up: this turns on cookies, which can affect your cookie-consent obligations — that is why it is off by default.

If the identity route below is registered, the snippet wires the SDK's getIdentityToken to it automatically, so browser events come out verified with zero extra code. The wiring resolves the route by name (kilden.identity), so a custom path — KildenRoutes::identity('/api/kilden-token') — is picked up without further configuration. Without KILDEN_PUBLIC_WRITE_KEY (or with KILDEN_ENABLED=false) the directive renders nothing.

Identity verification

The browser SDK can prove who its events belong to — but only your backend can sign that proof. One route makes it work:

// routes/web.php
use Kilden\Laravel\KildenRoutes;

KildenRoutes::identity();   // POST /kilden/identity, behind your auth middleware

KILDEN_IDENTITY_SECRET=...   # from your Kilden project settings
KILDEN_IDENTITY_KID=k1

The route signs a short-lived token for auth()->user() and returns { distinct_id, token, traits } — the web SDK refreshes against it automatically. To attach signed traits:

KildenRoutes::traitsUsing(fn ($user) => ['plan' => $user->plan]);

Only ever sign the authenticated user. Signing an id taken from request input lets anyone impersonate anyone — with a "verified" stamp on top.

Feature flags

if (Kilden::isEnabled('new_checkout', $user->id, ['default' => false])) {
    // ...
}

$variant = Kilden::getFeatureFlag('pricing_test', $user->id, [
    'person_properties' => ['plan' => $user->plan],
]);

Testing

use Kilden\Laravel\Facades\Kilden;

Kilden::fake();

// ... run code that tracks ...

Kilden::assertTracked('order_completed');
Kilden::assertNothingTracked();

With KILDEN_WRITE_KEY unset (or KILDEN_ENABLED=false) the client is a silent no-op, so test and local environments need no configuration at all.

About this repository

Read-only subtree split of kilden-sdk-php/packages/laravel — issues and pull requests go there. Behavior is governed by the server SDK spec.

License

MIT

kilden / laravel

Maintainers

Package info

Statistics

Security