Configuration - WordPress

Where the configuration lives

Every plugin setting sits on one screen: Settings → DockRay. At the top are two status pills - whether a full set of credentials is present, and how the last connection test ended, with its timestamp. The status does not query DockRay each time the screen opens, so opening the settings generates no traffic to the panel.

Configuration source

The plugin can take values from the settings screen or from PHP constants in wp-config.php. The Configuration source switch decides which wins:

A field overridden by a constant is shown with the value actually in effect and a note explaining why. A locked field still submits that value on save, so saving any other change cannot blank a token that a constant supplied.

wp-config.php constants

Environments

Every environment should report under an unambiguous name - production, staging, preview. The name is a column in the panel and a filter on the error list, so without it a production outage looks exactly like an error someone triggered in a test. Leave your local environment without credentials: with no token and no key the integration loads and stays silent, so you do not need a separate switch to turn it off.

What is worth reporting

Send DockRay the failures that need someone to act. By default the plugin follows the level from error_reporting(), and DOCK_RAY_ERROR_TYPES narrows it - to fatals and warnings only, for instance, leaving out the notices and deprecations that dominate a typical install with many plugins.

• Do not report validation that is handled as a normal response to the user.
• Filter out the 404s produced by scanners and non-existent URLs.
• Leave send_default_pii off unless you actually need the logged-in user's identity on the event.

Request timing and browser errors

Both are off by default and enabled separately. Request timing starts working once the transaction sample rate is above zero. JavaScript errors go to WordPress first, not to the panel: a browser cannot authenticate against DockRay, because that would mean putting the private key in page source. The WordPress-side receiver checks a nonce, drops bodies over 16 KB, allows 20 reports per IP address per minute and answers 202 whether or not the report was accepted.

Reporting from your own code

A theme or your own plugin can report an exception itself. A call wrapped in dock_ray_safe() does nothing when DockRay is not active, so the same code is safe on an environment without credentials.

try {
    $order->finalize();
} catch ( Throwable $e ) {
    if ( function_exists( 'dock_ray_safe' ) ) {
        dock_ray_safe( fn( $hub ) => $hub->captureException( $e ) );
    }

    throw $e;
}

Protecting the private key

The private key is a project secret, not an identifier. Keep it in environment variables, in a secrets manager or in the server configuration - never in the repository, in logs, in a screenshot or in code sent to the browser. One project can hold many keys, so production and staging should each get their own: either can be revoked on its own without interrupting the others. A suspicion that a key leaked is reason enough to revoke it and generate a new one.

When events go out

After the response. The plugin queues events during the request and sends them from a shutdown handler, once PHP-FPM has already closed the connection to the browser. Requests go through the WordPress HTTP API with TLS verification and without following redirects, so a self-hosted DockRay server has to be reachable over HTTPS.