---
title: "PHP SDK"
url: "https://bicho.fyi/docs/php"
description: "Install the Bicho PHP SDK with Composer to report exceptions and error messages. Configure backend credentials, synchronous delivery, filtering, and retries."
---

The `bicho-fyi/php` package reports PHP exceptions and error messages over OTLP/HTTP JSON. It requires PHP 8.2+ with the cURL and JSON extensions, and has no third-party runtime packages.

## Install and configure

```
composer require bicho-fyi/php
```

Load Composer’s autoloader in your application bootstrap. Use `otlp.endpoint` and `otlp.headers['X-Bicho-Key']` from [project registration](/docs/):

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

use Bicho\Client;
use Bicho\Config;

$tracker = new Client(new Config(
    endpoint: 'https://your-bicho-worker.example/v1/logs',
    key: 'YOUR_PUBLIC_KEY',
    serviceName: 'my-app/php',
    environment: 'production',
    release: 'my-app@1.0.0',
));
```

For a secret-enabled backend project, also pass `secret: 'YOUR_INGEST_SECRET'` using the generated `X-Bicho-Secret` value from secure application configuration. Never use the admin token for capture.

The endpoint must end at the exact `/v1/logs` path. HTTPS is required except on loopback for local testing; URL credentials, query strings, fragments, and redirects are not supported.

## Capture explicitly

```
try {
    $tracker->captureMessage('Bicho setup check');
} catch (\Bicho\DeliveryException $delivery) {
    error_log($delivery->getMessage());
}
```

Use `captureException($error)` with a `Throwable` from your application’s existing error handler. Both capture methods accept optional `tags` and `contexts` arrays. Handle delivery failures separately so they do not replace the application’s original exception.

Capture is manual. The SDK does not install global exception, error, or shutdown handlers, framework integrations, or WordPress hooks. Exception capture includes the class, message, failure and trace locations, and up to eight previous exception messages. It omits function arguments and object values from stack frames. It does not automatically collect requests, headers, cookies, sessions, user identities, or environment variables.

## Delivery and retries

Sending is synchronous: a capture call blocks until it receives a valid acknowledgment or throws. There is no queue or flush method. Reporting during a web request adds latency. The overall deadline defaults to 15 seconds; the optional `timeout` configuration accepts a positive value up to 60 seconds. Each attempt is limited to five seconds or the remaining deadline.

Network failures and HTTP 429/502/503/504 responses allow at most two retries, preserving the same payload and occurrence UID. The SDK respects `Retry-After` within its deadline. Redirects, invalid acknowledgments, and populated OTLP partial-success responses are terminal failures.

For an explicit retry after ambiguous delivery, create an immutable `Bicho\Event` and reuse it with `$tracker->send($event)`. Calling a capture method again creates a new occurrence. A returned UID confirms a valid acknowledgment, but is not the server’s stored event lookup ID. Read the event through [MCP](/docs/mcp/) or the [API](/docs/api/) to check the captured evidence.

## Limits and privacy

Events are limited to 60 KiB serialized. Messages and stack text stop at 16 KiB; contexts are bounded by depth, entry count, and string size. Tags cannot override protocol-owned attributes. Credential-like keys and common credential strings are filtered before sending, but arbitrary messages and paths can still contain private data.

There is no persistent offline queue, delivery guarantee, automatic fatal-error reporting, tracing, metrics, replay, or source-map upload. See [privacy](/docs/privacy/) and the [OTLP guide](/docs/otlp/) for collector behavior.

-   [PHP SDK source and full reference](https://github.com/bicho-fyi/bicho-php)
-   [PHP package on Packagist](https://packagist.org/packages/bicho-fyi/php)