{"id":23146644,"url":"https://github.com/zeekinteractive/wp-sentry","last_synced_at":"2025-04-04T13:24:04.406Z","repository":{"id":57089689,"uuid":"348011239","full_name":"ZeekInteractive/wp-sentry","owner":"ZeekInteractive","description":"Utility for handling Sentry support with WordPress. Includes the ability to filter out specific errors per project.","archived":false,"fork":false,"pushed_at":"2023-10-26T15:05:49.000Z","size":69,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T01:55:58.120Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZeekInteractive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-03-15T14:54:23.000Z","updated_at":"2021-11-09T15:13:42.000Z","dependencies_parsed_at":"2022-08-20T16:50:13.130Z","dependency_job_id":"b1b959d6-bc3e-4023-b881-d6f3d97aa62f","html_url":"https://github.com/ZeekInteractive/wp-sentry","commit_stats":{"total_commits":10,"total_committers":1,"mean_commits":10.0,"dds":0.0,"last_synced_commit":"cf5b1dd381ee8377af71c602efc4c786de189317"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeekInteractive%2Fwp-sentry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeekInteractive%2Fwp-sentry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeekInteractive%2Fwp-sentry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeekInteractive%2Fwp-sentry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZeekInteractive","download_url":"https://codeload.github.com/ZeekInteractive/wp-sentry/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247183135,"owners_count":20897521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T16:33:59.297Z","updated_at":"2025-04-04T13:24:04.388Z","avatar_url":"https://github.com/ZeekInteractive.png","language":"PHP","readme":"# WordPress Sentry (wp-sentry)\n\nA (unofficial) WordPress plugin to report PHP and JavaScript errors to [Sentry](https://sentry.io).\n\n\n## What?\n\nThis plugin can report PHP errors (optionally) and JavaScript errors (optionally) to [Sentry](https://sentry.io) and integrates with its release tracking.\n\nIt will auto detect authenticated users and add context where possible. All context/tags can be adjusted using filters mentioned below.\n\n\n## Requirements \u0026 Sentry PHP SDK\n\nThis plugin requires PHP `5.4`+ but urges users to use a PHP version that is not end of life (EOL) and no longer supported. For an up-to-date list of PHP versions that are still supported see: http://php.net/supported-versions.php.\n\n- Version `2.1.*` of this plugin will be the last to support PHP `5.3`.\n- Version `2.2.*` of this plugin will be the last to support PHP `5.4`.\n\nPlease note that version `3.x` is the most recent version of the wp-sentry plugin and only supports PHP `7.1` and up. If you need PHP `5.4-7.2` support check out version `2.x` but do keep in mind there are a lot of differences in the Sentry PHP SDK used.\n\n- Version [`2.x`](https://github.com/stayallive/wp-sentry/tree/2.x) of the wp-sentry plugin uses the [`1.x`](https://github.com/getsentry/sentry-php/tree/1.x) version of the official Sentry PHP SDK.\n- Version [`3.x`](https://github.com/stayallive/wp-sentry/tree/master) of the wp-sentry plugin uses the [`2.x`](https://github.com/getsentry/sentry-php/tree/master) version of the official Sentry PHP SDK.\n\n\n## Usage\n\n1. Install this plugin by cloning or copying this repository to your `wp-contents/plugins` folder\n2. Configure your DSN as explained below\n2. Activate the plugin through the WordPress admin interface\n\n**Note:** this plugin does not do anything by default and has no admin interface. A DSN must be configured first.\n\n\n## Configuration\n\n(Optionally) track PHP errors by adding this snippet to your `wp-config.php` and replace `PHP_DSN` with your actual DSN that you find inside Sentry in the project settings under \"Client Keys (DSN)\":\n```php\ndefine( 'WP_SENTRY_PHP_DSN', 'PHP_DSN' );\n```\n\n**Note:** Do not set this constant to disable the PHP tracker.\n\n**Note:** This constant was previously called `WP_SENTRY_DSN` and is still supported.\n\n---\n\n(Optionally) set the error types the PHP tracker will track:\n\n```php\ndefine( 'WP_SENTRY_ERROR_TYPES', E_ALL \u0026 ~E_DEPRECATED \u0026 ~E_NOTICE \u0026 ~E_USER_DEPRECATED );\n```\n\n---\n\n(Optionally) If this flag is enabled, certain personally identifiable information is added by active integrations. Without this flag they are never added to the event, to begin with.\n\nIf possible, it’s recommended to turn on this feature and use the server side PII stripping to remove the values instead.\n\nWhen enabled the current logged in user and IP address will be added to the event.\n\n```php\ndefine( 'WP_SENTRY_SEND_DEFAULT_PII', true );\n```\n\n---\n\n(Optionally) track JavaScript errors by adding this snippet to your `wp-config.php` and replace `JS_DSN` with your actual DSN that you find inside Sentry in the project settings under \"Client Keys (DSN)\":\n```php\ndefine( 'WP_SENTRY_BROWSER_DSN', 'JS_DSN' );\n```\n\n**Note:** Do not set this constant to disable the JavaScript tracker.\n\n**Note:** This constant was previously called `WP_SENTRY_PUBLIC_DSN` and is still supported.\n\n---\n\n(Optionally) enable JavaScript performance tracing by adding this snippet to your `wp-config.php` and replace `0.3` with your desired sampling rate (`0.3` means sample ~30% of your traffic):\n```php\ndefine( 'WP_SENTRY_BROWSER_TRACES_SAMPLE_RATE', 0.3 );\n```\n\n**Note:** Do not set this constant or set it to `0.0` to disable the JavaScript performance tracing.\n\n---\n\n(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.\n\n```php\ndefine( 'WP_SENTRY_VERSION', 'v4.2.0' );\n```\n\n(Optionally) define an environment of your site. Defaults to `unspecified`.\n\n```php\ndefine( 'WP_SENTRY_ENV', 'production' );\n```\n\n\n## Filters\n\nThis plugin provides the following filters to plugin/theme developers.\n\nPlease note that some filters are fired when the Sentry trackers are initialized so they won't fire if you define them in your theme or in a plugin that loads after WP Sentry does.\n\n### Common to PHP \u0026 JavaScript trackers\n\n#### `wp_sentry_user_context` (array)\n\nYou can use this filter to extend the Sentry user context for both PHP and JS trackers.\n\n\u003e **WARNING:** These values are exposed to the public in the JS tracker, so make sure you do not expose anything private!\n\nExample usage:\n\n```php\n/**\n * Customize sentry user context.\n *\n * @param array $user The current sentry user context.\n *\n * @return array\n */\nfunction customize_sentry_user_context( array $user ) {\n    return array_merge( $user, array(\n        'a-custom-user-meta-key' =\u003e 'custom value',\n    ));\n}\nadd_filter( 'wp_sentry_user_context', 'customize_sentry_user_context' );\n```\n\n**Note:** _This filter fires on the WordPress `set_current_user` action and only if the `WP_SENTRY_SEND_DEFAULT_PII` constant is set to `true`._\n\n### Specific to PHP tracker:\n\n#### `wp_sentry_dsn` (string)\n\nYou can use this filter to override the Sentry DSN used for the PHP tracker.\n\nExample usage:\n\n```php\n/**\n * Customize sentry dsn.\n *\n * @param string $dsn The current sentry DSN.\n *\n * @return string\n */\nfunction customize_sentry_dsn( $dsn ) {\n    return 'https://\u003ckey\u003e:\u003csecret\u003e@sentry.io/\u003cproject\u003e';\n}\nadd_filter( 'wp_sentry_dsn', 'customize_sentry_dsn' );\n```\n\n**Note:** _This filter fires on the WordPress `after_setup_theme` action. It is discouraged to use this and instead define the DSN in the `wp-config.php` using the `WP_SENTRY_PHP_DSN` constant_\n\n---\n\n#### `wp_sentry_scope` (void)\n\nYou can use this filter to customize the Sentry [scope](https://docs.sentry.io/enriching-error-data/context/?platform=php).\n\nExample usage:\n\n```php\n/**\n * Customize Sentry PHP SDK scope.\n *\n * @param \\Sentry\\State\\Scope $scope\n *\n * @return void\n */\nfunction customize_sentry_scope( \\Sentry\\State\\Scope $scope ) {\n\t$scope-\u003esetTag('my-custom-tag', 'tag-value');\n}\nadd_filter( 'wp_sentry_scope', 'customize_sentry_scope' );\n```\n\n**Note:** _This filter fires on the WordPress `after_setup_theme` action._\n\n---\n\n#### `wp_sentry_options` (array)\n\nYou can use this filter to customize the Sentry [options](https://docs.sentry.io/error-reporting/configuration/?platform=php).\n\nExample usage:\n\n```php\n/**\n * Customize sentry options.\n *\n * @param array $options The current sentry options.\n *\n * @return array\n */\nfunction customize_sentry_options( \\Sentry\\Options $options ) {\n    // Only sample 90% of the events\n    $options-\u003esetSampleRate(0.9);\n}\nadd_filter( 'wp_sentry_options', 'customize_sentry_options' );\n```\n\n**Note:** _This filter fires on the WordPress `after_setup_theme` action._\n\n### Specific to JS tracker\n\n#### `wp_sentry_public_dsn` (string)\n\nYou can use this filter to override the Sentry DSN used for the JS tracker.\n\n\u003e **WARNING:** This value is exposed to the public, so make sure you do not use your private DSN!\n\nExample usage:\n\n```php\n/**\n * Customize public sentry dsn.\n *\n * @param string $dsn The current sentry public dsn.\n *\n * @return string\n */\nfunction customize_public_sentry_dsn( $dsn ) {\n    return 'https://\u003ckey\u003e@sentry.io/\u003cproject\u003e';\n}\nadd_filter( 'wp_sentry_public_dsn', 'customize_public_sentry_dsn' );\n```\n\n---\n\n#### `wp_sentry_public_options` (array)\n\nYou can use this filter to customize/override the Sentry [options](https://docs.sentry.io/error-reporting/configuration/?platform=browser#common-options) used to initialize the JS tracker.\n\n\u003e **WARNING:** These values are exposed to the public, so make sure you do not expose anything private !\n\nExample usage:\n\n```php\n/**\n * Customize public sentry options.\n *\n * Note: Items prefixed with `regex:` in blacklistUrls and whitelistUrls option arrays\n * will be translated into pure RegExp.\n *\n * @param array $options The current sentry public options.\n *\n * @return array\n */\nfunction customize_sentry_public_options( array $options ) {\n    return array_merge( $options, array(\n        'sampleRate' =\u003e '0.5',\n        'blacklistUrls' =\u003e array(\n            'https://github.com/',\n            'regex:\\\\w+\\\\.example\\\\.com',\n        ),\n    ));\n}\nadd_filter( 'wp_sentry_public_options', 'customize_sentry_public_options' );\n```\n\n#### `wp_sentry_public_context` (array)\n\nYou can use this filter to customize/override the Sentry context, you can modify the `user`, `tags` and `extra` context.\n\n\u003e **WARNING:** These values are exposed to the public, so make sure you do not expose anything private !\n\nExample usage:\n\n```php\n/**\n * Customize public sentry context.\n *\n * @param array $context The current sentry public context.\n *\n * @return array\n */\nfunction customize_sentry_public_context( array $context ) {\n    $context['tags']['my-custom-tag'] = 'tag-value';\n\n    return $context;\n}\nadd_filter( 'wp_sentry_public_context', 'customize_sentry_public_context' );\n```\n\n\n## High volume of notices\n\nMany plugin in the WordPress ecosystem generate notices that are captured by the Senty plugin.\n\nThis can cause a high volume of events and even slower page loads because of those events being transmitted to Sentry.\n\nThe prevent this you can set the following in your `wp-config.php` to filter out errors of the notice type.\n\n```php\ndefine( 'WP_SENTRY_ERROR_TYPES', E_ALL \u0026 ~E_NOTICE );\n```\n\n\n## Capturing handled exceptions\n\nThe best thing to do with an exception is to capture it yourself, however you might still want to know about it.\n\nThe Sentry plugin only captures unhandled exceptions and fatal errors, to capture handled exception you can do the following:\n\n```php\ntry {\n\tmyMethodThatCanThrowAnException();\n} catch ( \\Exception $e ) {\n\t// We are using wp_sentry_safe to make sure this code runs even if the Sentry plugin is disabled\n\tif ( function_exists( 'wp_sentry_safe' ) ) {\n\t\twp_sentry_safe( function ( \\Sentry\\State\\HubInterface $client ) use ( $e ) {\n\t\t\t$client-\u003ecaptureException( $e );\n\t\t} );\n\t}\n\n\twp_die( 'There was an error doing this thing you were doing, we have been notified!' );\n}\n```\n\nIf you need to attach extra data only for the handled exception, you could add [Structured Context](https://docs.sentry.io/platforms/php/enriching-events/context/#structured-context):\n\n```php\nif (function_exists('wp_sentry_safe')) {\n    wp_sentry_safe(function (\\Sentry\\State\\HubInterface $client) use ($e) {\n        $client-\u003ewithScope(function (\\Sentry\\State\\Scope $scope) use ($client, $e) {\n            $scope-\u003esetExtra('user_data', $e-\u003egetData());\n            $client-\u003ecaptureException($e);\n        });\n    });\n}\n```\n\nIf you need to add data to the scope in every case use `configureScope` in [wp_sentry_scope filter](#wp_sentry_scope-void).\n\n## Capturing plugin errors\n\nSince 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.\n\nYou 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 exist you must create that too).\n\n```php\n\u003c?php\n\n$wp_sentry = __DIR__ . '/../plugins/wp-sentry-integration/wp-sentry.php';\n\nif ( ! file_exists( $wp_sentry ) ) {\n\treturn;\n}\n\nrequire $wp_sentry;\n\ndefine( 'WP_SENTRY_MU_LOADED', true );\n```\n\nNow `wp-sentry-integration` will load always and before all other plugins.\n\n**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).\n\n\n## Advanced: Client side hook\n\nWhen using the Sentry Browser integration it is possible to do some work in the client browser before Sentry is initialized to change options and/or prevent the Browser SDK from initializing at all.\n\nYou do this by defining a `wp_sentry_hook` JavaScript function before the Sentry Browser JavaScript file is included (keep this function small and easy since any errors that occur in there are not tracked by the Browser SDK).\n\nA quick example on how you would disable the Browser SDK using `wp_add_inline_script`:\n\n```php\nadd_action( 'wp_enqueue_scripts', function () {\n    wp_add_inline_script( 'wp-sentry-browser', 'function wp_sentry_hook(options) { return someCheckInYourCode() ? true : false; }', 'before' );\n} );\n```\n\nWhen the `wp_sentry_hook` function returns `false` the initialization of the Sentry Brower SDK will be stopped. Any other return value will be ignored.\n\nTo modify the options you can modify the object passed as the first argument of the `wp_sentry_hook`, this object will later be passed to `Sentry.init` to initialize the Browser SDK.\n\n## License\n\nThe WordPress Sentry (wp-sentry) plugin is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeekinteractive%2Fwp-sentry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeekinteractive%2Fwp-sentry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeekinteractive%2Fwp-sentry/lists"}