Save this content to: .cursor/rules/silverstripe.mdc

# Silverstripe adapter

Depends on core `Talaria\TalariaClient` (PHP) and the published npm package [`@newtalaria/browser`](https://www.npmjs.com/package/@newtalaria/browser) (JS). Integrate via Injector + Monolog + Requirements — minimal app code changes.

## PHP

- Support Silverstripe **4.13+ / 5 / 6** on PHP **8.1+**
- Composer: `monolog ^1.25 \|\| ^3`, `psr/log ^1 \|\| ^2 \|\| ^3` (do not pin `psr/log` to `^3` only)
- Dual Monolog handlers — one class cannot implement both `write(array)` and `write(LogRecord)`:
  - `Handlers\TalariaLogHandlerMonolog3` — Monolog 3 (SS5/6)
  - `Handlers\TalariaLogHandlerMonologLegacy` — Monolog 1/2 (SS4)
  - Files live in `silverstripe/handlers/` — **not** Composer PSR-4; `LogHandlerFactory` `require_once`s one file only
  - Never ship a generic `TalariaLogHandler` class (Injector/autoload will load it and fatal on the wrong Monolog)
  - Injector service id is `talariaLogHandler` (neutral) + factory; `_manifest_exclude` in `handlers/`
  - Shared logic in `LogHandlerSupport`
- Config via YAML / env (`TALARIA_API_KEY`, optional `TALARIA_URL`, …). A missing or invalid key gives a disabled no-op client from `InjectorFactory`; it never throws
- Capture Member id and request context when available
- Do not put Silverstripe imports in `src/`
- Same batch queue semantics as core SDK (`/v1/events`, `/v1/spans`, `/v1/analytics`)
- Filterable auto-tags: `platform=php`, `runtime=silverstripe`, `runtime_version`, plus per-request `ajax` / `ss_env` / `host` via `RequestTags` processor (not `setTags` on the singleton)
- Core also emits `cli` and `php.version` via `RuntimeContext`
- Optional YAML `service` / `tags` merge into init tags
- APM (off by default): `HTTPMiddleware` SERVER span, `TracingMySQLDatabase` CLIENT/db spans, Injector Guzzle factory, QueuedJob producer/consumer when the module exists. Enable with `enableTracing` / `TALARIA_ENABLE_TRACING`
- Product analytics (off by default): `enableAnalytics` / `TALARIA_ENABLE_ANALYTICS` gates PHP `Talaria::analytics()` and the public-page browser inject. CMS admin is never opted in. Middleware binds the current Member as `userId` when analytics is on.
- Do not wrap Talaria ingest Guzzle clients; `GuzzleClientFactory` is for **app** clients only
- No Redis wrapper — Silverstripe has no core Redis usage pattern

## Browser JS

- Load **`@newtalaria/browser` from npm** via jsDelivr ESM (`cdn.jsdelivr.net/npm/@newtalaria/browser@{version}/+esm`)
- Do **not** vendor or build from a local `sdks/javascript/browser` checkout for runtime
- Pin version with `Talaria\SilverStripe\Config.browserSdkVersion` (default **0.6.0**)
- Inject via `RequirementsHelper` + `LeftAndMainExtension` / `FrontendExtension`
- Config JSON is `window.__TALARIA_CONFIG__`; module script calls `Talaria.init` and assigns `window.Talaria`
- `browser_api_key` / `TALARIA_BROWSER_API_KEY` for browser inject. It must be a publishable `tal_pk_` key; the server `tal_sk_` key is never injected. Without a valid `tal_pk_` key the browser inject renders nothing. Replay sample rates default to `0`
- Init tags: `platform=web`, `runtime=silverstripe-cms|silverstripe-frontend`, `runtime_version`, `ss_env`, `host`, optional `service` / `browserTags`, CMS `ss.section`
- Init `userId` from current Member when logged in
- CMS sets `inlineStylesheet: true` automatically; frontend defaults false; YAML `browserInlineStylesheet` overrides both
- CMS promotes failed HTTP **400–599** to events; frontend **500–599**; YAML `browserFailedRequestStatusCodes` / `browserCaptureFailedRequests` override
- Dashboard filters by tags + first-class fields — not `extra`. Keep tags low-cardinality (max ~20/event)