1. Home
  2. Language Guides
  3. PHP
  4. Crash Reporting
  5. SilverStripe

SilverStripe

The Raygun for Silverstripe module allows you to easily set up Crash Reporting on Silverstripe CMS platform. This is a simple module that binds Raygun to the error & exception handler of SilverStripe.

  • PHP ^8.1
  • Raygun4PHP ^2
  • Silverstripe Framework ^5

Support for Silverstripe 3 can be found in version ^1. Support for Silverstripe 4 can be found in versions ^2 and ^3.

Run the following command within your project -

composer require silverstripe/raygun

Add the following to your .env file:

SS_RAYGUN_APP_KEY="paste_your_api_key_here"

If you want to track JavaScript errors in CMS, you can activate LeftAndMainExtension in your project YAML configs:

---
Name: raygunning-left-and-main
---
SilverStripe\Admin\LeftAndMain:
  extensions:
    - SilverStripe\Raygun\LeftAndMainExtension

You can define the error reporting level in your YAML config:

SilverStripe\Core\Injector\Injector:
  SilverStripe\Raygun\RaygunHandler:
    constructor:
      client: '%$Raygun4php\RaygunClient'
      level: 'error'

By default, no user data will be sent to Raygun at all. You can choose to track logged-in members by setting some yml configuration:

---
After: raygun
---
Raygun4php\RaygunClient:
  disable_user_tracking: false

SilverStripe\Raygun\RaygunHandler:
  user_main_id_field: 'ID' #default: 'Email'. This is the "Identifier" in the Raygun app.
  user_include_firstname: true #default: false
  user_include_fullname: true #default: false
  user_include_email: true #default: false

You may have more than one Raygun integration, each of which could use custom API keys, different from the default one (set by SS_RAYGUN_APP_KEY). To do so you'll need to configure each one of them separately. Here are some examples:

# Here's an example of the LeftAndMainExtension using a custom raygun
# API Key, set through a custom environment variable (SS_CUSTOM_RAYGUN_APP_KEY)

---
Name: custom-raygun-leftnmain-extension
---
SilverStripe\Core\Injector\Injector:
  SilverStripe\Raygun\LeftAndMainExtension.custom:
    class: SilverStripe\Raygun\LeftAndMainExtension
    properties:
      # You'll have to set the SS_CUSTOM_RAYGUN_APP_KEY environment var
      CustomRaygunAppKey: '`SS_CUSTOM_RAYGUN_APP_KEY`'

---
Name: raygunning-left-and-main
After: custom-raygun-leftnmain-extension
---
SilverStripe\Admin\LeftAndMain:
  extensions:
    - SilverStripe\Raygun\LeftAndMainExtension.custom

# Here's an example of a custom Raygun handler for Monolog
# which uses API Key provided by a custom RaygunClientFactory

---
Name: custom-monolog-raygun-handler
---
SilverStripe\Core\Injector\Injector:
  SilverStripe\Raygun\RaygunClientFactory.custom:
    class: SilverStripe\Raygun\RaygunClientFactory
    properties:
      # You'll have to set the SS_CUSTOM_RAYGUN_APP_KEY environment var
      CustomRaygunAppKey: '`SS_CUSTOM_RAYGUN_APP_KEY`'

  Raygun4php\RaygunClient.custom:
    factory: '%$SilverStripe\Raygun\RaygunClientFactory.custom'

  SilverStripe\Raygun\RaygunHandler.custom:
    class: SilverStripe\Raygun\RaygunHandler
    constructor:
      client: '%$Raygun4php\RaygunClient.custom'
      level: 'debug'

  Psr\Log\LoggerInterface:
    calls:
      - [ pushHandler, [ '%$SilverStripe\Raygun\RaygunHandler.custom'] ]

The RaygunHandler is enabled by default when the SS_RAYGUN_APP_KEY environment variable is set. There may be some situations where you need that variable to be set but you don't want the handler enabled by default (e.g. you may not want the handler enabled in dev or test environments except when triggering some test exception via a BuildTask).

---
Only:
  environment: 'dev'
---
SilverStripe\Raygun\RaygunHandler:
  enabled: false

Then in your BuildTask you can enable that handler as required.

use SilverStripe\Control\Director;
use SilverStripe\Control\HTTPRequest;
use SilverStripe\Core\Config\Config;
use SilverStripe\Dev\BuildTask;
use SilverStripe\Raygun\RaygunHandler;

class TriggerTestExtensionTask extends BuildTask
{
    protected $title = 'Trigger Test Exception';

    protected $description = 'Throws an exception. Useful for checking raygun integration is working as expected.';

    /**
     * Throw a test exception that is directed through raygun.
     *
     * @param HTTPRequest $request
     */
    public function run($request)
    {
        $env = Director::get_environment_type();
        Config::modify()->set(RaygunHandler::class, 'enabled', true);
        throw new \Exception("Test exception thrown from '$env' environment.");
    }
}

If you need to forward outgoing requests through a proxy (such as for sites hosted in CWP), you can set the proxy host and optional port via yaml config:

SilverStripe\Core\Injector\Injector:
  Raygun4php\RaygunClient:
    constructor:
      proxyHost: '`SS_OUTBOUND_PROXY`'
      proxyPort: '`SS_OUTBOUND_PROXY_PORT`'

Raygun will send the following data:

  • $_POST
  • $_SERVER
  • $_GET (included in URL also)

By default we filter out some sensitive Silverstripe details which appear in the $_SERVER variable. These include:

  • SS_DATABASE_USERNAME
  • SS_DEFAULT_ADMIN_USERNAME
  • SS_RAYGUN_APP_KEY
  • Cookie information (through Cookie and HTTP_COOKIE)
  • Basic auth information (through PHP_AUTH_PW)
  • HTTP authorisation information (through Authorization and HTTP_AUTHORIZATION)
  • Anything containing PASSWORD, KEY, SECRET or TOKEN (case insensitive)

You will likely want to filter out other sensitive data such as credit cards, passwords etc. You can do this in your mysite/_config.php file. These rules are applied to $_SERVER, $_POST and $_GET data. All key comparisons are case insensitive.

Example implementation in mysite/_config.php:

<?php

$client = Injector::inst()->get(Raygun4php\RaygunClient::class);
$client->setFilterParams(array_merge($client->getFilterParams(), [
    'php_auth_pw' => true,
    '/password/i' => true,
	'Email' => function($key, $val) {
        return substr($val, 0, 5) . '...';
    }
]));

note: This feature is built by a separate third party provider within the silverstripe-raygun-tags repository.

This is a purpose-built extension that adds several useful tags to error messages that are published to Raygun via the silverstripe/silverstripe-raygun extension.

The following tags are added:

  • env:live (or env:dev / env:test)
  • php:8.2.x
  • host:example.com
  • framework:5.0.x
  • ajax:false (true if this is an AJAX request)
  • cli:false (true if being run via the CLI)

The logging level is set to WARNING and above (debug & info is ignored, see configuration).

  • Silverstripe ^5.0
  • A Raygun application and API key (see configuration)

Run the following command in your project-

composer require springtimesoft/silverstripe-raygun-tags

Add the SS_RAYGUN_APP_KEY="xxxxxxxxx" environment variable to your .env file.

Please refer to the original silverstripe/silverstripe-raygun README for further information on customising the Raygun extension.

To change the logging level of your application you can overrule the module's defaults by adding a custom yaml file like:

---
Name: custom-raygun
After:
  - '#raygun-log-level'
Only:
  envorconstant: 'SS_RAYGUN_APP_KEY'
---

# Prevent Raygun from logging debug/info messages, which aren't considered errors
SilverStripe\Core\Injector\Injector:
  SilverStripe\Raygun\RaygunHandler:
    constructor:
      level: 100 # Monolog\Level::Debug

More information about accepted filtering formats is available in the raygun4php documentation.

This provider is built by a third party provider and it is open source. The repository is available at silverstripe-raygun repository.

On this page: