A (unofficial) WordPress plugin to report PHP and JavaScript errors to Sentry., (*1)
What?
This plugin can report PHP errors (optionally) and JavaScript errors (optionally) to Sentry and integrates with its release tracking., (*2)
It will auto detect authenticated users and add context where possible. All context/tags can be adjusted using filters mentioned below., (*3)
Usage
- Install this plugin by cloning or copying this repository to your
wp-contents/plugins folder
- Configure your DSN as explained below
- Activate the plugin through the WordPress admin interface
Note: this plugin does not do anything by default and has no admin interface. A DSN must be configured first., (*4)
Configuration
(Optionally) track PHP errors by adding this snippet to your wp-config.php and replace DSN with your actual DSN that you find in Sentry:, (*5)
define( 'WP_SENTRY_DSN', 'DSN' );
Note: Do not set this constant to disable the PHP tracker., (*6)
(Optionally) set the error types the PHP tracker will track:, (*7)
define( 'WP_SENTRY_ERROR_TYPES', E_ALL & ~E_DEPRECATED & ~E_NOTICE & ~E_USER_DEPRECATED );
(Optionally) track JavaScript errors by adding this snippet to your wp-config.php and replace PUBLIC_DSN with your actual public DSN that you find in Sentry (never use your private DSN):, (*8)
define( 'WP_SENTRY_PUBLIC_DSN', 'PUBLIC_DSN' );
Note: Do not set this constant to disable the JavaScript tracker., (*9)
(Optionally) define a version of your site; by default the theme version will be used. This is used for tracking at which version of your site the error occurred. When combined with release tracking this is a very powerful feature., (*10)
define( 'WP_SENTRY_VERSION', 'v2.1.3' );
(Optionally) define an environment of your site. Defaults to unspecified., (*11)
define( 'WP_SENTRY_ENV', 'production' );
Filters
This plugin provides the following filters to plugin/theme developers., (*12)
Please note that some filters are fired when the Sentry trackers are initialized so they won't fire if you define them in you theme or in a plugin that loads after WP Sentry does., (*13)
Common to PHP & JavaScript trackers
wp_sentry_user_context (array)
You can use this filter to extend the Sentry user context for both PHP and JS trackers., (*14)
WARNING: These values are exposed to the public in the JS tracker, so make sure you do not expose anything private!, (*15)
Example usage:, (*16)
/**
* Customize sentry user context.
*
* @param array $user The current sentry user context.
*
* @return array
*/
function customize_sentry_user_context( array $user ) {
return array_merge( $user, array(
'a-custom-user-meta-key' => 'custom value',
));
}
add_filter( 'wp_sentry_user_context', 'customize_sentry_user_context' );
Note: This filter fires on the WordPress set_current_user action., (*17)
Specific to PHP tracker:
wp_sentry_dsn (string)
You can use this filter to override the Sentry DSN used for the PHP tracker., (*18)
Example usage:, (*19)
/**
* Customize sentry dsn.
*
* @param string $dsn The current sentry public dsn.
*
* @return string
*/
function customize_sentry_dsn( $dsn ) {
return 'https://<key>:<secret>@sentry.io/<project>';
}
add_filter( 'wp_sentry_dsn', 'customize_sentry_dsn' );
Note: This filter fires on when WP Sentry initializes and after the WP after_setup_theme., (*20)
wp_sentry_options (array)
You can use this filter to customize the Sentry options used to initialize the PHP tracker., (*21)
Example usage:, (*22)
/**
* Customize sentry options.
*
* @param array $options The current sentry options.
*
* @return array
*/
function customize_sentry_options( array $options ) {
return array_merge( $options, array(
'tags' => array(
'my-custom-tag' => 'custom value',
),
));
}
add_filter( 'wp_sentry_options', 'customize_sentry_options' );
Note: This filter fires on when WP Sentry initializes and after the WP after_setup_theme., (*23)
wp_sentry_send_data (array|bool)
Provide a function which will be called before Sentry PHP tracker sends any data, allowing you both to mutate that data, as well as prevent it from being sent to the server., (*24)
Example usage:, (*25)
/**
* Customize sentry send data.
*
* @param array $data The sentry send data.
*
* @return array|bool Return the data array or false to cancel the send operation.
*/
function filter_sentry_send_data( array $data ) {
$data['tags']['my_custom_key'] = 'my_custom_value';
return $data;
}
add_filter( 'wp_sentry_send_data', 'filter_sentry_send_data' );
Note: This filter fires whenever the Sentry SDK is sending data to the Sentry server., (*26)
Specific to JS tracker
wp_sentry_public_dsn (string)
You can use this filter to override the Sentry DSN used for the JS tracker., (*27)
WARNING: This value is exposed to the public, so make sure you do not use your private DSN!, (*28)
Example usage:, (*29)
/**
* Customize public sentry dsn.
*
* @param string $dsn The current sentry public dsn.
*
* @return string
*/
function customize_public_sentry_dsn( $dsn ) {
return 'https://<key>@sentry.io/<project>';
}
add_filter( 'wp_sentry_public_dsn', 'customize_public_sentry_dsn' );
wp_sentry_public_options (array)
You can use this filter to customize/override the sentry options used to initialize the JS tracker., (*30)
WARNING: These values are exposed to the public, so make sure you do not expose anything private !, (*31)
Example usage:, (*32)
/**
* Customize public sentry options.
*
* @param array $options The current sentry public options.
*
* @return array
*/
function customize_public_sentry_options( array $options ) {
return array_merge( $options, array(
'tags' => array(
'custom-tag' => 'custom value',
),
));
}
add_filter( 'wp_sentry_public_options', 'customize_sentry_public_options' );
Catching plugin errors
Since this plugin is called wp-sentry-integration it loads a bit late which could miss errors or notices occuring in plugins that load before it., (*33)
You can remedy this by loading WordPress Sentry as a must-use plugin by creating the file wp-content/mu-plugins/wp-sentry-integration.php (if the mu-plugins directory does not exists you must create that too)., (*34)
<?php
/**
* Plugin Name: WordPress Sentry
* Plugin URI: https://github.com/stayallive/wp-sentry
* Description: A (unofficial) WordPress plugin to report PHP and JavaScript errors to Sentry.
* Version: must-use-proxy
* Author: Alex Bouma
* Author URI: https://alex.bouma.me
* License: MIT
*/
$wp_sentry = __DIR__ . '/../plugins/wp-sentry-integration/wp-sentry.php';
if ( ! file_exists( $wp_sentry ) ) {
return;
}
require $wp_sentry;
define( 'WP_SENTRY_MU_LOADED', true );
Now wp-sentry-integration will load always and before all other plugins., (*35)
Note: We advise you leave the original wp-sentry-integration in the /wp-content/plugins folder to still have updates come in through the WordPress updater. However enabling or disabling does nothing if the above script is active (since it will always be enabled)., (*36)
Security Vulnerabilities
If you discover a security vulnerability within WordPress Sentry (wp-sentry), please send an e-mail to Alex Bouma at me@alexbouma.me. All security vulnerabilities will be swiftly addressed., (*37)
License
The WordPress Sentry (wp-sentry) plugin is open-sourced software licensed under the MIT license., (*38)
Wallogit.com
