Download the PHP package faustoff/laravel-contextify without Composer

Laravel Contextify

Contextual logging with inline notifications for Laravel.

Laravel Contextify enhances Laravel's logging with two main features:

1. Inline Notifications — send notifications alongside logging without splitting code into multiple lines for logging and notifying.
2. Automatic Context Enrichment — logs and notifications include extra contextual data from configured Call file and line, and more), helping you keep messages short and clean by moving additional context out of the message itself into a separate area.

Provides Log facade: same methods (debug, info, notice, warning, error, critical, alert, emergency) with identical parameters, plus a chainable notify() method.

Name origin: “Contextify” combines Context and Notify, reflecting its dual purpose — to enrich logs with contextual data and to send notifications for log events.

Features

• 📧 Notification Support: Send notifications via mail, telegram, or any Laravel notification channel
• 🔍 Automatic Context Enrichment: Logs and notifications automatically include extra contextual data from configured Context Providers
• 🔌 Custom Context Providers: Extend built-in providers with your own
• 🔄 Static & Dynamic Providers: Static (cached) and dynamic (refreshed on each call) providers
• 🎯 Group-Based Context: Separate Context Providers for logs and notifications
• 📊 PSR-3 Log Levels: All standard log levels (debug, info, notice, warning, error, critical, alert, emergency)
• 🎨 add custom channels
• 🔔 Notifications Channel Filtering: Filter channels with only and except parameters
• 🔄 Fluent API: Chain methods for readable code
• ⚡ Monolog Integration: Integrates with Laravel's logging via Monolog processors

Requirements

• PHP 8.0 or higher
• Laravel 8.0 or higher
• Monolog 2.0 or higher

Installation

Install the package via Composer:

Configuration

Optionally, publish the configuration file:

This creates config/contextify.php for configuring notifications.

Environment Variables

Add to .env to configure notification recipients and toggles:

Set CONTEXTIFY_ENABLED=false to fully disable Contextify: no context providers are booted, the Monolog processor is not registered, exception reporting is not hooked, notify() calls are ignored, and touch() becomes a no-op. Logging methods (debug, info, etc.) still forward messages to Laravel's Log facade, but without any context enrichment. This is useful for disabling Contextify during testing to eliminate its influence on the code under test.

Set CONTEXTIFY_NOTIFICATIONS_ENABLED=false to disable all notifications (both inline notify() and automatic exception notifications).

Note: CONTEXTIFY_ENABLED disables the entire package. CONTEXTIFY_NOTIFICATIONS_ENABLED only disables notifications while keeping context enrichment active.

Note: Telegram notifications require the laravel-notification-channels/telegram package to be installed manually.

Usage

Writing Logs

Use the for logging:

Sending Notifications

Chain notify() after any for notifications.

Filter channels using only and except parameters:

Control notification sending conditionally using the shouldNotify parameter:

If necessary, you can override the default implementation of the LogNotification:

Update configuration:

Exception Notifications

Exceptions are automatically reported via notifications (enabled by default). Notifications include exception details (message and stack trace) and extra context from for notifications.

If necessary, you can override the default implementation of the ExceptionNotification:

Update configuration:

To disable automatic exception notifications, set reportable to null:

Note: ExceptionNotificationFailedException prevents infinite loops when exception notifications fail.

Context Providers

Context Providers add extra contextual data to logs and notifications, helping you keep log entry and notification messages short and clean by moving additional context out of the message itself into a separate context area. The contextual data is still present in the log entry or notification, but it's separated from the message itself—keeping the message focused while preserving all information for searching and analysis. You no longer need to worry about explicitly passing the required contextual data each time, as it will be added automatically.

Static Context Providers

Static providers return data that remains constant throughout the request/process lifecycle. They implement StaticContextProviderInterface.

Built-in:

• ProcessIdContextProvider: Adds the current PHP process ID (pid)
• TraceIdContextProvider: Generates a unique 16-character hexadecimal trace ID (trace_id) for distributed tracing
• HostnameContextProvider: Adds the server hostname (hostname)
• EnvironmentContextProvider: Adds the application environment (environment)

Refreshing Static Context

Static context is cached during application boot. Use touch() to refresh it manually, useful when a process is forked (e.g., queue workers) to generate a new trace ID:

Dynamic Context Providers

Dynamic providers refresh data on each log call. They implement DynamicContextProviderInterface.

Built-in:

• CallContextProvider: Adds the file path and line number (file) and class name (class) of the calling code
• PeakMemoryUsageContextProvider: Adds the peak memory usage in bytes (peak_memory_usage)
• DateTimeContextProvider: Adds the current date and time in Laravel log format (datetime)

Creating Custom Context Providers

Implement StaticContextProviderInterface or DynamicContextProviderInterface:

Registering Custom Providers

Add custom providers to config/contextify.php:

Group-Based Context

Define separate Context Providers for logs and notifications. If a provider appears in both sets, the same context data is used for both.

Configure in config/contextify.php:

• logs.providers — providers for log entries
• notifications.providers — providers for notifications

Example:

Notifications

Supports mail and telegram channels out of the box. Mail works immediately; Telegram requires the laravel-notification-channels/telegram package.

Configuration

Configure channels in config/contextify.php:

Custom Notification Channels

For example, to add Slack notifications, you need to:

1. Create a custom notification class with a toSlack() method implemented:

2. Create a custom notifiable class with a routeNotificationForSlack() method implemented:

3. Configure Slack in config/services.php.

4. Update config/contextify.php:

Note: For exception notifications, extend ExceptionNotification and add the toSlack() method similarly.

Want more notification channels? You are welcome to Laravel Notifications Channels.

Console Commands

Tracking

Use Faustoff\Contextify\Console\Trackable trait to log command start, finish, and execution time:

Log:

Output Capturing

Use Faustoff\Contextify\Console\Outputable trait to capture Laravel console output from info()-like methods and store it in logs:

Log:

Handling Shutdown Signals

Handle shutdown signals (SIGQUIT, SIGINT, SIGTERM by default) for graceful shutdown. Use the appropriate trait with SignalableCommandInterface:

• TerminatableV62 for symfony/console:<6.3 (Laravel 9, 10)
• TerminatableV63 for symfony/console:^6.3 (Laravel 9, 10)
• TerminatableV70 for symfony/console:^7.0 (Laravel 11+)

Log:

License

This package is open-sourced software licensed under the MIT license.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or contributions, please visit the GitHub repository.