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

composer require perkamo/symfony-bundle

Import the bundle routes manually; Symfony does not import routes from third-party bundles automatically:

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

The route file is PHP config so the bundle does not need symfony/yaml as a runtime dependency. type: php makes the route loader explicit.

Configure

perkamo:
  api_key: "%env(PERKAMO_SECRET_KEY)%"
  browser:
    key: "%env(PERKAMO_BROWSER_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 for a custom, staging or private endpoint. Browser token routes use browser.key, the public browser key from the Perkamo console. The bundle verifies the Symfony user session, calls Perkamo with the server API key and returns Perkamo's short-lived browser JWT. Browser key access policy is configured in Perkamo and enforced server-side. The Symfony bundle does not send scopes or event allowlists in token requests. Use * on the browser key to allow all current and future configured events. New browser keys default to the full browser SDK policy: customer reads, allowed browser events and customer streams.

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

By default, browser 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

{{ 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, browser key or Space ID.

The generated client uses preview Perkamo /v1/client/* routes after it receives a browser token. Until those routes are enabled for an integration, use the bundle for backend event emission and token issuing, and return customer state through your own backend controllers.

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:

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

Or override the script path in one template:

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

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

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