README

LogTide PHP SDK

Official PHP SDK for LogTide with automatic batching, retry logic, circuit breaker, query API, live streaming, and middleware support.

Features

Automatic batching with configurable size and interval
Retry logic with exponential backoff
Circuit breaker pattern for fault tolerance
Max buffer size with drop policy to prevent memory leaks
Query API for searching and filtering logs
Live tail with Server-Sent Events (SSE)
Trace ID context for distributed tracing
Global metadata added to all logs
Structured error serialization
Internal metrics (logs sent, errors, latency, etc.)
Laravel, Symfony & PSR-15 middleware for auto-logging HTTP requests
Full PHP 8.1+ support with strict types and enums

Requirements

PHP 8.1 or higher
Composer

Installation

composer require logtide/sdk-php

Quick Start

use LogTide\SDK\LogTideClient;
use LogTide\SDK\Models\LogTideClientOptions;

$client = new LogTideClient(new LogTideClientOptions(
    apiUrl: 'http://localhost:8080',
    apiKey: 'lp_your_api_key_here',
));

// Send logs
$client->info('api-gateway', 'Server started', ['port' => 3000]);
$client->error('database', 'Connection failed', new PDOException('Timeout'));

// Graceful shutdown (auto-handled via register_shutdown_function)

Configuration Options

Basic Options

Option	Type	Default	Description
`apiUrl`	`string`	required	Base URL of your LogTide instance
`apiKey`	`string`	required	Project API key (starts with `lp_`)
`batchSize`	`int`	`100`	Number of logs to batch before sending
`flushInterval`	`int`	`5000`	Interval in ms to auto-flush logs

Advanced Options

Option	Type	Default	Description
`maxBufferSize`	`int`	`10000`	Max logs in buffer (prevents memory leak)
`maxRetries`	`int`	`3`	Max retry attempts on failure
`retryDelayMs`	`int`	`1000`	Initial retry delay (exponential backoff)
`circuitBreakerThreshold`	`int`	`5`	Failures before opening circuit
`circuitBreakerResetMs`	`int`	`30000`	Time before retrying after circuit opens
`enableMetrics`	`bool`	`true`	Track internal metrics
`debug`	`bool`	`false`	Enable debug logging to error_log
`globalMetadata`	`array`	`[]`	Metadata added to all logs
`autoTraceId`	`bool`	`false`	Auto-generate trace IDs for logs

Example: Full Configuration

$client = new LogTideClient(new LogTideClientOptions(
    apiUrl: 'http://localhost:8080',
    apiKey: 'lp_your_api_key_here',

    // Batching
    batchSize: 100,
    flushInterval: 5000,

    // Buffer management
    maxBufferSize: 10000,

    // Retry with exponential backoff (1s -> 2s -> 4s)
    maxRetries: 3,
    retryDelayMs: 1000,

    // Circuit breaker
    circuitBreakerThreshold: 5,
    circuitBreakerResetMs: 30000,

    // Metrics & debugging
    enableMetrics: true,
    debug: true,

    // Global context
    globalMetadata: [
        'env' => getenv('APP_ENV'),
        'version' => '1.0.0',
        'hostname' => gethostname(),
    ],

    // Auto trace IDs
    autoTraceId: false,
));

Logging Methods

Basic Logging

use LogTide\SDK\Enums\LogLevel;

$client->debug('service-name', 'Debug message');
$client->info('service-name', 'Info message', ['userId' => 123]);
$client->warn('service-name', 'Warning message');
$client->error('service-name', 'Error message', ['custom' => 'data']);
$client->critical('service-name', 'Critical message');

Error Logging with Auto-Serialization

The SDK automatically serializes Throwable objects:

try {
    throw new RuntimeException('Database timeout');
} catch (Exception $e) {
    // Automatically serializes error with stack trace
    $client->error('database', 'Query failed', $e);
}

Generated log metadata:

{
  "error": {
    "name": "RuntimeException",
    "message": "Database timeout",
    "stack": "...",
    "file": "/path/to/file.php",
    "line": 42
  }
}

Trace ID Context

Track requests across services with trace IDs.

Manual Trace ID

$client->setTraceId('request-123');

$client->info('api', 'Request received');
$client->info('database', 'Querying users');
$client->info('api', 'Response sent');

$client->setTraceId(null); // Clear context

Scoped Trace ID

$client->withTraceId('request-456', function() use ($client) {
    $client->info('api', 'Processing in context');
    $client->warn('cache', 'Cache miss');
});
// Trace ID automatically restored after closure

Auto-Generated Trace ID

$client->withNewTraceId(function() use ($client) {
    $client->info('worker', 'Background job started');
    $client->info('worker', 'Job completed');
});

Query API

Search and retrieve logs programmatically.

Basic Query

use LogTide\SDK\Models\QueryOptions;
use LogTide\SDK\Enums\LogLevel;

$result = $client->query(new QueryOptions(
    service: 'api-gateway',
    level: LogLevel::ERROR,
    from: new DateTime('-24 hours'),
    to: new DateTime(),
    limit: 100,
    offset: 0,
));

echo "Found {$result->total} logs\n";
foreach ($result->logs as $log) {
    print_r($log);
}

Full-Text Search

$result = $client->query(new QueryOptions(
    q: 'timeout',
    limit: 50,
));

Get Logs by Trace ID

$logs = $client->getByTraceId('trace-123');
echo "Trace has " . count($logs) . " logs\n";

Aggregated Statistics

use LogTide\SDK\Models\AggregatedStatsOptions;

$stats = $client->getAggregatedStats(new AggregatedStatsOptions(
    from: new DateTime('-7 days'),
    to: new DateTime(),
    interval: '1h',
));

foreach ($stats->topServices as $service) {
    echo "{$service['service']}: {$service['count']} logs\n";
}

Live Streaming (SSE)

Stream logs in real-time using Server-Sent Events.

$client->stream(
    onLog: function($log) {
        echo "[{$log['time']}] {$log['level']}: {$log['message']}\n";
    },
    onError: function($error) {
        echo "Stream error: {$error->getMessage()}\n";
    },
    filters: [
        'service' => 'api-gateway',
        'level' => 'error',
    ]
);

// Note: This blocks. Run in separate process for production.

Metrics

Track SDK performance and health.

$metrics = $client->getMetrics();

echo "Logs sent: {$metrics->logsSent}\n";
echo "Logs dropped: {$metrics->logsDropped}\n";
echo "Errors: {$metrics->errors}\n";
echo "Retries: {$metrics->retries}\n";
echo "Avg latency: {$metrics->avgLatencyMs}ms\n";
echo "Circuit breaker trips: {$metrics->circuitBreakerTrips}\n";

// Get circuit breaker state
echo $client->getCircuitBreakerState()->value; // CLOSED|OPEN|HALF_OPEN

// Reset metrics
$client->resetMetrics();

Middleware Integration

LogTide provides ready-to-use middleware for popular frameworks.

Laravel Middleware

Auto-log all HTTP requests and responses.

// app/Http/Kernel.php or bootstrap/app.php
use LogTide\SDK\Middleware\LaravelMiddleware;

$middleware->append(LaravelMiddleware::class);

// Service Provider
use LogTide\SDK\LogTideClient;
use LogTide\SDK\Models\LogTideClientOptions;

$this->app->singleton(LogTideClient::class, function() {
    return new LogTideClient(new LogTideClientOptions(
        apiUrl: env('LOGTIDE_API_URL'),
        apiKey: env('LOGTIDE_API_KEY'),
    ));
});

Logged automatically:

Request: POST /api/users
Response: POST /api/users 201 (45ms)
Errors: Request error: Internal Server Error

Symfony Event Subscriber

# config/services.yaml
services:
    LogTide\SDK\Middleware\SymfonySubscriber:
        arguments:
            $client: '@LogTide\SDK\LogTideClient'
            $serviceName: '%env(APP_NAME)%'
        tags:
            - { name: kernel.event_subscriber }

PSR-15 Middleware

Compatible with Slim, Mezzio, and other PSR-15 frameworks.

use LogTide\SDK\Middleware\Psr15Middleware;

$app->add(new Psr15Middleware(
    client: $client,
    serviceName: 'slim-api',
));

Examples

See the examples/ directory for complete working examples:

basic.php - Simple usage
advanced.php - All advanced features
laravel.php - Laravel integration
symfony.php - Symfony integration

Best Practices

1. Flush on Shutdown

// Automatic cleanup via register_shutdown_function
// Or manually call:
$client->close();

2. Use Global Metadata

$client = new LogTideClient(new LogTideClientOptions(
    apiUrl: 'http://localhost:8080',
    apiKey: 'lp_your_api_key_here',
    globalMetadata: [
        'env' => getenv('APP_ENV'),
        'version' => '1.0.0',
        'region' => 'us-east-1',
    ],
));

3. Enable Debug Mode in Development

$client = new LogTideClient(new LogTideClientOptions(
    apiUrl: 'http://localhost:8080',
    apiKey: 'lp_your_api_key_here',
    debug: getenv('APP_ENV') === 'development',
));

Testing

Run the test suite:

# Install dependencies
composer install

# Run tests
composer test

# Run with coverage
composer test:coverage

# Run PHPStan
composer phpstan

# Code style check
composer cs

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

logtide / sdk-php

Maintainers

Details