README

Official Bugwatch error-monitoring SDK for PHP 8.1+. Capture exceptions and messages from PHP applications and send them to your Bugwatch project.

Requirements

PHP 8.1 or later
Composer 2
PHP extensions: curl and json
A Bugwatch project DSN, available from the project's Get started page

Check the required PHP extensions:

php -m | grep -E 'curl|json'

Installation

Install the SDK from Packagist in the root of your PHP project:

composer require roomylabs/bugwatch-php

Composer installs the package and updates composer.json and composer.lock. Load Composer's generated autoloader once in your application entry point:

<?php

require __DIR__ . '/vendor/autoload.php';

If your entry point is inside a public directory, adjust the relative path, for example require dirname(__DIR__) . '/vendor/autoload.php';.

Quick start

Initialize Bugwatch as early as possible with the DSN copied from your project:

<?php

require __DIR__ . '/vendor/autoload.php';

Bugwatch::init(
    'https://bw-your_project_key@bugwatch-api.loadmindx.com/api/your_project_id'
);

try {
    risky_operation();
} catch (Throwable $exception) {
    Bugwatch::captureException($exception);
    throw $exception; // Keep your application's normal error flow.
}

For command-line scripts and short-lived workers, flush pending events before exit:

Bugwatch::flush();

Long-running web requests are flushed automatically during PHP shutdown.

Capture messages

Bugwatch::captureMessage('Payment gateway timed out', 'warning');

Supported levels include debug, info, warning, error, and fatal.

Add diagnostic context

Breadcrumbs

Breadcrumbs describe the actions that happened before an error:

Bugwatch::addBreadcrumb('checkout', 'Customer submitted the payment form');
Bugwatch::addBreadcrumb('database', 'Loading active subscription');

The SDK retains the latest 100 breadcrumbs.

User context

Bugwatch::setUser(42, 'alice@example.com');

The email local part is masked before transmission (alice@example.com becomes a****@example.com).

Framework integration

Initialize the SDK from the earliest shared bootstrap file in your framework:

Laravel: bootstrap/app.php or a service provider's register() method
Symfony: public/index.php or a kernel bootstrap file
WordPress: a must-use plugin or the active plugin's bootstrap file
Plain PHP: the front controller, commonly public/index.php

Example for an environment-based DSN:

<?php

require dirname(__DIR__) . '/vendor/autoload.php';

$dsn = getenv('BUGWATCH_DSN');

if (is_string($dsn) && $dsn !== '') {
    Bugwatch::init($dsn);
}

Store BUGWATCH_DSN in your deployment environment; do not commit a real DSN to a public repository.

Local development over HTTP

Bugwatch requires HTTPS DSNs by default. For a local Bugwatch server only, set:

export BUGWATCH_ALLOW_HTTP=1

Do not enable this option in production.

Runtime behaviour

Non-blocking: events are queued on a cURL multi handle.
Shutdown flush: pending events are flushed automatically at PHP shutdown.
Failure-safe: network failures never throw into the host application.
Safe before initialization: capture calls are silent no-ops until init().
HTTPS by default: plain HTTP DSNs are rejected unless explicitly allowed.
PII masking: email addresses passed through setUser() are masked.

API reference

Method	Description
`Bugwatch::init(string $dsn): void`	Configure the SDK with a project DSN
`Bugwatch::captureException(Throwable $exception): ?string`	Queue an exception and return its event ID
`Bugwatch::captureMessage(string $message, string $level = 'error'): ?string`	Queue a message
`Bugwatch::addBreadcrumb(string $category, string $message): void`	Add diagnostic history
`Bugwatch::setUser(?int $id, ?string $email = null): void`	Attach masked user context
`Bugwatch::setTag(string $key, string $value): void`	Attach a searchable tag
`Bugwatch::flush(): bool`	Wait for pending requests to finish

Updating

Update within the currently allowed version constraint:

composer update roomylabs/bugwatch-php

Inspect the installed version:

composer show roomylabs/bugwatch-php

Troubleshooting

Composer cannot find the package

Ensure Packagist is enabled and clear stale Composer metadata:

composer clear-cache
composer require roomylabs/bugwatch-php

`Class "Bugwatch" not found`

Ensure your application loads Composer's autoloader before calling the SDK:

require __DIR__ . '/vendor/autoload.php';

Events do not arrive from a CLI script

Call Bugwatch::flush() before the process exits and confirm the DSN belongs to the selected Bugwatch project.

Development

Clone the repository and run the syntax checks:

git clone https://github.com/ycodexme/bugwatch-php.git
cd bugwatch-php
php -l Bugwatch.php
php -l BugwatchTest.php

Support

Documentation: https://bugwatch.roomylabs.com/docs/php/
Issues: https://github.com/ycodexme/bugwatch-php/issues
Package: https://packagist.org/packages/roomylabs/bugwatch-php

License

MIT — see LICENSE.

roomylabs / bugwatch-php

Package info

Security

Statistics