Configuration - PrestaShop

Where the configuration lives

Everything is on one screen: Modules → Module Manager → DockRay → Configure. At the top are two status pills - whether the credentials are complete and how the last connection test ended, with its timestamp.

A shop copied to a staging server

This is the classic PrestaShop trap: a shop copied to staging carries its database, and with it the project credentials - and both environments start reporting into one project. Override the key with a constant in app/config/parameters.php, which is not part of a database dump:

define('_DOCKRAY_PRIVATE_KEY_', 'staging-project-private-key');

The constant wins over whatever is stored in the configuration table.

Configuration source

The Configuration source switch decides how constants and the form interact: Auto (the default - a defined constant wins for its own field, everything else comes from the form), Constants only and This form only. The last option helps when a shared parameters file bakes in a default project and one shop in a multistore should report into its own.

The remaining constants work the same way: _DOCKRAY_TOKEN_, _DOCKRAY_URL_, _DOCKRAY_ENVIRONMENT_, _DOCKRAY_RELEASE_, _DOCKRAY_TRACES_SAMPLE_RATE_, _DOCKRAY_SEND_CUSTOMER_, _DOCKRAY_SEND_DEFAULT_PII_, _DOCKRAY_JS_ERRORS_ and _DOCKRAY_JS_SAMPLE_RATE_.

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.

Customer data and privacy

Two switches, both off by default and deliberately separate. Attach the logged-in customer sends the id and the e-mail address - it helps reconstruct an order's path, but it brings personal data into monitoring. Send IP address and user agent is a separate decision, because it also covers guests. Turn them on deliberately and write that into your privacy policy.

JavaScript errors on the storefront

Off by default. Once enabled, the module loads a small collector on the storefront that reports window.onerror and unhandled promise rejections to the shop, not to the panel: authenticating from the browser would mean publishing the project private key in page source. The shop forwards each error with its own key.

The receiver is a module front controller (index.php?fc=module&module=dockray&controller=browsererror), guarded by the PrestaShop token, a 16 KB body limit and 20 reports per IP address per minute. It answers 202 whether or not the report was accepted. The collector caps itself too: one report per distinct error per page view, at most ten per page view, with ResizeObserver loop and cross-origin Script error. filtered out.

From your own storefront code:

DockRay.captureException(error);
DockRay.captureMessage('Checkout step skipped');

Reporting by hand from PHP

use Dock\Ray\PrestaShop\Reporter;

try {
    $this->syncStock();
} catch (\Throwable $exception) {
    Reporter::report($exception);

    throw $exception;
}

Reporter::report() never throws, so you can call it inside the error handling you are reporting from.

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 module queues events during the request and flushes them from a shutdown handler, once PHP-FPM has closed the connection to the browser. A slow panel costs the shopper nothing.