PHPackages                             bluecapapps/downctl-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. bluecapapps/downctl-php

ActiveLibrary[Logging & Monitoring](/categories/logging)

bluecapapps/downctl-php
=======================

PHP SDK for the Downctl error and metrics reporting API.

v1.1.0(1mo ago)071MITPHPPHP ^8.2

Since May 19Pushed 1mo agoCompare

[ Source](https://github.com/bluecapapps/downctl-php)[ Packagist](https://packagist.org/packages/bluecapapps/downctl-php)[ RSS](/packages/bluecapapps-downctl-php/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (4)Versions (3)Used By (1)

bluecapapps/downctl-php
=======================

[](#bluecapappsdownctl-php)

PHP SDK for reporting errors and server metrics to Downctl. Zero external dependencies - uses PHP's built-in `curl` extension.

Requirements
------------

[](#requirements)

- PHP 8.2+
- `curl` extension (enabled by default in most PHP distributions)

Installation
------------

[](#installation)

```
composer require bluecapapps/downctl-php
```

Configuration
-------------

[](#configuration)

The client is configured via a `Config` object. You can build it from environment variables or construct it directly.

### From environment variables (recommended)

[](#from-environment-variables-recommended)

Set these in your server environment or `.env` file:

```
DOWNCTL_API_KEY=your-secret-api-key
DOWNCTL_PUBLIC_KEY=your-public-key   # optional, for frontend reporting
```

Then instantiate the client:

```
use Bluecapapps\Downctl\Client;
use Bluecapapps\Downctl\Config;

$client = new Client(Config::fromEnv());
```

### Direct construction

[](#direct-construction)

```
use Bluecapapps\Downctl\Client;
use Bluecapapps\Downctl\Config;

$client = new Client(new Config(
    apiKey: 'your-secret-api-key',
));
```

### All config options

[](#all-config-options)

OptionTypeDefaultDescription`apiKey``string`-**Required.** Server-side API key (keep secret)`publicKey``?string``null`Public key for frontend use (safe to expose)`timeoutSeconds``int``5`HTTP request timeout`silent``bool``true`Swallow transport errors - see [Silent mode](#silent-mode)All SDK requests are sent to `https://downctl.com`.

Usage
-----

[](#usage)

### Capture an exception

[](#capture-an-exception)

The most common use case. Extracts the message, stack trace, and current request URL automatically. Query strings are stripped from captured URLs before sending, so request secrets such as tokens, codes, and signed URL parameters are not included in SDK payloads.

```
try {
    riskyOperation();
} catch (\Throwable $e) {
    $client->captureException($e);
}
```

Capture with a custom severity level and additional context:

```
$client->captureException($e, level: 'warning', context: [
    'user_id' => $userId,
    'order_id' => $orderId,
]);
```

### Report a message

[](#report-a-message)

Send a plain message without an exception object:

```
$client->report('Payment gateway timed out', level: 'error');
```

Include a manually built stack trace, URL, or context:

```
$client->report(
    message: 'Slow database query detected',
    level: 'warning',
    stackTrace: debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS),
    url: 'https://yourapp.com/checkout',
    context: ['query_time_ms' => 4200],
);
```

Manually provided URLs are also sent without their query string. Context values are sent as provided by the base PHP SDK; integrations such as `bluecapapps/downctl-laravel` may add framework-specific context redaction before calling this client.

Valid levels: `error`, `warning`, `info`.

### Report server metrics

[](#report-server-metrics)

For applications that run alongside the Go agent and want to report metrics directly from PHP:

```
use Bluecapapps\Downctl\Payload\MetricsPayload;

$metrics = new MetricsPayload(
    cpuPercent: 42.5,
    memoryPercent: 61.0,
    memoryTotalMb: 8192,
    memoryUsedMb: 5000,
    diskPercent: 38.0,
    diskTotalGb: 100,
    diskUsedGb: 38,
    loadAvg1m: 1.2,   // optional
    loadAvg5m: 0.9,   // optional
    loadAvg15m: 0.8,  // optional
);

$client->reportMetrics($metrics);
```

### Verify connectivity

[](#verify-connectivity)

Returns `true` if the Downctl API is reachable, `false` otherwise. Safe to call during a startup health check.

```
if (! $client->ping()) {
    error_log('Downctl API is unreachable');
}
```

Cron Monitoring
---------------

[](#cron-monitoring)

Cron monitoring lets Downctl alert you when a scheduled PHP script misses its expected window, runs too long, or exits with an error. Each monitor has a unique ping token; your script hits that URL to prove it ran.

### 1. Create a monitor in Downctl

[](#1-create-a-monitor-in-downctl)

Open your site in Downctl, navigate to **Cron monitors**, and add a monitor. Set the schedule (cron expression or a simple minute frequency) and a grace period. Copy the ping token shown on the monitor card.

### 2. Add pings to your script

[](#2-add-pings-to-your-script)

For simple scripts that just need a heartbeat:

```