README

A lightweight, zero-configuration Laravel package that automatically captures unhandled exceptions and sends them to LogPilot AI via a FastAPI microservice.

No changes to config/logging.php or your exception handler are required — install the package, set your API URL, and you're done.

Requirements

• PHP ^8.1
• Laravel 10 or 11

Installation

Install via Composer:

composer require tawfiq-alqaidy/logpilot-laravel

The service provider is auto-discovered. No manual registration is needed.

Configuration

Environment variables

Add these to your .env file:

LOGPILOT_API_URL=http://localhost:8000/api/v1/logs
LOGPILOT_SERVICE_NAME="${APP_NAME}"

Publish config (optional)

To customize the config file directly:

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

This publishes config/logpilot.php to your application.

How it works

On boot, the package:

1. Registers a custom logpilot Monolog channel.
2. Appends logpilot to Laravel's default stack channel (when LOG_CHANNEL=stack, the Laravel default).

When Laravel's exception handler logs an unhandled exception to the stack, the LogPilotHandler intercepts it and sends a fire-and-forget HTTP POST to your LogPilot API:

{
  "service_name": "my-laravel-app",
  "error_type": "RuntimeException",
  "stack_trace": "..."
}

If LogPilot is unreachable or returns an error, the failure is silently ignored — your Laravel app is never affected.

Manual logging

You can also send logs directly to the LogPilot channel:

use Illuminate\Support\Facades\Log;

Log::channel('logpilot')->error('Something went wrong', [
    'exception' => $exception,
]);

When an exception is present in the log context, the handler extracts the exception class and stack trace automatically. Otherwise, the log message is used for both fields.

Architecture

Exception Handler
       │
       ▼
  stack channel  ──►  logpilot channel  ──►  LogPilotHandler  ──►  POST /api/v1/logs

License

MIT