=== DockTHOR ===
Contributors: jacycha
Tags: error tracking, monitoring, debugging, logging, performance
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.2
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Reports PHP errors, uncaught exceptions and request timings from WordPress to the DockTHOR monitoring panel.

== Description ==

DockTHOR sends PHP errors and uncaught exceptions from your WordPress site to a
DockTHOR project, together with the stack trace, the environment and — when you
allow it — the logged-in user. It can also measure how long requests take.

Features:

* Automatic reporting of PHP errors and uncaught exceptions
* Optional request timing, including admin-ajax actions and WP-CLI commands
* Optional user context
* Error filtering by PHP error type
* A settings screen at **Settings → DockTHOR**, with a live connection
  status and a one-click test event — no wp-config.php editing required
* Configuration can also come from `wp-config.php` constants, per field or
  entirely, for teams that prefer to keep the private key out of the database
* Available in English, Polish and German

Fill in the token and the private key on **Settings → DockTHOR** and you are
done. If you would rather keep the private key out of the database — a
database dump travels between environments more often than a config file
does — define it as a `wp-config.php` constant instead; the settings screen
shows exactly which fields are currently coming from a constant, and a
**Configuration source** switch lets you pin the plugin to constants only,
to the database only, or let a defined constant win per field (the default,
and how the plugin behaved before this screen existed).

== Installation ==

1. Upload the plugin to `/wp-content/plugins/dockthor`, or install it from the
   plugins screen.
2. Activate it through the **Plugins** menu — its row gets a **Settings**
   link straight to the next step, so there is nothing to hunt for.
3. Open **Settings → DockTHOR**, paste in your project token and private key,
   and save.
4. Click **Send a test event** to confirm it reached the panel.

Both values come from the project screen in the DockTHOR panel. The token is
public and appears in the ingest URL; the private key is a secret shown once,
when it is generated.

Prefer `wp-config.php` instead? Add the constants below and the settings
screen will show the fields as coming from wp-config.php automatically —
nothing else to configure.

`define( 'DOCK_THOR_TOKEN', 'YOUR_PROJECT_TOKEN' );`
`define( 'DOCK_THOR_PRIVATE_KEY', 'YOUR_PRIVATE_KEY' );`

== Configuration ==

Every setting below has a field on **Settings → DockTHOR**. Each one can also
be set as a `wp-config.php` constant — go there above the `/* That's all */`
line — and the **Configuration source** switch on the screen decides whether
a constant is allowed to win, is required, or is ignored in favour of the
database.

**Server URL** — which DockTHOR instance receives the events. Defaults to the
hosted one.

`define( 'DOCK_THOR_URL', 'https://thor.dock.codes' );`

**Error types** — which PHP errors become events. Defaults to everything except
deprecations and notices. This one is constant-only; there is no equivalent
field on the settings screen, since it is a bitmask rather than a value worth
typing into a text box.

`define( 'DOCK_THOR_ERROR_TYPES', E_ALL & ~E_DEPRECATED & ~E_NOTICE );`

**Personal data** — attaches the user id, e-mail, IP address and user agent.
Off by default.

`define( 'DOCK_THOR_SEND_DEFAULT_PII', true );`

**Release** — the version of the site. Without it the active theme version is
used.

`define( 'DOCK_THOR_VERSION', 'v1.4.0' );`

**Environment** — defaults to `WP_ENVIRONMENT_TYPE`.

`define( 'DOCK_THOR_ENV', 'production' );`

**Request timing** — the share of requests that are measured, from 0 to 1.
Zero, the default, disables it.

`define( 'DOCK_THOR_TRACES_SAMPLE_RATE', 0.2 );`

== Filters ==

`dock_thor_token`, `dock_thor_private_key`, `dock_thor_url` — override the
credentials, for instance to read them from a secrets manager.

`dock_thor_user_context` — change the user data attached to events.

`add_filter( 'dock_thor_user_context', fn( array $user ) => array_merge( $user, [ 'plan' => 'pro' ] ) );`

`dock_thor_scope` — set tags and extra context before events are sent.

`add_filter( 'dock_thor_scope', function ( $scope ) { $scope->setTag( 'tier', 'gold' ); return $scope; } );`

`dock_thor_options` — adjust SDK options after the client is built.

`dock_thor_client_builder` — an action that receives the client builder before
the client is created.

== Reporting your own exceptions ==

`if ( function_exists( 'dock_thor_safe' ) ) {`
`    dock_thor_safe( fn( $hub ) => $hub->captureException( $exception ) );`
`}`

The callback runs only when the plugin is configured, so the calling code does
not have to check.

== Frequently Asked Questions ==

= Does the plugin have a settings screen? =

Yes — **Settings → DockTHOR**. It shows a live configuration status, the
result of the last test event, and lets you edit every setting without
touching `wp-config.php`. Anything already defined as a constant keeps
working; the screen shows exactly which fields that applies to.

= Will it slow down my site? =

Request timing is off by default. When it is on, the transaction is sent after
the response has been handed to the browser, so the visitor does not wait for
it.

= What happens if the site cannot reach DockTHOR? =

Nothing visible. Failures to start or to send are logged to the PHP error log
and the request continues.

= Which languages does it speak? =

English, Polish and German.

== Changelog ==

= 1.1.0 =
* Dependency update
* Appearance update
* Added backend configuration option

== Upgrade Notice ==

= 1.0.0 =
* Initial release.