Silverstripe upgrade

talaria/silverstripe 2.0.1 requires talaria/talaria ^2.0.0. Treat them as one unit:

talaria/silverstripe
        │
        └── requires → talaria/talaria

When a new module release requires a newer core, upgrade both in the same Composer command. The shared rules for the lock file and for composer install on deploy are in PHP upgrade. This page is the Silverstripe sequence and the config that has to change with it.

The module supports Silverstripe 4.13, 5, and 6 on PHP 8.1 or newer. Do not call Talaria::init() in application code. Injector builds the client.

Upgrade

Run this from the application root, the project that owns composer.json and composer.lock. Not from inside vendor/.

composer show talaria/silverstripe
composer show talaria/talaria
composer update talaria/silverstripe talaria/talaria -W --dry-run
composer update talaria/silverstripe talaria/talaria -W

-W (--with-all-dependencies) lets Composer update dependencies required by the packages you are upgrading. That is what a failed solve is asking for when the new module needs a newer talaria/talaria, or a newer library the core now requires, and the lock file still has the old one.

composer update will not cross from 1.x into 2.0 while composer.json says ^1.2 (>=1.2.0 <2.0.0). Change the constraint and update the lock together:

composer require talaria/silverstripe:^2.0 talaria/talaria:^2.0 -W

Inside 2.0, the composer update … -W command is the one that moves you to 2.0.1.

Read git diff composer.lock. -W can move other packages. silverstripe/framework should stay on the major you already run. The Talaria constraint allows 4.13, 5, and 6, so an unbounded framework requirement can change the CMS in the same solve. Pin silverstripe/framework to your major, then run the Talaria update again.

On Silverstripe 4, leave monolog/monolog on 1.x or 2.x and leave psr/log able to resolve 1.x. A root constraint of psr/log: ^3 or monolog/monolog: ^3 does not install against Silverstripe 4. The module loads one Monolog handler: TalariaLogHandlerMonolog3 on Monolog 3 (Silverstripe 5 and 6), TalariaLogHandlerMonologLegacy on Monolog 1 and 2 (Silverstripe 4). Those classes are excluded from Composer's classmap and are not both loaded. Do not add your own TalariaLogHandler class, and do not point an Injector service at a concrete handler class name. The service id is talariaLogHandler.

silverstripe/vendor-plugin has to stay allowed (composer config allow-plugins.silverstripe/vendor-plugin true). If that plugin is blocked, the module's _config YAML is not applied and the logger handler never registers.

Flush and test

vendor/bin/sake dev/build flush=all

dev/build builds the database. flush=all clears the manifest cache, so the new module YAML (Injector services, browser version, removed keys) replaces the cached copy. Run that command as the same system user that serves the site. A flush owned by another user leaves the web process on the old manifest. If the site still behaves as the previous module, delete the silverstripe-cache directory the web user reads and flush again.

Then use the site. Log an error through the framework logger, or throw, and open a public HTML page and a CMS page. Confirm with MCP search_errors and environment: development when the key is a development key. A page with no browser script usually means enableBrowserFrontend is false, the response is not HTML, or TALARIA_BROWSER_API_KEY is set to something that is not a tal_live_ key. A non-empty browser key in the wrong shape disables browser inject.

Restart PHP-FPM after the code is deployed so OPcache loads the new files. A rejected key stays cached for about 24 hours until that restart.

The module reads keys through Silverstripe's environment, including .env. A variable exported only in your shell is visible to that shell and not to PHP-FPM. Set TALARIA_API_KEY where the web SAPI loads it. If the key or DSN is missing, Injector installs a disabled client and error_log records that. Install and flush still complete.

Commit the lock file

git add composer.json composer.lock
git commit -m "Upgrade Talaria dependencies"

Commit both files. composer.lock is the exact set you just flushed and clicked through. UAT and production should install that set:

composer install --no-dev --optimize-autoloader

Do not run composer update on deploy. composer install reproduces the lock file.

1.x to 2.0

2.0.0 removes the environment setting and TALARIA_ENVIRONMENT. Browser init no longer sends environment. The API key decides the environment.

Delete this from your YAML if it is still there:

Talaria\SilverStripe\Config:
  environment: '`TALARIA_ENVIRONMENT`'

Delete TALARIA_ENVIRONMENT from .env. Leaving the key does not select an environment. Events land on the key's environment. Use a development key on a laptop and a production key on the live site.

2.0.0 requires talaria/talaria ^2.0.0 and pins @newtalaria/browser 0.5.0. 2.0.1 moves that pin to 0.5.3. An application YAML value for browserSdkVersion replaces the module default. If you pinned an older browser SDK (for example 0.4.1), the PHP upgrade does not change the script until you remove that line or set 0.5.3. The script URL is https://cdn.jsdelivr.net/npm/@newtalaria/browser@{version}/+esm, so the version in YAML is the version the browser loads.

1.1 to 1.2.0

1.2.0 requires talaria/talaria ^1.2.0. Tracing, analytics, heatmaps, and replay follow the project config document, not YAML.

These stop controlling the client once core is 1.2.0 or newer, even if your YAML or .env still sets them:

• enableTracing and TALARIA_ENABLE_TRACING
• tracesSampleRate and TALARIA_TRACES_SAMPLE_RATE
• enableAnalytics and TALARIA_ENABLE_ANALYTICS
• sampleRate

Turn the features on in Project settings. Public pages can send browser analytics when that document allows it. The CMS is not opted into browser analytics. Until the first document is cached, PHP sends errors only.

1.1.0 was the release that added enableAnalytics (default off) and Member userId for PHP analytics. After 1.2.0 that YAML flag is not the switch.

Patch releases

From 1.2.1, a blank TALARIA_DSN sends to Talaria Cloud. Set dsn in YAML, or TALARIA_DSN, when the API is somewhere else. If PHP talks to a host the browser cannot reach (a Docker-internal URL, or HTTP behind an HTTPS site), set TALARIA_BROWSER_DSN for the injected script only. PHP keeps its own DSN.

TALARIA_BROWSER_API_KEY is optional. When it is a tal_live_ key, CMS and public pages report with that key and PHP keeps TALARIA_API_KEY. When it is unset, the script uses the PHP key. When it is non-empty and not a tal_live_ key, the script is not injected.

Query spans from 1.2.3 roll identical SQL into one span under the same parent. A waterfall that used to show one bar per query now shows a count. Queries of 200ms or more, and failed queries, stay separate. A transaction stores at most 200 spans.

MySQL wrapping is an Injector replacement of MySQLDatabase that runs after the #databaseconnectors fragment. If your own YAML replaces MySQLDatabase after #talaria-tracing, that replacement is the class that runs, and query spans are not recorded. Keep Talaria's replacement, or subclass Talaria\SilverStripe\TracingMySQLDatabase.

Queued-job spans load only when symbiote/silverstripe-queuedjobs is installed. The job service class is not in the Composer classmap until that module is present.

Related

• PHP upgrade
• Silverstripe SDK
• Instrumentation and tracing
• Project configuration