diff --git a/README.md b/README.md index 2b16840..f30b3c1 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,180 @@ # Rollbar for WordPress -[![Plugin Version](https://img.shields.io/wordpress/plugin/v/rollbar.svg)](https://wordpress.org/plugins/rollbar/) [![WordPress Version Compatibility](https://img.shields.io/wordpress/v/rollbar.svg)](https://wordpress.org/plugins/rollbar/) [![Downloads](https://img.shields.io/wordpress/plugin/dt/rollbar.svg)](https://wordpress.org/plugins/rollbar/) [![Rating](https://img.shields.io/wordpress/plugin/r/rollbar.svg)](https://wordpress.org/plugins/rollbar/) -Rollbar full-stack error tracking for WordPress +[![Plugin Version](https://img.shields.io/wordpress/plugin/v/rollbar.svg)](https://wordpress.org/plugins/rollbar/) [![WordPress Version Compatibility](https://img.shields.io/wordpress/v/rollbar.svg)](https://wordpress.org/plugins/rollbar/) [![Downloads](https://img.shields.io/wordpress/plugin/dt/rollbar.svg)](https://wordpress.org/plugins/rollbar/) [![Rating](https://img.shields.io/wordpress/plugin/r/rollbar.svg)](https://wordpress.org/plugins/rollbar/) -The full documentation is available [here](https://docs.rollbar.com/v1.0.0/docs/wordpress). +Rollbar full-stack error tracking for WordPress. -## Description Rollbar collects errors that happen in your application, notifies you, and analyzes them so you can debug and fix them. - This plugin integrates Rollbar into your WordPress installation. -Find out [how Rollbar can help you decrease development and maintenance costs](https://rollbar.com/features/). +#### Helpful Links -See [real companies improving their development workflow thanks to Rollbar](https://rollbar.com/customers/). +* [Documentation](https://docs.rollbar.com/docs/wordpress) +* [Official WordPress.org Plugin](https://wordpress.org/plugins/rollbar/) +* [How Rollbar Works](https://rollbar.com/discover/) +* [Rollbar Pricing](https://rollbar.com/pricing/) [Official WordPress.org Plugin](https://wordpress.org/plugins/rollbar/) +#### Table of Contents + +1. [Installation](#installation) + 1. [Through WordPress Plugin directory](#through-wordpress-plugin-directory) + 2. [Through Packagist](#through-packagist-recommended-new) + 3. [Through WPackagist](#through-wpackagist) +2. [Configuration](#configuration) + 1. [WordPress Admin](#wordpress-admin) + 2. [Programmatic Configuration](#programmatic-configuration) +3. [Advanced Use](#advanced-use) + 1. [Constants](#constants) + 2. [Environment Variables](#environment-variables) + 3. [Filters](#filters) + 4. [Telemetry](#telemetry) +4. [Help / Support](#help--support) +5. [Special thanks](#special-thanks) +6. [Contributing](#contributing) +7. [Testing](#testing) ## Installation ### Through [WordPress Plugin directory](https://wordpress.org/plugins/rollbar/) -The easiest way to install the plugin is from the WordPress Plugin directory. If you have an existing WordPress installation and you want to add Rollbar: +The easiest way to install the plugin is from the WordPress Plugin directory. If you have an existing WordPress +installation, and you want to add Rollbar: 1. In your WordPress administration panel go to `Plugins` → `Add New`. 2. Search for "Rollbar" and find `Rollbar` by Rollbar in the search results. 3. Click `Install Now` next to the `Rollbar` plugin. 4. In `Plugins` → `Installed plugins` find `Rollbar` and click `Activate` underneath. -5. Log into your [Rollbar account dashboard](https://rollbar.com/login/): - 1. Go to `Settings` → `Project Access Tokens`. - 2. Copy the token value under `post_client_item` and `post_server_item`. -6. In WordPress, navigate to `Settings` → `Rollbar`: - 1. Enable `PHP error logging` and/or `Javascript error logging` depending on your needs. - 2. Paste the tokens you copied in step 7 in `Access Token` section. - 3. Provide the name of your environment in `Environment`. By default, the environment will be taken from `WP_ENV` environment variable if it's set otherwise it's blank. We recommend to fill this out either with `development` or `production`. - 4. Pick a minimum logging level. Only errors at that or higher level will be reported. For reference: [PHP Manual: Predefined Error Constants](http://php.net/manual/en/errorfunc.constants.php). - 5. Click `Save Changes`. - -**Warning**: This installation method might not be suitable for complex WordPress projects. The plugin installed this way will be self-contained and include all of the required dependencies for itself and `rollbar/rollbar-php` library. In complex projects, this might lead to version conflicts between dependencies and other plugins/packages. If this is an issue in your project, we recommend the "Advanced" installation method. For more information why this might be important for you, read [Using Composer with WordPress](https://roots.io/using-composer-with-wordpress/). - -### Through [wpackagist](https://wpackagist.org/) (if you manage your project with Composer) *recommended* - -This is a recommended way to install Rollbar plugin for advanced projects. This way ensures the plugin and all of its' dependencies are managed by Composer. - -1. If your WordPress project is not managed with Composer yet, we suggest looking into upgrading your WordPress: [Using Composer with WordPress](https://roots.io/using-composer-with-wordpress/). -2. In your `composer.json` add `wpackagist-plugin/rollbar` to your `require` section, i.e.: -```json - "require": { - "php": ">=8.1", - ..., - "wpackagist-plugin/rollbar": "*" - } + +**Warning**: This installation method might not be suitable for complex WordPress projects. The plugin installed this +way will be self-contained and include all of the required dependencies for itself and the `rollbar/rollbar-php` +library. In complex projects, this might lead to version conflicts between dependencies and other plugins/packages. If +this is an issue in your project, we recommend the "Packagist" installation method. + +### Through [Packagist](https://packagist.org/packages/rollbar/rollbar-php-wordpress) *recommended new* + +*Note: this only works if your WordPress project is managed with Composer. +Read [Using Composer with WordPress](https://roots.io/using-composer-with-wordpress/) for more details.* + +This is a recommended way to install the Rollbar plugin for advanced projects. This way ensures the plugin and all of +its dependencies are managed by Composer. + +You can install the plugin by running the following command in the root directory of your WordPress project: + +```txt +composer require rollbar/rollbar-php-wordpress:^3.0 ``` -3. Issue command `composer install` in the root directory of your WordPress project. -4. Go to step #4 above. -## Advanced Use +### Through [WPackagist](https://wpackagist.org/) -### Constants +*Note: if your WordPress project is managed with Composer, we strongly recommend installing the plugin through +Packagist instead.* -The plugin provides a number of constants that can be used to configure the plugin. These should typically be defined in -the `wp-config.php` file. +*Installing the plugin from wpackagist.org instead of packagist.org will result in the plugin being managed by +Composer. However, the downside is that it's dependencies will not be managed by composer. Instead they will be packaged +in the plugin's `vendor` directory not in your project's `vendor` directory. This has the potential to cause name +collisions if other plugins or your project use different versions of the same dependencies.* -Note: If you define these constants, they will override the settings defined in the WordPress Admin. +To install the plugin from wpackagist.org run the following steps command in the root directory of your WordPress +project: -`ROLLBAR_DISABLE_ADMIN` - (optional) Removes the Rollbar Admin menu from the WordPress Admin if set to `true`. This -allows for the plugin to be used without the admin settings page, for example, if the plugin is managed via the -`wp-config.php` file. +```txt +composer require wpackagist-plugin/rollbar +``` -`ROLLBAR_SETTINGS` - (optional) An associative array of settings to override the settings values from the WordPress -Admin. Note: if you disable the admin settings page with `ROLLBAR_DISABLE_ADMIN` constant, this constant must be used to -configure the plugin. +## Configuration -`ROLLBAR_ACCESS_TOKEN` - The Rollbar PHP server access token. +The plugin can be configured in the WordPress Admin or programmatically. -`ROLLBAR_CLIENT_ACCESS_TOKEN` - The Rollbar JS client access token. +### WordPress Admin -#### WordPress Constants +The plugin provides a settings page in the WordPress Admin that allows you to configure the plugin. This settings page +can be disabled by setting the `ROLLBAR_DISABLE_ADMIN` constant to `true` in your `wp-config.php` file. -The Rollbar plugin respects the following WordPress constants: +1. In `Plugins` → `Installed plugins` find `Rollbar` and click `Activate` underneath. +2. Log into your [Rollbar account dashboard](https://rollbar.com/login/): + 1. Go to `Settings` → `Project Access Tokens`. + 2. Copy the token value under `post_client_item` and `post_server_item`. +3. In WordPress, navigate to `Settings` → `Rollbar`: + 1. Enable `PHP error logging` and/or `Javascript error logging` depending on your needs. + 2. Paste the tokens you copied in step 7 in `Access Token` section. + 3. Provide the name of your environment in `Environment`. By default, the environment will be taken from `WP_ENV` + environment variable if it's set otherwise it's blank. We recommend to fill this out either with `development` or + `production`. + 4. Pick a minimum logging level. Only errors at that or higher level will be reported. For + reference: [PHP Manual: Predefined Error Constants](http://php.net/manual/en/errorfunc.constants.php). + 5. Click `Save Changes`. -`WP_ENV` - (optional) The environment name. This is used to determine the environment name for the Rollbar project. +### Programmatic Configuration -`WP_PROXY_HOST` - (optional) The proxy host. If both `WP_PROXY_HOST` and `WP_PROXY_PORT` are set, the plugin will use -the respect the HTTP proxy when making requests to Rollbar. +The plugin can also be configured programmatically. This is useful if you want to configure the plugin in a more +advanced way or if you want to disable the admin settings page. -`WP_PROXY_PORT` - (optional) The proxy port. +```php +// wp-config.php + +// Configure the plugin. +define( 'ROLLBAR_SETTINGS', [ + 'php_logging_enabled' => true, + 'server_side_access_token' => '', + 'js_logging_enabled' => true, + 'client_side_access_token' => '', + 'environment' => 'development', + 'included_errno' => E_ERROR, + 'enable_person_reporting' => true, +] ); + +// Optional: disable the admin settings page so the plugin is configured only programmatically. +define( 'ROLLBAR_DISABLE_ADMIN', true ); +``` -`WP_PROXY_USERNAME` - (optional) The proxy username. +## Advanced Use -`WP_PROXY_PASSWORD` - (optional) The proxy password. +### Constants -`WP_PROXY_BYPASS_HOSTS` - (optional) The proxy bypass hosts. This is a comma-separated list of hosts that should not be -proxied. If proxying is enabled, but you don't want to proxy requests to Rollbar, you can add `api.rollbar.com` to this -list. +The plugin provides a number of constants that can be used to configure the plugin. These should typically be defined in +the `wp-config.php` file. -### Environment Variables +Note: If you define these constants, they will override the settings defined in the WordPress Admin. -The plugin looks for the following environment variables to configure itself. Note: these are overridden by the -constants defined above. +* `ROLLBAR_DISABLE_ADMIN` - (optional) Removes the Rollbar Admin menu from the WordPress Admin if set to `true`. This + allows for the plugin to be used without the admin settings page, for example, if the plugin is managed via the + `wp-config.php` file. +* `ROLLBAR_SETTINGS` - (optional) An associative array of settings to override the settings values from the WordPress + Admin. Note: if you disable the admin settings page with `ROLLBAR_DISABLE_ADMIN` constant, this constant must be used + to configure the plugin. +* `ROLLBAR_ACCESS_TOKEN` - The Rollbar PHP server access token. +* `ROLLBAR_CLIENT_ACCESS_TOKEN` - The Rollbar JS client access token. + +#### WordPress Constants -`ROLLBAR_ACCESS_TOKEN` - The Rollbar PHP server access token. +The Rollbar plugin respects the following WordPress constants: -`ROLLBAR_CLIENT_ACCESS_TOKEN` - The Rollbar JS client access token. +* `WP_ENV` - (optional) The environment name. This is used to determine the environment name for the Rollbar project. +* `WP_PROXY_HOST` - (optional) The proxy host. If both `WP_PROXY_HOST` and `WP_PROXY_PORT` are set, the plugin will use + the respect the HTTP proxy when making requests to Rollbar. +* `WP_PROXY_PORT` - (optional) The proxy port. +* `WP_PROXY_USERNAME` - (optional) The proxy username. +* `WP_PROXY_PASSWORD` - (optional) The proxy password. +* `WP_PROXY_BYPASS_HOSTS` - (optional) The proxy bypass hosts. This is a comma-separated list of hosts that should not + be + proxied. If proxying is enabled, but you don't want to proxy requests to Rollbar, you can add `api.rollbar.com` to + this list. -`WP_ENV` - (optional) The environment name. This is used to determine the environment name for the Rollbar project. +### Environment Variables + +The plugin looks for the following environment variables to configure itself. Note: these are overridden by the +constants defined above. + +* `ROLLBAR_ACCESS_TOKEN` - The Rollbar PHP server access token. +* `ROLLBAR_CLIENT_ACCESS_TOKEN` - The Rollbar JS client access token. +* `WP_ENV` - (optional) The environment name. This is used to determine the environment name for the Rollbar project. ### Filters The plugin provides a number of filters that allow you to customize the behavior of the plugin. -### `apply_filters('rollbar_api_admin_permission', bool $value, string $route, WP_REST_Request $request)` +#### `apply_filters('rollbar_api_admin_permission', bool $value, string $route, WP_REST_Request $request)` Filter to allow or deny access to a Rollbar route in the WordPress REST API used in the WordPress Admin. Generally, this should be the same as the `rollbar_user_can_view_admin` filter. @@ -120,7 +185,7 @@ this should be the same as the `rollbar_user_can_view_admin` filter. * `string $route` - The route being accessed. * `WP_REST_Request $request` - The REST request object. -### `apply_filters('rollbar_js_config', array $config)` +#### `apply_filters('rollbar_js_config', array $config)` Filters the Rollbar JavaScript configuration. @@ -128,7 +193,7 @@ Filters the Rollbar JavaScript configuration. * `array $config` - The Rollbar JavaScript configuration array. -### `apply_filters('rollbar_plugin_settings', array $settings)` +#### `apply_filters('rollbar_plugin_settings', array $settings)` Filters the Rollbar plugin settings. @@ -136,7 +201,7 @@ Filters the Rollbar plugin settings. * `array $settings` - The Rollbar plugin settings array. -### `apply_filters('rollbar_php_config', array $config)` +#### `apply_filters('rollbar_php_config', array $config)` Filters the Rollbar Core SDK PHP configuration. @@ -144,28 +209,28 @@ Filters the Rollbar Core SDK PHP configuration. * `array $config` - The Rollbar PHP configuration array. -### `apply_filters('rollbar_telemetry_actions', array $actions)` +#### `apply_filters('rollbar_telemetry_actions', array $actions)` Filter the list of actions to instrument with Telemetry. **Parameters** -* `array $actions` - An associative array where the keys are action names and the values are the number of +* `array $actions` - An associative array where the keys are action names and the values are the number of arguments accepted by the action. -### `apply_filters('rollbar_telemetry_custom_handlers', array $handlers)` +#### `apply_filters('rollbar_telemetry_custom_handlers', array $handlers)` Filter the list of custom action event handlers for Telemetry. -Note: The custom action handler will only be called if the action is instrumented with Telemetry. This means you must +Note: The custom action handler will only be called if the action is instrumented with Telemetry. This means you must select the action on the settings page, or add it to the list of actions using the `rollbar_telemetry_actions` filter. **Parameters** -* `array $handlers` - An associative array where the keys are action names +* `array $handlers` - An associative array where the keys are action names and the values are the custom event handler. -### `apply_filters('rollbar_user_can_view_admin', bool $disable)` +#### `apply_filters('rollbar_user_can_view_admin', bool $disable)` Filter to enable / disable the admin settings page of the plugin for the current user. @@ -177,24 +242,24 @@ This filter cannot override the `ROLLBAR_DISABLE_ADMIN` constant. ### Telemetry -Starting in version 3.0.0 of the Rollbar plugin, Telemetry is enabled by default. Telemetry is a feature that allows -the plugin to track events that occur in your WordPress installation prior to an exception or message being sent to -Rollbar. The Telemetry data is sent to Rollbar along with the exception or message, and can be used to provide +Starting in version 3.0.0 of the Rollbar plugin, Telemetry is enabled by default. Telemetry is a feature that allows +the plugin to track events that occur in your WordPress installation prior to an exception or message being sent to +Rollbar. The Telemetry data is sent to Rollbar along with the exception or message, and can be used to provide additional context and help debug the issue. You can modify the list of actions you want to instrument with Telemetry by selecting them on the settings page, or -using the `rollbar_telemetry_actions` filter. To use a custom handler for a specific action, use the +using the `rollbar_telemetry_actions` filter. To use a custom handler for a specific action, use the `rollbar_telemetry_custom_handlers` filter. This can also be used to change the handler on any of the default actions. #### Registering custom actions -You can also instrament custom actions like this: +You can also instrument custom actions like this: ```php use Rollbar\WordPress\Telemetry\Listener; // Register a custom action with a custom handler function. -$listener = Listener::getInstance()->instrumentAction( +Listener::getInstance()->instrumentAction( action: 'my_custom_action', priority: 10, acceptedArgs: 2, @@ -205,7 +270,7 @@ $listener = Listener::getInstance()->instrumentAction( ); // Use the default handler for the action. -$listener = Listener::getInstance()->instrumentAction( +Listener::getInstance()->instrumentAction( action: 'my_other_custom_action', priority: 10, acceptedArgs: 1, @@ -213,7 +278,7 @@ $listener = Listener::getInstance()->instrumentAction( ); ``` -Of course, you can also call `Rollbar::captureTelemetryEvent()` directly to send custom events. See the +Of course, you can also call `Rollbar::captureTelemetryEvent()` directly to send custom events. See the [Telemetry documentation](https://docs.rollbar.com/docs/php-telemetry) for more information. ## Help / Support @@ -222,26 +287,32 @@ If you run into any issues, please email us at [support@rollbar.com](mailto:supp For bug reports, please [open an issue on GitHub](https://github.com/rollbar/rollbar-php-wordpress/issues/new). -## Special thanks - -The original author of this package is [@flowdee](https://twitter.com/flowdee/). This is a fork and continuation of his efforts. - ## Contributing 1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Added some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Verify your commit passes the code standards enforced by [Codacy](https://www.codacy.com). -5. Create new Pull Request +4. Make sure tests pass (see below). +5. Push to the branch (`git push origin my-new-feature`) +6. Create a new Pull Request ## Testing -In order to run the tests, you will need to install the dependencies for [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) including Node.js, git, and docker. +To run the tests, you will need to install the dependencies for +[@wordpress/env](https://www.npmjs.com/package/@wordpress/env) including Node.js, git, and Docker. + +1. `npm install` - This will install the dependencies to set up the local environment. +2. `npm run start` - This will start a local WordPress installation with the Rollbar plugin installed. +3. `npm run test` - This will run the tests. -1. npm install -2. npm run test -You can set the `WP_ENV_PHP_VERSION` enviormental variable to test with different versions of PHP. If you are changing the version, you can do so by running `WP_ENV_PHP_VERSION="8.2" npm run wp-env start -- --update` and setting the enviornmental variable based on +You can set the `WP_ENV_PHP_VERSION` environment variable to test with different versions of PHP. If you are changing +the version, you can do so by running `WP_ENV_PHP_VERSION="8.2" npm run wp-env start -- --update` and setting the +environment variable based on the version you want to test with. + +## Special thanks + +The original author of this package is [@flowdee](https://twitter.com/flowdee/). This is a fork and continuation of his +efforts. ## Tagging @@ -253,24 +324,26 @@ This is only for contributors with committer access: 3. Add record in the `Upgrade Notice` section of the `readme.txt`. 4. Bump the plugin version in `rollbar-php-wordpress.php` in the `Version:` comment. 5. Bump the plugin version in `src/Plugin.php` in the `\Rollbar\WordPress\Plugin::VERSION` constant. - 5. Add and commit the changes you made to bump the plugin version: `git add readme.txt rollbar-php-wordpress.php src/Plugin.php && git commit -m"Bump version to v[version number]"` - 6. Bump versions of the JS and CSS files versions in Settings.php class to force refresh of those assets on users' installations. - 7. `git push origin master` + 6. Add and commit the changes you made to bump the plugin version: + `git add readme.txt rollbar-php-wordpress.php src/Plugin.php && git commit -m"Bump version to v[version number]"` + 7. Bump versions of the JS and CSS files versions in Settings.php class to force refresh of those assets on users' + installations. + 8. `git push origin master` 2. Tag the new version from the `master` branch and push upstream with `git tag v[version number] && git push --tags`. 3. Publish a new release on [GitHub](https://github.com/rollbar/rollbar-php-wordpress/releases). 4. Update the WordPress Plugin Directory Subversion Repository. 1. Fetch the latest contents of Subversion repo with `svn update`. 2. Remove the contents of `trunk/` with `rm -Rf trunk`. 3. Update the contents of `trunk/` with a clone of the tag you created in step 2. - 2. `git clone https://github.com/rollbar/rollbar-php-wordpress.git trunk` - 3. `cd trunk && git checkout tags/v[version number] && cd ..` - 4. `rm -Rf trunk/.git` - 5. `svn add trunk --force` - 6. `svn commit -m"Sync with GitHub repo"` - 4. Create the Subversion tag: `svn copy https://plugins.svn.wordpress.org/rollbar/trunk https://plugins.svn.wordpress.org/rollbar/tags/[version number] -m"Tag [version number]"`. Notice the version number in Subversion doesn't include the "v" prefix. + 1. `git clone https://github.com/rollbar/rollbar-php-wordpress.git trunk` + 2. `cd trunk && git checkout tags/v[version number] && cd ..` + 3. `rm -Rf trunk/.git` + 4. `svn add trunk --force` + 5. `svn commit -m"Sync with GitHub repo"` + 4. Create the Subversion tag: + `svn copy https://plugins.svn.wordpress.org/rollbar/trunk https://plugins.svn.wordpress.org/rollbar/tags/[version number] -m"Tag [version number]"`. + Notice the version number in Subversion doesn't include the "v" prefix. ## Disclaimer This plugin is a community-driven contribution. All rights reserved to Rollbar. - -[![Rollbar](https://d26gfdfi90p7cf.cloudfront.net/rollbar-badge.144534.o.png)](https://rollbar.com/) diff --git a/assets/screenshot-1.png b/assets/screenshot-1.png new file mode 100644 index 0000000..60636fd Binary files /dev/null and b/assets/screenshot-1.png differ diff --git a/composer.json b/composer.json index 3a9436f..4f45c6c 100644 --- a/composer.json +++ b/composer.json @@ -41,7 +41,8 @@ "extra": { "scripts-description": { "test": "Run all tests. Wrapper around npm run test" - } + }, + "installer-name": "rollbar" }, "scripts": { "test": [ diff --git a/readme.txt b/readme.txt index c009c04..8c5bb5a 100644 --- a/readme.txt +++ b/readme.txt @@ -1,37 +1,34 @@ === Rollbar === -Contributors: arturmoczulski, jorbin +Contributors: arturmoczulski, jorbin, danielmorell Tags: rollbar, full stack, error, tracking, error tracking, error reporting, reporting, debug -Requires at least: 4.4.0 -Tested up to: 6.3.1 -Stable tag: 2.7.1 +Requires at least: 6.5.0 +Tested up to: 6.8 +Requires PHP: 8.1 +Stable tag: 3.0.0 License: GPLv2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Official Rollbar full-stack error tracking for WordPress supported by Rollbar, Inc. == Description == -Rollbar collects errors that happen in your application, notifies you, and analyzes them so you can debug and fix them. +Rollbar collects errors that happen in your application, notifies you, and analyzes them so you can debug and fix them. This plugin integrates Rollbar into your WordPress installation. -Find out [how Rollbar can help you decrease development and maintenance costs](https://rollbar.com/features/). - -See [real companies improving their development workflow thanks to Rollbar](https://rollbar.com/customers/). - = Features = -* PHP & Javascript error logging -* Define an environment for each single WordPress installation or Multisite blog -* Specify your desired logging level +* PHP & JavaScript error logging. +* Define an environment for each single WordPress installation or Multisite blog. +* Specify your desired logging level. * Regular updates and improvements! -> Please note
-> In order to use this plugin, a [Rollbar account](https://rollbar.com/) is required. +**Please note:** +In order to use this plugin, a [Rollbar account](https://rollbar.com/) is required. = Support = -* Browse [issue tracker](https://github.com/rollbar/rollbar-php-wordpress/issues) on GitHub and report new issues -* If you run into any issues, please email us at [support@rollbar.com](mailto:support@rollbar.com) +* Browse [issue tracker](https://github.com/rollbar/rollbar-php-wordpress/issues) on GitHub and report new issues. +* If you run into any issues, please email us at [support@rollbar.com](mailto:support@rollbar.com). * For bug reports, please [open an issue on GitHub](https://github.com/rollbar/rollbar-php-wordpress/issues/new). = You like it? = @@ -46,62 +43,110 @@ This plugin is a community-driven contribution. All rights reserved to [Rollbar] The installation and configuration of the plugin are as simple as it can be. -= Through [WordPress Plugin directory](https://wordpress.org/plugins/rollbar/) = += Through WordPress Plugin directory = -The easiest way to install the plugin is from the WordPress Plugin directory. If you have an existing WordPress installation and you want to add Rollbar: +The easiest way to install the plugin is from the WordPress Plugin directory. If you have an existing WordPress +installation, and you want to add Rollbar: 1. In your WordPress administration panel go to `Plugins` → `Add New`. 2. Search for "Rollbar" and find `Rollbar` by Rollbar in the search results. 3. Click `Install Now` next to the `Rollbar` plugin. -4. In `Plugins` → `Installed plugins` find `Rollbar` and click `activate` underneath. -5. Log into your [Rollbar account dashboard](https://rollbar.com/login/). -6. Go to `Settings` → `Project Access Tokens`. -7. Copy the token value under `post_client_item` and `post_server_item`. -8. Navigate to `Tools` → `Rollbar`. -9. Enable `PHP error logging` and/or `Javascript error logging` depending on your needs. -10. Paste the tokens you copied in step 7 in `Access Token` section. -11. Provide the name of your environment in `Environment`. By default, the environment will be taken from `WP_ENV` environment variable if it's set otherwise it's blank. We recommend to fill this out either with `development` or `production`. -12. Pick a minimum logging level. Only errors at that or higher level will be reported. For reference: [PHP Manual: Predefined Error Constants](http://php.net/manual/en/errorfunc.constants.php). -13. Click `Save Changes`. +4. In `Plugins` → `Installed plugins` find `Rollbar` and click `Activate` underneath. + +**Warning**: This installation method might not be suitable for complex WordPress projects. The plugin installed this +way will be self-contained and include all of the required dependencies for itself and the `rollbar/rollbar-php` +library. In complex projects, this might lead to version conflicts between dependencies and other plugins/packages. If +this is an issue in your project, we recommend the "Packagist" installation method. -**Warning**: This installation method might not be suitable for complex WordPress projects. The plugin installed this way will be self-contained and include all of the required dependencies for itself and `rollbar/rollbar-php` library. In complex projects, this might lead to version conflicts between dependencies and other plugins/packages. If this is an issue in your project, we recommend the "Advanced" installation method. For more information why this might be important for you, read [Using Composer with WordPress](). += Through Packagist = -= Through [wpackagist](https://wpackagist.org/) (if you manage your project with Composer) *recommended* = +*Note: this only works if your WordPress project is managed with Composer. +Read [Using Composer with WordPress](https://roots.io/using-composer-with-wordpress/) for more details.* -This is a recommended way to install Rollbar plugin for advanced projects. This way ensures the plugin and all of its' dependencies are managed by Composer. +This is a recommended way to install the Rollbar plugin for advanced projects. This way ensures the plugin and all of +its dependencies are managed by Composer. -1. If your WordPress project is not managed with Composer yet, we suggest looking into upgrading your WordPress: [Using Composer with WordPress](). -2. In your `composer.json` add `wpackagist-plugin/rollbar` to your `require` section, i.e.: +You can install the plugin by running the following command in the root directory of your WordPress project: + +```txt +composer require rollbar/rollbar-php-wordpress:^3.0 ``` - "require": { - "php": ">=8.1", - ..., - "wpackagist-plugin/rollbar": "*" - } + += Through WPackagist = + +*Note: if your WordPress project is managed with Composer, we strongly recommend installing the plugin through +Packagist instead.* + +*Installing the plugin from wpackagist.org instead of packagist.org will result in the plugin being managed by +Composer. However, the downside is that it's dependencies will not be managed by composer. Instead they will be packaged +in the plugin's `vendor` directory not in your project's `vendor` directory. This has the potential to cause name +collisions if other plugins or your project use different versions of the same dependencies.* + +To install the plugin from wpackagist.org run the following steps command in the root directory of your WordPress +project: + +```txt +composer require wpackagist-plugin/rollbar +``` + += Configuration = + +The plugin can be configured in the WordPress Admin or programmatically. + +**WordPress Admin** + +The plugin provides a settings page in the WordPress Admin that allows you to configure the plugin. This settings page +can be disabled by setting the `ROLLBAR_DISABLE_ADMIN` constant to `true` in your `wp-config.php` file. + +1. In `Plugins` → `Installed plugins` find `Rollbar` and click `Activate` underneath. +2. Log into your [Rollbar account dashboard](https://rollbar.com/login/): + 1. Go to `Settings` → `Project Access Tokens`. + 2. Copy the token value under `post_client_item` and `post_server_item`. +3. In WordPress, navigate to `Settings` → `Rollbar`: + 1. Enable `PHP error logging` and/or `Javascript error logging` depending on your needs. + 2. Paste the tokens you copied in step 7 in `Access Token` section. + 3. Provide the name of your environment in `Environment`. By default, the environment will be taken from `WP_ENV` + environment variable if it's set otherwise it's blank. We recommend to fill this out either with `development` or + `production`. + 4. Pick a minimum logging level. Only errors at that or higher level will be reported. For + reference: [PHP Manual: Predefined Error Constants](http://php.net/manual/en/errorfunc.constants.php). + 5. Click `Save Changes`. + +**Programmatic Configuration** + +The plugin can also be configured programmatically. This is useful if you want to configure the plugin in a more +advanced way or if you want to disable the admin settings page. + +```php +// wp-config.php + +// Configure the plugin. +define( 'ROLLBAR_SETTINGS', [ + 'php_logging_enabled' => true, + 'server_side_access_token' => '', + 'js_logging_enabled' => true, + 'client_side_access_token' => '', + 'environment' => 'development', + 'included_errno' => E_ERROR, + 'enable_person_reporting' => true, +] ); + +// Optional: disable the admin settings page so the plugin is configured only programmatically. +define( 'ROLLBAR_DISABLE_ADMIN', true ); ``` -3. Issue command `composer install` in the root directory of your WordPress project. -4. In `Plugins` → `Installed plugins` find `Rollbar` and click `Activate` underneath. -5. Log into your [Rollbar account dashboard](https://rollbar.com/login/). -6. Go to `Settings` → `Project Access Tokens`. -7. Copy the token value under `post_client_item` and `post_server_item`. -8. Navigate to `Tools` → `Rollbar`. -9. Enable `PHP error logging` and/or `Javascript error logging` depending on your needs. -10. Paste the tokens you copied in step 7 in `Access Token` section. -11. Provide the name of your environment in `Environment`. By default, the environment will be taken from `WP_ENV` environment variable if it's set otherwise it's blank. -12. Pick a minimum logging level. Only errors at that or higher level will be reported. For reference: [PHP Manual: Predefined Error Constants](http://php.net/manual/en/errorfunc.constants.php). -13. Click `Save Changes`. == Frequently Asked Questions == = Multisite supported? = -Yes of course. Additionally, you can assign different environments to each of your blogs. +Yes, of course. Additionally, you can assign different environments to each of your blogs. = I have a complex WordPress project and use composer for managing dependencies. Is your plugin composer friendly? = -Yes. It's actually the recommended method of installation. +Yes. It's actually the recommended method of installation. You can install the `rollbar/rollbar-php-wordpress` package +using composer. == Screenshots == -1. Settings page +1. Settings page. == Changelog == @@ -110,6 +155,7 @@ Yes. It's actually the recommended method of installation. * Removed support for PHP 8.0 and below. * Updated and improved the settings page. * Updated the Rollbar core PHP SDK to v4.1. +* Updated the Rollbar core JavaScript SDK to v2.26. * Added support for telemetry and added auto-instrumentation. * Added support for `ROLLBAR_DISABLE_ADMIN` to remove the plugin settings page from the admin. * Added support for `ROLLBAR_SETTINGS` to configure the plugin without the admin page. @@ -188,7 +234,7 @@ Yes. It's actually the recommended method of installation. * Updated rollbar-php dependency to v1.5.1 = Version 2.4.0 (17th May 2018) = -* Added capture_ip, capture_email and capture_username to the config options. +* Added capture_ip, capture_email, and capture_username to the config options. * Fixed populating config options from the database to the plugin for boolean values. * Updated rollbar-php dependency to v1.5.0 @@ -307,7 +353,7 @@ Updated admin test results to show a skipped test as a success. Fixed new sessio * Updated rollbar-php dependency to v1.5.1 = Version 2.4.0 (5th April 2018) = -* Added capture_ip, capture_email and capture_username to the config options. +* Added capture_ip, capture_email, and capture_username to the config options. * Fixed populating config options from the database to the plugin for boolean values. * Updated rollbar-php dependency to v1.5.0 diff --git a/src/Admin/SettingsPage.php b/src/Admin/SettingsPage.php index 17c3810..5e57239 100644 --- a/src/Admin/SettingsPage.php +++ b/src/Admin/SettingsPage.php @@ -261,7 +261,7 @@ public function telemetrySectionHeader(): void Template::print(ROLLBAR_PLUGIN_DIR . '/templates/admin/settings-section-header.php', [ 'id' => 'rollbar_settings_telemetry_header', 'title' => 'Telemetry Settings', - 'description' => '

See the Rollbar' + 'description' => '

See the Rollbar ' . 'telemetry documentation and WordPress action reference for more details on these settings.

', ]);