README

A simple and extensible Laravel logging package for structured logging, transactions, and multiple output drivers — all with zero code changes when switching drivers.

🚀 Features

• 🔧 Multiple log levels (debug, info, warning, error)
• 🏷 Tagged log entries with custom attributes
• 📁 Supports multiple drivers:
  • CLI (console output)
  • JSON file logging (rotated daily)
  • Simple text log file
• 🔄 Transaction-based logging with start/end timestamps
• 📆 Log viewer Artisan command with filters
• ➕ Easily add custom drivers without modifying the core
• 📦 Laravel-ready with automatic service provider & facade

📦 Installation

composer require alen-dev/xpath-log

🛠 Setup

Step 1: Publish the config

php artisan vendor:publish --tag=xpath-log-config

This is the contents of the published config file:

return [
    'driver_map' => [
        'cli' => \AlenDev\XpathLog\Drivers\CliDriver::class,
        'json' => \AlenDev\XpathLog\Drivers\JsonFileDriver::class,
        'log'  => \AlenDev\XpathLog\Drivers\LogFileDriver::class,
    ],
    'external_driver_map' => [],
    'default_drivers' => explode(',', env('XPATH_LOG_DEFAULT_DRIVERS', 'cli,log')),
    'file_name' => env('XPATH_LOG_FILENAME', 'xpath'),
];

Step 2: Optional ENV config

XPATH_LOG_DEFAULT_DRIVERS="cli,log"
XPATH_LOG_FILENAME=xpathlog

🧪 Usage

Basic Logging

$xPathLog = new XpathLog();
$xPathLog
    ->use('cli')
    ->log('warning', 'message', ['test' => '34234']);

Transaction Logging

$xPathLog
    ->use('json')
    ->startTransaction('TX-789', ['customerId' => 123]);
$xPathLog
    ->use('json')
    ->endTransaction('TX-789', ['status' => 'success']);

Or log custom transaction messages:

$xPathLog
    ->use('json')
    ->transaction('abc-123', 'Applied discount', ['code' => 'SUMMER']);

🖥 Artisan Log Viewer

Optional: you can add some sample data for Artisan Log Viewer. The log viewer is designed to view JSON log created by this package.

php artisan xpathlog:create-sample

View the most recent XpathLog entries from your JSON log file (other file formats coming soon)

php artisan xpathlog:view

Filter logs

php artisan xpathlog:view --level=error
php artisan xpathlog:view --search=payment
php artisan xpathlog:view --date=2025-08-01
php artisan xpathlog:view --from="2025-08-01" --to="2025-08-02"
php artisan xpathlog:view --search=payment --from="yesterday"

🧩 Custom Drivers

You can register custom drivers externally via config:

// config/xpath-log.php
'driver_map' => [
    'slack' => App\Logging\Drivers\SlackDriver::class,
],

Each driver must implement:

interface DriverInterface {
    public function handle(LogEntry $entry): void;
}

🧩 Request Logger

This feature is disabled by default. To enable just add the following variable to your .env file:

XPATH_LOG_ENABLE_REQUEST_LOGGER=true

If enabled, by default, this will log every request on your web middleware but you can change this by adding the following line to your .env file:

XPATH_LOG_MIDDLEWARE_GROUP=api

🧪 Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Alain Traxler

License

The MIT License (MIT). Please see License File for more information.