# DockTHOR
- Contributors: jacycha
- Tags: error tracking, monitoring, debugging, logging
- Requires at least: 5.6
- Tested up to: 6.9
- Requires PHP: 7.2
- Stable tag: 1.0.0
- License: GPLv2 or later
- License URI: http://www.gnu.org/licenses/gpl-2.0.html

DockTHOR is a lightweight WordPress integration for sending PHP errors and exceptions to the THOR monitoring platform.

## Description

DockTHOR integrates WordPress with the THOR monitoring platform and automatically reports PHP errors and uncaught exceptions.

The plugin is designed to work silently in the background and has no admin interface. After installation you only need to configure your THOR project credentials.

### Features:

* Automatic reporting of PHP errors and uncaught exceptions
* Support for custom error filtering
* Optional user context information
* Customizable configuration via WordPress constants and filters
* Minimal performance overhead

This plugin is intended for developers and teams who want to monitor errors occurring in WordPress installations.

# Installation

1. Upload the plugin files to the `/wp-content/plugins/dockthor` directory, or install the plugin through the WordPress plugins screen.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Configure your THOR credentials in `wp-config.php`.

Example configuration:
```php
define( 'DOCK_THOR_TOKEN', 'YOUR_THOR_TOKEN' );
define( 'DOCK_THOR_PRIVATE_KEY', 'YOUR_PRIVATE_KEY' );
```
Once configured, the plugin will automatically begin reporting PHP errors.

# Configuration

Add the following constants to your `wp-config.php` file.
 
## DockTHOR Token
```php
define( 'DOCK_THOR_TOKEN', 'YOUR_THOR_TOKEN' );
```
## Private Key
```php
define( 'DOCK_THOR_PRIVATE_KEY', 'YOUR_PRIVATE_KEY' );
```
## Error Types (optional)
```php
define( 'DOCK_THOR_ERROR_TYPES', E_ALL & ~E_DEPRECATED & ~E_NOTICE & ~E_USER_DEPRECATED );
```
Define which PHP errors should be captured.
## Send Default PII (optional)

If enabled, additional context such as the logged-in user and IP address will be attached to the event.
```php
define( 'DOCK_THOR_SEND_DEFAULT_PII', true );
```

## Site Version (optional)

Define the version of your website. This can help track which version of the site generated an error.
```php
define( 'DOCK_THOR_VERSION', 'v1.0.0' );
```

## Environment (optional)

Define the current environment.
```php
define( 'DOCK_THOR_ENV', 'production' );
```

# Filters

DockTHOR provides several filters that allow developers to customize behavior.

## dock_thor_user_context

Allows extending the user context sent to THOR.

Example:
```php
add_filter( 'dock_thor_user_context', function ( array $user ) {
    return array_merge( $user, ['custom_meta' => 'value'] );
});
```

Note: These values may be exposed publicly when used in JavaScript trackers.

## dock_thor_token

Allows overriding the THOR token.

Example:
```php
add_filter( 'dock_thor_token', function ( $token ) {
    return 'xxxxxxxxxxxxxxxxxxxx';
});
```
Using the `DOCK_THOR_TOKEN` constant is recommended instead.

## dock_thor_scope

Allows modifying the THOR scope before events are sent.

Example:
```php
add_filter( 'dock_thor_scope', function ( \Dock\Thor\State\Scope $scope ) {
    $scope->setTag('custom-tag', 'value');
    return $scope;
});
```
## dock_thor_options

Allows customizing THOR SDK options.

Example:
```php
add_filter( 'dock_thor_options', function ( \Dock\Thor\Options $options ) {
    $options->setSampleRate(0.9);
    return $options;
});
```

# Advanced Usage

## High volume of notices

Some plugins generate large amounts of PHP notices. You can filter them out:
```php
define( 'DOCK_THOR_ERROR_TYPES', E_ALL & ~E_NOTICE );
```

## Capturing handled exceptions

If you want to report handled exceptions:
```php
try {
    myMethodThatCanThrowAnException();
} catch ( \Exception $e ) {
    if ( function_exists( 'dock_thor_safe' ) ) {
        dock_thor_safe( function ( \Dock\Thor\State\HubInterface $client ) use ( $e ) {
            $client->captureException( $e );
        });
    }
    wp_die( 'An error occurred.' );
}
```


# Frequently Asked Questions

= Does this plugin have an admin panel? =

No. DockTHOR works automatically after configuration in `wp-config.php`.

= Will this slow down my site? =

The plugin is designed to have minimal performance impact. Error events are sent asynchronously when possible.

= Can I disable certain errors? =

Yes. You can configure the error types captured using the `DOCK_THOR_ERROR_TYPES` constant.

## Changelog

### 1.0.0
- Initial release.

# License

The DockTHOR plugin is licensed under the GNU General Public License v2.0 or later (GPLv2+), as required by WordPress. This means the plugin’s source code is open and can be modified, copied, and redistributed under the terms of the GPL.