PHPackages                             marin-solutions/checkybot-laravel - 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. marin-solutions/checkybot-laravel

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

marin-solutions/checkybot-laravel
=================================

Laravel package for CheckyBot monitoring integration

v0.2.1(2w ago)06.2k[3 PRs](https://github.com/Marin-Solutions/checkybot-laravel/pulls)MITPHPPHP ^8.2CI passing

Since Dec 1Pushed 1w agoCompare

[ Source](https://github.com/Marin-Solutions/checkybot-laravel)[ Packagist](https://packagist.org/packages/marin-solutions/checkybot-laravel)[ Docs](https://github.com/Marin-Solutions/checkybot-laravel)[ GitHub Sponsors]()[ RSS](/packages/marin-solutions-checkybot-laravel/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (26)Versions (11)Used By (0)

Checkybot Laravel
=================

[](#checkybot-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/3d5f62dc62d8f94ca840fb46d2880c5cbf22e225f5fed4f1e529518bea4f3784/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6172696e2d736f6c7574696f6e732f636865636b79626f742d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/marin-solutions/checkybot-laravel)[![GitHub Tests Action Status](https://camo.githubusercontent.com/6e544940eed9177ad09215f6f10412e6c5685b8e1cba0ab80261c9eff308f0cd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f4d6172696e2d536f6c7574696f6e732f636865636b79626f742d6c61726176656c2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/Marin-Solutions/checkybot-laravel/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/756ba0f29b090e2f466da83f334ed574eae179ce832588c9cd5753e39d515974/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6172696e2d736f6c7574696f6e732f636865636b79626f742d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/marin-solutions/checkybot-laravel)

A Laravel package for defining and syncing monitoring checks to your Checkybot instance. Define uptime, SSL certificate, and API endpoint monitors using a beautiful fluent API inspired by Pest, and sync them with a single command.

Quick Start
-----------

[](#quick-start)

Get up and running in under 2 minutes:

```
# 1. Install the package
composer require marin-solutions/checkybot-laravel

# 2. Publish the routes file
php artisan vendor:publish --tag="checkybot-routes"

# 3. Publish the config (for API credentials)
php artisan vendor:publish --tag="checkybot-laravel-config"

# 4. Add credentials to .env
echo "CHECKYBOT_API_KEY=your-api-key" >> .env
echo "CHECKYBOT_PROJECT_ID=1" >> .env

# 5. Define your checks in routes/checkybot.php (see examples below)

# 6. Preview your checks
php artisan checkybot:sync --dry-run

# 7. Sync to Checkybot
php artisan checkybot:sync
```

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

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require marin-solutions/checkybot-laravel
```

### Step 2: Publish Routes File

[](#step-2-publish-routes-file)

```
php artisan vendor:publish --tag="checkybot-routes"
```

This creates `routes/checkybot.php` where you'll define your monitoring checks using the fluent API.

### Step 3: Publish Configuration

[](#step-3-publish-configuration)

```
php artisan vendor:publish --tag="checkybot-laravel-config"
```

### Step 4: Set Environment Variables

[](#step-4-set-environment-variables)

Add to your `.env` file:

```
CHECKYBOT_API_KEY=your-api-key
CHECKYBOT_PROJECT_ID=1
CHECKYBOT_URL=https://checkybot.com
```

VariableDescription`CHECKYBOT_API_KEY`Your Checkybot API key (found in account settings)`CHECKYBOT_PROJECT_ID`The project ID to sync checks to`CHECKYBOT_URL`Checkybot instance URL (default: `https://checkybot.com`)### Step 5: Verify Installation

[](#step-5-verify-installation)

```
php artisan checkybot:sync --dry-run
```

Runtime Component Status Reporting (v0.2.1)
-------------------------------------------

[](#runtime-component-status-reporting-v021)

Install the supported client with:

```
composer require marin-solutions/checkybot-laravel:^0.2.1
```

After a component has been declared and synced, report its runtime status through the configured `CheckybotClient`:

```
use DateTimeImmutable;
use DateTimeZone;
use MarinSolutions\CheckybotLaravel\Http\CheckybotClient;

/** @var CheckybotClient $checkybot */
$checkybot = app(CheckybotClient::class);

$checkybot->reportComponentStatus(
    componentKey: 'serp-data-lake',
    status: 'warning', // healthy, warning, or failure
    observedAt: new DateTimeImmutable('now', new DateTimeZone('UTC')),
    message: 'Refresh backlog is above the warning threshold.',
    metrics: [
        'due' => 12,
        'coverage_percent' => 98.5,
    ],
);
```

This method calls `POST /api/v1/projects/{projectId}/components/{componentKey}/status` with the configured base URL, project ID, timeout, Bearer API key, and retry settings. The Checkybot application must support this endpoint before consumers upgrade.

Each call sends an `Idempotency-Key` header. The package generates a stable key for the call and reuses it across configured retries; pass an optional 64-character hexadecimal key as the sixth argument when a caller must safely retry the same operation after an unknown network outcome.

The authenticated JSON body contains only:

```
{
  "status": "healthy|warning|failure",
  "observed_at": "2026-07-31T12:34:56+00:00",
  "message": "A short safe status message.",
  "metrics": {"due": 12}
}
```

`observed_at` is normalized to RFC3339 UTC. Component keys must be 1–64 characters matching `[A-Za-z0-9][A-Za-z0-9._-]*`. Messages are limited to 500 bytes and cannot contain control characters. Metrics are limited to 20 values, must use the allowlisted keys `active`, `configured_pairs`, `count`, `coverage_percent`, `due`, `duration_ms`, `error_count`, `failed`, `failure_count`, `failure_streak`, `healthy`, `latency_ms`, `missing_pairs`, `oldest_overdue_age_minutes`, `overdue`, `stale_claims`, `success_count`, `total`, `unique_keywords`, or `warning`, and each value must be a non-negative integer, finite number, or boolean no greater than 1,000,000,000.

The server maps `failure` to Checkybot's `danger` state and persists the observation against the already-declared component. Declaration sync remains separate and continues to reject runtime status, message, timestamp, and metric fields.

The server allows observed timestamps up to 120 seconds ahead of its clock to tolerate normal clock skew; larger future timestamps are rejected. Deploy the compatible Checkybot application endpoint and migration first (server hardening commit `1e43daf3334cef0e49dd409b317a650bb74d9984`), then change the consumer requirement to `^0.2.1`. Do not add status fields to `php artisan checkybot:sync`; call `reportComponentStatus` separately from application runtime code.

Defining Checks (Fluent API)
----------------------------

[](#defining-checks-fluent-api)

Define your checks in `routes/checkybot.php` using the expressive fluent API:

```