Monolog Extra Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/package-name

Publish the configuration file to customize default settings:

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider" --tag="config"

The package introduces a LoggerExtra facade for logging with customizable extra fields. Initialize it in your config/package-name.php:

'extra_fields' => [
    'user_id' => auth()->id(),
    'request_id' => request()->header('X-Request-ID'),
],

First use case: Log structured data with extra fields in a controller:

use Vendor\PackageName\Facades\LoggerExtra;

public function store(Request $request) {
    LoggerExtra::info("Resource created", [
        'data' => $request->validated(),
    ]);
}

Implementation Patterns

1. Global Extra Fields

Configure reusable fields in config/package-name.php under extra_fields. These are automatically appended to all log entries via LoggerExtra:

'extra_fields' => [
    'environment' => app()->environment(),
    'ip_address' => request()->ip(),
],

2. Dynamic Extra Fields

Override global fields per log entry:

LoggerExtra::warning("Failed payment", [
    'extra' => ['payment_id' => $payment->id], // Merges with global fields
]);

3. Integration with Laravel Logging

Use the package alongside Laravel’s built-in logger (e.g., Monolog). The LoggerExtra facade extends the default logger:

// Fallback to default logger if needed
\Log::error("Critical error", ['context' => 'fallback']);

4. Middleware for Automatic Fields

Add a middleware to inject dynamic fields (e.g., auth user) globally:

namespace App\Http\Middleware;

use Closure;
use Vendor\PackageName\Facades\LoggerExtra;

class LogExtraFieldsMiddleware
{
    public function handle($request, Closure $next)
    {
        LoggerExtra::setExtraFields(['user_agent' => $request->userAgent()]);
        return $next($request);
    }
}

Gotchas and Tips

Pitfalls

• Field Overwriting: Global fields are merged with per-log entry fields. Use the extra key to explicitly override:

  LoggerExtra::info("Event", ['extra' => ['user_id' => 123]]); // Overrides config
  

• Configuration Caching: Clear config cache after publishing:

  php artisan config:clear
  

• Performance: Avoid heavy computations in extra_fields (e.g., DB queries). Cache or lazy-load values.

Debugging

• Log Level Filtering: Use LoggerExtra::debug() to inspect merged fields:

  LoggerExtra::debug("Debug fields", ['extra' => ['test' => true]]);
  

• Check Config: Verify config/package-name.php is loaded. Run:

  php artisan config:dump
  

Extension Points

• Custom Field Providers: Extend the package by binding a service to resolve dynamic fields:

  $this->app->bind(\Vendor\PackageName\Contracts\ExtraFieldProvider::class, function () {
      return new class {
          public function getFields(): array {
              return ['custom_metric' => 'value'];
          }
      };
  });
  

• Log Channels: Use the package with custom Monolog handlers (e.g., Slack, Datadog) by configuring the logging array in config/logging.php.

Breaking Changes (v1.0.0)

• Facade Renaming: The logger facade is now LoggerExtra (previously Logger if it existed). Update imports:

  - use Vendor\PackageName\Facades\Logger;
  + use Vendor\PackageName\Facades\LoggerExtra;
  

• Configuration Structure: The extra_fields key is now required in the published config. Backward compatibility is not guaranteed for older versions.