PHPackages                             perkamo/symfony-bundle - 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. [API Development](/categories/api)
4. /
5. perkamo/symfony-bundle

ActiveSymfony-bundle[API Development](/categories/api)

perkamo/symfony-bundle
======================

Symfony bundle for Perkamo backend and browser SDK integrations.

v0.9.0(3w ago)03MITPHPPHP >=8.2

Since Jun 3Pushed 3w agoCompare

[ Source](https://github.com/Perkamo/symfony-bundle)[ Packagist](https://packagist.org/packages/perkamo/symfony-bundle)[ RSS](/packages/perkamo-symfony-bundle/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (20)Versions (12)Used By (0)

`perkamo/symfony-bundle`
========================

[](#perkamosymfony-bundle)

Perkamo integration bundle for Symfony applications.

It provides:

- a configured [`perkamo/sdk`](https://packagist.org/packages/perkamo/sdk)backend client service,
- authenticated client-token and stream-token endpoints for `@perkamo/browser`,
- Twig helpers that load either the pinned CDN browser bundle or a self-hosted browser bundle path.

Compatibility
-------------

[](#compatibility)

- PHP 8.2+
- Symfony 6.4 LTS
- Symfony 7.4 LTS
- Symfony 8.x, which requires PHP 8.4+ through Symfony

Symfony 7.0 through 7.3 are intentionally not supported.

Install
-------

[](#install)

```
composer require perkamo/symfony-bundle
```

Register The Bundle
-------------------

[](#register-the-bundle)

Symfony Flex can enable the bundle from the package metadata. Without Flex, add it to `config/bundles.php`:

```
return [
    Perkamo\SymfonyBundle\PerkamoSymfonyBundle::class => ['all' => true],
];
```

Configure
---------

[](#configure)

```
# config/packages/perkamo.yaml
perkamo:
  api_key: "%env(PERKAMO_SECRET_KEY)%"
  timeout_seconds: 10
```

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 are optional. Create a signing key in the Perkamo console (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:

```
# config/packages/perkamo.yaml
perkamo:
  api_key: "%env(PERKAMO_SECRET_KEY)%"
  browser:
    enabled: true
    kid: "%env(PERKAMO_SIGNING_KID)%" # KID
    secret: "%env(PERKAMO_SIGNING_SECRET)%" # backend-only
```

KeyWhat 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.

The bundle registers `Perkamo\Client`, so backend services can use constructor injection:

```
use Perkamo\Client;
use Perkamo\EventInput;

final class CheckoutEvents
{
    public function __construct(private readonly Client $perkamo)
    {
    }

    public function completed(string $customerId, string $orderId): void
    {
        $event = EventInput::create($customerId, 'purchase.completed')
            ->withTransactionId($orderId)
            ->withContextValue('order_id', $orderId);

        $this->perkamo->emitEvent($event);
    }
}
```

The same autowired `Perkamo\Client` can read trusted admin metadata:

```
$perkamo->identify($customerId, [
    'email' => $customerEmail,
    'name' => $customerName,
]);

$events = $perkamo->eventCatalog();
```

Use `identify()` for trusted customer traits and `eventCatalog()` for backend admin screens that need configured event keys and labels. Non-2xx API responses throw `Perkamo\Exception\PerkamoApiException`, including request id, retry-after and rate-limit metadata when available.

Browser SDK Endpoints
---------------------

[](#browser-sdk-endpoints)

After importing the routes, the bundle exposes:

- `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:

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

The bundle ships route definitions as PHP config so `symfony/yaml` is not a runtime dependency of this package. Importing the PHP route file from your application YAML route config is supported by Symfony; `type: php` makes the loader explicit.

The token endpoints use the current Symfony security user identifier by default. For custom customer IDs, implement `Perkamo\SymfonyBundle\Security\UserIdResolverInterface` and configure:

```
perkamo:
  browser:
    user_id_resolver: App\Perkamo\CustomerIdResolver
```

The resolver may also set a request attribute named `perkamo_user_id` before the controller runs.

Twig Frontend Helper
--------------------

[](#twig-frontend-helper)

In a Twig layout:

```
{{ perkamo_browser_bundle_script() }}
```

The helper loads the browser bundle from jsDelivr by default and defines `window.PerkamoSymfony.createClient()`. The generated config includes browser bundle metadata, local token endpoints and a custom API endpoint only when `base_url` is configured. Frontend code can then create the preview browser client without handling token routes manually:

```

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

```

The generated frontend config 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. 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.

By default, the Twig helper loads the exact browser package version bundled with this Symfony bundle:

```

```

Override `perkamo.browser.bundle.version` only when intentionally using a different compatible browser package. To use a self-hosted bundle globally, configure a custom path:

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

For a one-off template override, pass your own path expression:

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

`perkamo_browser_sdk_script()` remains available as a backward-compatible alias, but new integrations should use `perkamo_browser_bundle_script()`.

Security Notes
--------------

[](#security-notes)

Use this package only from trusted Symfony backend code. The token routes require an authenticated Symfony user before they self-sign a short-lived client token. Never expose the server API key or signing secret to templates, JSON config endpoints, browser bundles, mobile apps or embedded widgets.

Client tokens are short-lived credentials signed locally by the Symfony application with a Perkamo signing key secret.

License
-------

[](#license)

MIT

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance94

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Every ~2 days

Total

11

Last Release

27d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/11a336cfb16ac061dacdcaf0deb633df9161e1486cef2ed1a5f237a0a05f76b4?d=identicon)[kur4tor](/maintainers/kur4tor)

---

Top Contributors

[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (12 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/perkamo-symfony-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/perkamo-symfony-bundle/health.svg)](https://phpackages.com/packages/perkamo-symfony-bundle)
```

###  Alternatives

[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9421.6k64](/packages/open-dxp-opendxp)[contao-community-alliance/dc-general

Universal data container for Contao

1680.8k92](/packages/contao-community-alliance-dc-general)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)