README

Official PHP SDK for Logdash.io - Zero-configuration observability platform designed for developers working on side projects and prototypes.

Why Logdash?

Most observability solutions feel overwhelming for small projects and prototypes. Logdash provides instant logging and real-time metrics without complex configurations. Just add the SDK and start monitoring your application immediately.

Key Features

🚀 Zero Configuration: Start logging and tracking metrics in seconds
📊 Real-time Dashboard: Cloud-hosted interface with live data updates
📝 Structured Logging: Multiple log levels with rich context support
📈 Custom Metrics: Track counters, gauges, and business metrics effortlessly
⚡ Asynchronous: Non-blocking operations with automatic resource management
🛡️ Production Ready: Built with enterprise-grade patterns and error handling
🔧 Framework Agnostic: Works with Laravel, Symfony, or standalone PHP apps
🐘 PHP 8.1+ Compatible: Supports PHP 8.1, 8.2, 8.3, and all newer versions

Pre-requisites

Setup your free project in less than 2 minutes at logdash.io

Installation

Composer

composer require logdash/php-sdk

Quick Start

Basic Logging (Local Only)

<?php

require_once 'vendor/autoload.php';

use Logdash\Logdash;

// Create Logdash instance without API key for local logging only
$logdash = Logdash::create();
$logger = $logdash->logger();

// Log different levels
$logger->error('This is an error message');
$logger->warn('This is a warning message');
$logger->info('This is an info message');
$logger->debug('This is a debug message');

Cloud Logging & Metrics

<?php

require_once 'vendor/autoload.php';

use Logdash\Logdash;

// Create Logdash instance with API key for cloud sync
$logdash = Logdash::create([
    'apiKey' => 'your-api-key-here',
    'host' => 'https://api.logdash.io', // Optional, defaults to this
    'verbose' => true // Optional, for debugging
]);

$logger = $logdash->logger();
$metrics = $logdash->metrics();

// Logging with cloud sync
$logger->error('Application error occurred');
$logger->info('User logged in successfully');

// Custom metrics
$metrics->set('active_users', 150);
$metrics->mutate('login_count', 1); // Increment by 1
$metrics->mutate('error_count', -1); // Decrement by 1

Apps

A domain has one API key, the domain key, shared by all apps of that domain, for example a desktop app, an API and a landing page. Set app to name this one, so the dashboard can filter logs and metrics by app:

$logdash = Logdash::create([
    'apiKey' => 'your-domain-key',
    'app' => 'api'
]);

Every log, metric and event sent by this instance carries the app. Older service keys ignore app.

Framework Integration

Laravel

// In your AppServiceProvider or custom service provider
use Logdash\Logdash;

public function register()
{
    $this->app->singleton('logdash', function ($app) {
        return Logdash::create([
            'apiKey' => config('services.logdash.api_key'),
            'verbose' => config('app.debug')
        ]);
    });
}

// Usage in controllers/services
public function someMethod()
{
    $logdash = app('logdash');
    $logdash->logger()->info('Operation completed');
    $logdash->metrics()->set('operation_count', 42);
}

Symfony

// In your services.yaml
services:
    logdash:
        class: Logdash\Logdash
        factory: ['Logdash\Logdash', 'create']
        arguments:
            - apiKey: '%env(LOGDASH_API_KEY)%'
              verbose: '%kernel.debug%'

// Usage in controllers/services
public function someAction(Logdash $logdash)
{
    $logdash->logger()->info('Action executed');
    $logdash->metrics()->mutate('action_count', 1);
}

API Reference

Logdash

`Logdash::create(array $params = []): Logdash`

Creates a new Logdash instance.

Parameters:

apiKey (string, optional): Your Logdash API key. If not provided, logs and events are only printed locally
host (string, optional): Logdash API host. Defaults to https://api.logdash.io
verbose (bool, optional): Enable verbose internal logging. Defaults to false
app (string, optional): Name of this app within its domain, sent with every log, metric and event. See Apps
httpClient (GuzzleHttp\ClientInterface, optional): Client that sends the requests to the API, such as one with a proxy. Defaults to a client with a 5 second timeout

`flush(): void`

Sends the logs, metrics and events buffered so far, and waits for the API.

Logdash buffers them and sends them together, so that a log costs no HTTP request of its own. It sends them when 100 are buffered, when the logs near the API's 2 MB request limit, when one comes a second or more after the last send, and when the PHP request or script ends. Call flush() where the process lives on, such as in a queue worker after each job:

$logdash->logger()->info('Job done');
$logdash->flush();

Logger

The logger provides methods for different log levels:

error(...$data): Log error level messages
warn(...$data): Log warning level messages
info(...$data): Log info level messages
log(...$data): Alias for info level
http(...$data): Log HTTP-related messages
verbose(...$data): Log verbose messages
debug(...$data): Log debug messages
silly(...$data): Log silly level messages

Metrics

`set(string $name, float $value): void`

Set a metric to a specific value.

$metrics->set('cpu_usage', 45.2);
$metrics->set('memory_usage', 1024);

`mutate(string $name, float $value): void`

Change a metric by the specified amount (can be positive or negative).

$metrics->mutate('request_count', 1);    // Increment
$metrics->mutate('error_count', -1);     // Decrement
$metrics->mutate('temperature', 2.5);    // Increase by 2.5

Events

`track(string $name, array $props = [], string|int|null $userId = null): void`

Track an event, such as an agent run or a signup.

$logdash->track('agent_run', [
    'agent' => 'support',
    'steps' => 4,
    'success' => true,
], $user->id);

Events show up in the domain's Analytics as goals, with a daily trend. Pass the user ID for signed-in users, so one person counts once across the website and apps. Without it, Logdash counts a visitor of that app that changes every day. Never put personal data in props.

Parameters:

name (string): The event name, matching [a-z][a-z0-9_]{0,63}, except pageview, pageleave and browser_error, which belong to the website tracker. An invalid name drops the event with a warning
props (array, optional): Up to 10 properties with string, number or boolean values
userId (string|int, optional): The signed-in user's internal ID, never an email address. An ID that contains @ drops the event with a warning

Log Levels

The SDK supports the following log levels (in order of severity):

ERROR: Error conditions
WARN: Warning conditions
INFO: Informational messages
HTTP: HTTP request/response logs
VERBOSE: Verbose informational messages
DEBUG: Debug-level messages
SILLY: Very detailed debug information

Configuration

Environment Variables

You can use environment variables for configuration:

LOGDASH_API_KEY=your-api-key-here
LOGDASH_HOST=https://api.logdash.io
LOGDASH_VERBOSE=true

$logdash = Logdash::create([
    'apiKey' => $_ENV['LOGDASH_API_KEY'] ?? '',
    'host' => $_ENV['LOGDASH_HOST'] ?? 'https://api.logdash.io',
    'verbose' => filter_var($_ENV['LOGDASH_VERBOSE'] ?? false, FILTER_VALIDATE_BOOLEAN)
]);

Error Handling

The SDK is designed to be non-blocking and fail silently in production. If there are issues with the API connection:

Local logging will continue to work
API errors are logged internally when verbose mode is enabled
Your application will not be affected by Logdash connectivity issues

Requirements

PHP 8.1 or higher
Guzzle HTTP client (automatically installed via Composer)

Development

# Install dependencies
composer install

# Run tests
composer test

# Run static analysis
composer phpstan

# Check code style
composer cs

# Fix code style
composer cbf

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

📧 Email: support@logdash.io
🌐 Website: logdash.io
📚 Documentation: docs.logdash.io
🐛 Issues: GitHub Issues

logdash / php-sdk

Package info

Security

Statistics