PHP SDK

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:

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 or the 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 and the OTLP guide for collector behavior.

• PHP SDK source and full reference
• PHP package on Packagist