README

Lescopr is a zero-configuration PHP monitoring SDK that automatically captures logs, errors, and exceptions from any PHP project and streams them in real-time to the Lescopr app.

Works out of the box with Laravel, Symfony, and vanilla PHP / custom OOP projects.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Framework Integration
  • Laravel
  • Symfony
  • Vanilla PHP / POO
• Architecture
• CLI Reference
• Advanced Configuration
• Packagist
• License

Features

• ✅ Automatic error capture — hooks into set_error_handler, set_exception_handler, register_shutdown_function
• ✅ Framework auto-detection — detects Laravel, Symfony, Lumen, Slim, and vanilla PHP from composer.json
• ✅ Monolog integration — drop-in handler for Laravel and Symfony
• ✅ Background daemon — runs as a pcntl_fork process, completely non-blocking
• ✅ HTTP batch transport — logs are batched and flushed every 5 seconds via HTTPS
• ✅ Zero configuration — a single CLI command is enough to get started
• ✅ Works everywhere — Laravel, Symfony, Lumen, Slim, scripts, custom OOP

Requirements

Note: ext-pcntl is not available on Windows. On those environments the SDK operates in direct HTTP mode (no background daemon).

Installation

composer require lescopr/lescopr-php

Quick Start

Step 1 — Initialise the SDK in your project directory:

./vendor/bin/lescopr init --sdk-key YOUR_SDK_KEY

This auto-detects your framework, registers the project with the Lescopr API, writes .lescopr.json, and starts the background daemon.

Step 2 — Integrate into your application (see Framework Integration below).

That's it. All logs and exceptions are forwarded to the Lescopr app automatically.

Framework Integration

Laravel

The SDK registers automatically via Composer's package auto-discovery. No manual registration needed.

Publish the config (optional):

php artisan vendor:publish --tag=lescopr-config

Add the Lescopr channel to your logging stack in config/logging.php:

'channels' => [
    'stack' => [
        'driver'   => 'stack',
        'channels' => ['single', 'lescopr'],  // ← add 'lescopr'
    ],

    'lescopr' => [
        'driver'  => 'monolog',
        'handler' => \Lescopr\Integrations\Laravel\Logging\LescoprMonologHandler::class,
        'handler_with' => [
            'sdk' => app(\Lescopr\Core\Lescopr::class),
        ],
    ],
],

All Log::info(...), Log::error(...) etc. calls are automatically forwarded to Lescopr.

Exceptions are captured automatically via the exception handler decorator bundled with the ServiceProvider.

Environment variables (.env):

LESCOPR_SDK_KEY=lsk_xxxx
LESCOPR_API_KEY=lak_xxxx
LESCOPR_ENVIRONMENT=production

Symfony

Register the bundle in config/bundles.php:

return [
    // ... other bundles
    Lescopr\Integrations\Symfony\LescoprBundle::class => ['all' => true],
];

Wire the Monolog handler in config/packages/monolog.yaml:

monolog:
  handlers:
    lescopr:
      type:     service
      id:       Lescopr\Integrations\Symfony\LescoprMonologHandler
      channels: ['!event', '!doctrine']

Register services in config/services.yaml:

services:
  Lescopr\Core\Lescopr:
    factory: ['Lescopr\Core\Lescopr', 'fromConfig']
    public: true

  Lescopr\Integrations\Symfony\LescoprMonologHandler:
    arguments: ['@Lescopr\Core\Lescopr']

  Lescopr\Integrations\Symfony\EventSubscriber\KernelExceptionSubscriber:
    arguments: ['@Lescopr\Core\Lescopr']
    tags:
      - { name: kernel.event_subscriber }

Kernel exceptions are automatically captured via KernelExceptionSubscriber.

Vanilla PHP / POO

Add one line at the top of your entry point (index.php / bootstrap.php):

<?php
require 'vendor/autoload.php';

\Lescopr\Integrations\Vanilla\LescoprBootstrap::init();

// Your existing code continues unchanged

The bootstrap installs:

• set_error_handler — captures all PHP errors (E_WARNING, E_NOTICE, etc.)
• set_exception_handler — captures uncaught exceptions
• register_shutdown_function — captures fatal errors (E_ERROR, E_PARSE, etc.)

Manual configuration (no .lescopr.json):

\Lescopr\Integrations\Vanilla\LescoprBootstrap::init([
    'sdk_key'     => 'lsk_xxxx',
    'api_key'     => 'lak_xxxx',
    'environment' => 'production',
    'debug'       => false,
]);

Architecture

Your PHP Application
        │
        │  Log::error() / throw Exception / trigger_error()
        ▼
┌─────────────────────────────────┐
│   LescoprMonologHandler         │  (Monolog — Laravel / Symfony)
│   OR LescoprBootstrap handlers  │  (set_error_handler — Vanilla)
└──────────────┬──────────────────┘
               │ HTTP POST (batched)
               ▼
┌─────────────────────────────────┐
│      Lescopr Daemon             │  (background process, .lescopr.pid)
│  pcntl_fork → DaemonRunner      │  flushes every 5 seconds
└──────────────┬──────────────────┘
               │ HTTPS batch
               ▼
     https://api.lescopr.com
               │
               ▼
     Lescopr App
  https://app.lescopr.com

Key components:

CLI Reference

After installation, the lescopr command is available via Composer's vendor/bin:

./vendor/bin/lescopr [COMMAND] [OPTIONS]

init

./vendor/bin/lescopr init --sdk-key YOUR_SDK_KEY [--environment production] [--no-start-daemon]

• Auto-detects your project framework
• Registers the project with the Lescopr API
• Writes .lescopr.json
• Starts the background daemon (use --no-start-daemon to skip)

diagnose

./vendor/bin/lescopr diagnose --details --check-server

Prints PHP environment, configuration validity, daemon state, and optionally tests HTTPS connectivity to api.lescopr.com.

Advanced Configuration

.lescopr.json is generated automatically by lescopr init:

{
    "sdk_id": "proj_xxxx",
    "sdk_key": "lsk_xxxx",
    "api_key": "lak_xxxx",
    "environment": "development",
    "project_name": "my-app",
    "project_stack": ["laravel"]
}

Security: Add .lescopr.json to your .gitignore.

Environment variables

Packagist

The package is available on Packagist: lescopr/lescopr-php

To publish a new release, use the automated release script:

# From the sdk/php directory
./scripts/release.sh 0.2.0

This will update CHANGELOG.md, commit, tag and push — GitHub Actions will create the GitHub Release and notify Packagist automatically.

For the full publishing guide (Symfony Flex recipe, Laravel News, SemVer rules), see PUBLISHING.md.

Support

License

MIT © 2024-present SonnaLab. All rights reserved.