SDKsPreview · 3 min read

Symfony Bundle

Use perkamo/symfony-bundle when a Symfony application needs both trusted backend events and a browser SDK token route. The bundle supports Symfony 6.4 LTS, Symfony 7.4 LTS and Symfony 8. Symfony 8 requires PHP 8.4+.

Install

bash

composer require perkamo/symfony-bundle

Configure

yaml

perkamo:
  api_key: "%env(PERKAMO_SECRET_KEY)%"

Backend event calls use the configured server API key to identify the Space. The bundle defaults to the hosted Perkamo API. Configure base_url only when Perkamo support supplies a different API URL.

Browser token routes are optional. Create a signing key in the Perkamo console under Settings → Security → Signing keys. It gives you a KID (shown in the creation dialog and then listed in the table) and a one-time secret (shown once, backend-only). Enable perkamo.browser and wire both — the %env(...)% names are your own choice:

yaml

perkamo:
  api_key: "%env(PERKAMO_SECRET_KEY)%"
  browser:
    enabled: true
    kid: "%env(PERKAMO_SIGNING_KID)%" # KID
    secret: "%env(PERKAMO_SIGNING_SECRET)%" # backend-only

Key	What it is
`kid`	KID of your signing key; goes in the token header. Safe to expose.
`secret`	The signing key's one-time secret that signs the token. Keep it backend-only.

When enabled, the bundle verifies the Symfony user session and self-signs a short-lived client token for @perkamo/browser. The token scope and event list are clamped to the signing key policy by Perkamo during client route verification; only the secret is sensitive — the kid is public.

Backend services can autowire Perkamo\Client and emit trusted events with the server API key. The same service can call identify() for trusted customer traits, or program() and eventCatalog() for backend admin tooling that needs configured event keys and labels. API failures throw Perkamo\Exception\PerkamoApiException with request id, retry-after and rate-limit metadata when available.

The bundle exposes application-local token endpoints for frontend code:

GET /api/perkamo/browser/config
POST /api/perkamo/token
POST /api/perkamo/stream-token

Import the bundle routes only when you enable those browser endpoints:

yaml

perkamo:
  resource: "@PerkamoSymfonyBundle/config/routes.php"
  type: php

By default, client token subjects come from the current Symfony security user identifier. For a custom customer/customer id mapping, implement Perkamo\SymfonyBundle\Security\UserIdResolverInterface and configure perkamo.browser.user_id_resolver.

Twig Helper

twig

{{ perkamo_browser_bundle_script() }}

The helper loads the CDN build of @perkamo/browser by default and defines window.PerkamoSymfony.createClient(). The generated browser config includes browser bundle metadata, local token endpoints and a custom API endpoint only when base_url is configured. It never includes the server API key, signing secret or Space ID.

The generated client uses Perkamo /v1/client/* routes after it receives a client token. Token subjects, scopes and allowed event names remain constrained by the signing key policy configured for the Space.

The CDN URL is pinned to the browser package version bundled with this Symfony bundle, not the npm latest dist-tag. Override perkamo.browser.bundle.version only when you intentionally choose a different compatible @perkamo/browser version.

Use perkamo.browser.bundle.path for a global self-hosted bundle path. Include version only when the self-hosted file is not the bundle default:

yaml

perkamo:
  browser:
    bundle:
      path: "/build/perkamo-browser.global.min.js"

Or override the script path in one template:

twig

{{ perkamo_browser_bundle_script(asset("build/perkamo-browser.global.min.js")) }}

html

<script>
  window.addEventListener("DOMContentLoaded", function () {
    var perkamo = window.PerkamoSymfony.createClient();
    perkamo.emit("page.viewed", { path: window.location.pathname });
  });
</script>

Client token routes require an authenticated application session. Do not expose these endpoints publicly without your normal Symfony security rules.

PHP SDK

Realtime streaming