---
title: "WordPress plugin"
url: "https://bicho.fyi/docs/wordpress"
description: "Report PHP and browser errors from WordPress to your own Bicho instance. Configure separate channels, wp-config constants, and environment overrides."
---

[Bicho for WordPress](https://github.com/bicho-fyi/bicho-wordpress) connects your WordPress site to your own Bicho instance. PHP and browser reporting have separate switches, endpoints, and public ingest keys, so backend and frontend errors can go to different Bicho projects. Both channels are off until you enable them.

Requires WordPress 6.8+, PHP 8.2+, and the PHP cURL extension. The plugin bundles the [Bicho PHP SDK](/docs/php/) (namespace-scoped to `BichoWordPress\SDK`) and the [JavaScript SDK](/docs/javascript/). Visitors do not load reporting scripts from a CDN.

## Install

-   [Deploy Bicho and create projects](/docs/) for your PHP backend, browser frontend, or both. Use a public-key-only project (`secret: false`) for the browser channel.
-   Download [`bicho-error-tracking.zip`](https://github.com/bicho-fyi/bicho-wordpress/releases/download/v1.0.0/bicho-error-tracking.zip) from the [v1.0.0 GitHub release](https://github.com/bicho-fyi/bicho-wordpress/releases/tag/v1.0.0).
-   In WordPress admin, open Plugins > Add Plugin > Upload Plugin, upload `bicho-error-tracking.zip`, and activate Bicho.
-   Open Tools > Bicho.
-   Enter the generated `/v1/logs` endpoint and public ingest key for each channel you want to enable. PHP optionally accepts the backend ingest secret. Never enter your Bicho admin token here.
-   Enable the chosen channels and save.

Do not upload a checkout of the source repository directly to a production server; install the release `bicho-error-tracking.zip`, which contains only the bundled runtime files.

## Configuration overrides

Constants in `wp-config.php` override environment variables, which override saved dashboard settings. Overridden fields appear read-only in Tools > Bicho and show whether their value comes from a constant or an environment variable.

```
define('BICHO_PHP_ENABLED', true);
define('BICHO_PHP_ENDPOINT', 'https://your-bicho-worker.example/v1/logs');
define('BICHO_PHP_PUBLIC_KEY', 'YOUR_PHP_PUBLIC_KEY');
define('BICHO_PHP_SECRET', 'YOUR_BACKEND_INGEST_SECRET');

define('BICHO_JS_ENABLED', true);
define('BICHO_JS_ENDPOINT', 'https://your-bicho-worker.example/v1/logs');
define('BICHO_JS_PUBLIC_KEY', 'YOUR_BROWSER_PUBLIC_KEY');

define('BICHO_DEBUG', false);
define('BICHO_ENVIRONMENT', 'production');
define('BICHO_RELEASE', 'my-site@1.0.0');
```

Define constants in `wp-config.php` before WordPress loads plugins. Environment variables use the same names; boolean values accept `true`/`false`, `1`/`0`, `yes`/`no`, or `on`/`off`. An explicit `false`, `0`, or empty override still takes precedence over dashboard settings. Invalid configuration disables the affected channel rather than falling back to saved credentials.

Omit `BICHO_PHP_SECRET` when your PHP project does not require an ingest secret. On the dashboard, leaving the secret field blank keeps the saved secret; check “Clear saved secret” to remove it.

## PHP capture and limits

When enabled, PHP reporting registers an error handler and shutdown check after plugins load. It reports unsuppressed warnings, user warnings, recoverable errors, and fatal errors (`E_WARNING`, `E_USER_WARNING`, `E_RECOVERABLE_ERROR`, `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`, `E_COMPILE_ERROR`, `E_USER_ERROR`).

-   Chains any existing PHP error handler and preserves normal WordPress error handling.
-   Skips `@`\-suppressed errors, notices, deprecations, caught exceptions, and failures that happen before the plugin loads.
-   Uses synchronous delivery with a 1-second deadline per report and at most 5 reports per request.
-   Attaches `php.error_type`, `php.version`, `wordpress.version`, and `plugin.version` tags with service name `wordpress/php`.

Synchronous reporting adds up to 1 second per reported error during a failing request. Collector timeouts or failures are ignored so they do not replace your site’s own error handling.

`BICHO_DEBUG` (or the “Reporting diagnostics” checkbox) logs a fixed, credential-free message to the PHP error log when reporting cannot complete. It does not enable `WP_DEBUG` or display errors to visitors.

## Browser capture

When enabled, browser reporting enqueues the bundled `bicho.min.js` script on public frontend pages and initializes `window.Bicho.init()` with service name `wordpress/browser`.

-   Runs only on public pages, never on `wp-admin` or login screens.
-   Captures uncaught JavaScript errors and unhandled promise rejections after the script loads.
-   Serializes only the browser endpoint, browser public key, service name, environment, and release. PHP credentials and backend secrets are never included in page HTML.

## Uninstall and privacy

Uninstalling the plugin deletes the `bicho_settings` option from WordPress. It does not delete events already stored in your Bicho instance or remove constants from `wp-config.php`.

Review [WordPress privacy and credentials](/docs/privacy/#wordpress) before enabling reporting on a production site.

-   [WordPress plugin source](https://github.com/bicho-fyi/bicho-wordpress)
-   [Download bicho-error-tracking.zip (v1.0.0)](https://github.com/bicho-fyi/bicho-wordpress/releases/download/v1.0.0/bicho-error-tracking.zip)
-   [GitHub release v1.0.0](https://github.com/bicho-fyi/bicho-wordpress/releases/tag/v1.0.0)