README

Vanguard is a lightweight PHP SDK for capturing errors and exceptions in your PHP applications and sending them to the Vanguard Dashboard. It's designed to be framework-agnostic, with as little external dependencies as possibly, so it can plug into any PHP project.

Features

Captures uncaught exceptions and PHP runtime errors.
Normalize exceptions and errors into structured events.
Fingerprint events for grouping.
Logs to a local JSON file or send events to the Vanguard Dashboard API

Installation

composer require codelikesuraj/vanguard

Usage

require 'vendor/autoload.php';

use Codelikesuraj\Vanguard\Vanguard;
use Codelikesuraj\Vanguard\Transport\FileTransport;

// log to local file
$transport = new FileTransport(__DIR__ . '/VANGUARD_LOG_FILE'));

/** OR **/

// log to Vanguard dashboard
$transport = new HttpTransport("https://VANGUARD_PROJECT_DSN")


// Initialize vanguard and automatically capture errors and exceptions
Vanguard::init($transport);

// Manually capture and exception
Vanguard::capture(Throwable $e, array $context = [])
    ->transport($transport)   // optional

How it works

Vanguard::init() registers global handlers:
- Errors via set_error_handler()
- Exceptions via set_exception_handler()
Every captured error and exception is turned into an Event with:
- Context (custom metadata)
- Message
- File path
- Fingerprint (used for grouping)
- Line number
- Type (Exception, Error etc)
- Stacktrace
- Timestamp
The chosen Transport (File/Http) then decides where the event goes.

Example Event JSON

{
  "context": [],
  "fingerprint": "24bb5912458f9dd1fe4bc1843a17c2c261306fff",
  "message": "strlen(): Argument #1 ($string) must be of type string, array given",
  "file": "/var/www/index.php",
  "line": 12,
  "stacktrace": [
    {"file": "/var/www/index.php", "line": 12, "function": "strlen"}
  ],
  "timestamp": "2025-08-17T20:11:49+01:00",
  "type": "TypeError"
}

Roadmap

Basic Vanguard dashboard - provide API for logging events per project
SDK for other languages (JS, Go)
will add others as needed

codelikesuraj / vanguard-php

Maintainers

Details