PHP SDK

Installation

Install via Composer:

composer require cronbeats/cronbeats-php

Requirements: PHP 7.4 or higher

Quick Start

Send a simple ping to mark your cron job as successful:

<?php

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

use CronBeats\PingSdk\PingClient;

$client = new PingClient('YCrXzYbV');
$client->ping();

// Done! CronBeats knows your job ran successfully.

Sending Pings

Simple Ping

Send a single heartbeat when your job completes:

<?php

$client = new PingClient('YCrXzYbV');
$client->ping();

Start & End Signals

Track execution time by signaling when your job starts and ends:

<?php

$client = new PingClient('YCrXzYbV');

$client->start();
// ... do your work ...
$client->success();  // or $client->fail() on error

Real-World Cron Job Example

Complete example with error handling:

<?php

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

use CronBeats\PingSdk\PingClient;

$client = new PingClient('YCrXzYbV');
$client->start();

try {
    // Your actual cron job work
    processEmails();
    generateReports();
    cleanupTempFiles();
    
    $client->success();
} catch (Exception $e) {
    $client->fail();
    error_log($e->getMessage());
    exit(1);
}

Progress Tracking

Send real-time progress updates from long-running jobs. CronBeats displays a live progress bar and status message on your dashboard.

📊 Two Progress Modes

Mode 1: With Percentage — $client->progress(50, "message")

Dashboard shows progress bar (0-100%) + your message. Use when you can calculate meaningful progress.

Mode 2: Message Only — $client->progress(null, "message")

Dashboard shows only your status message (no percentage bar). Use for status updates without measurable progress.

Basic Progress Update

<?php

// Send progress percentage (0-100) with status message
$client->progress(50, 'Processing batch 50/100');

// Using array syntax
$client->progress([
    'seq' => 75,
    'message' => 'Almost done'
]);

Database Backup Example

Real-world example with multiple progress checkpoints:

<?php

$client = new PingClient('YCrXzYbV');
$client->start();

try {
    $client->progress(10, 'Starting backup...');
    
    // Dump database
    exec('mysqldump -u user -p password mydb > backup.sql');
    $client->progress(40, 'Database dumped');
    
    // Compress
    exec('gzip backup.sql');
    $client->progress(70, 'Compression complete');
    
    // Upload to S3
    exec('aws s3 cp backup.sql.gz s3://my-bucket/');
    $client->progress(90, 'Uploaded to S3');
    
    $client->progress(100, 'Backup complete');
    $client->success();
    
} catch (Exception $e) {
    $client->fail();
    throw $e;
}

Error Handling

The SDK throws typed exceptions for validation and API errors:

<?php

use CronBeats\PingSdk\PingClient;
use CronBeats\PingSdk\Exception\ApiException;
use CronBeats\PingSdk\Exception\ValidationException;

$client = new PingClient('YCrXzYbV');

try {
    $client->ping();
    
} catch (ValidationException $e) {
    // Invalid job key format or parameters (client-side)
    error_log('Validation error: ' . $e->getMessage());
    
} catch (ApiException $e) {
    // API/network issue with normalized metadata
    $code = $e->getErrorCode();    // e.g. 'RATE_LIMITED'
    $status = $e->getHttpStatus();  // e.g. 429
    $retryable = $e->isRetryable(); // bool
    
    error_log("API error: {$code} (HTTP {$status})");
}

API Reference

Method	Description
`ping()`	Send a simple heartbeat ping
`start()`	Signal job start and begin execution timer
`end($status)`	Signal job end with status ('success' or 'fail')
`success()`	Alias for end('success')
`fail()`	Alias for end('fail')
`progress($seq, $msg)`	Send progress update (0-100) with status message

For complete API documentation, see the GitHub repository.

Configuration Options

Customize the client behavior:

<?php

$client = new PingClient('YCrXzYbV', [
    'baseUrl' => 'https://cronbeats.io',  // Default
    'timeoutMs' => 5000,                    // Default: 5 seconds
    'maxRetries' => 2,                      // Default: 2 retries
]);

Note: The default 5-second timeout ensures the SDK never blocks your cron job if CronBeats is unreachable. Adjust only if you need longer waits.

Complete Examples

Processing Records with Progress

<?php

require __DIR__ . '/vendor/autoload.php';
use CronBeats\PingSdk\PingClient;

$client = new PingClient('YCrXzYbV');
$client->start();

$total = 10000;
for ($i = 1; $i <= $total; $i++) {
    // Process record
    processRecord($i);
    
    // Update progress every 500 records
    if ($i % 500 === 0) {
        $percent = (int)($i * 100 / $total);
        $client->progress($percent, "Processed $i / $total records");
    }
}

$client->progress(100, 'All records processed');
$client->success();

Framework Integration

Laravel

Use in Laravel scheduled tasks:

<?php
// app/Console/Commands/BackupDatabase.php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use CronBeats\PingSdk\PingClient;

class BackupDatabase extends Command
{
    protected $signature = 'backup:database';
    
    public function handle()
    {
        $client = new PingClient(env('CRONBEATS_JOB_KEY'));
        $client->start();
        
        try {
            $this->info('Starting backup...');
            // Your backup logic
            $client->success();
        } catch (\Exception $e) {
            $client->fail();
            $this->error($e->getMessage());
            return 1;
        }
        
        return 0;
    }
}

Plain PHP Script

Use in standalone PHP scripts or vanilla PHP cron jobs:

<?php
// /path/to/your/cron-script.php

require __DIR__ . '/vendor/autoload.php';
use CronBeats\PingSdk\PingClient;

$client = new PingClient('YCrXzYbV');
$client->start();

// Your cron job logic here
$result = doSomeWork();

if ($result) {
    $client->success();
} else {
    $client->fail();
}