Download the PHP package wp-spaghetti/wonolog-handler without Composer

Wonolog Handler

Monolog handler that forwards Laravel logs to Inpsyde's Wonolog - the professional WordPress logging solution.

Works with any Laravel + WordPress setup: Acorn (w/wo Sage), WP Starter, Corcel, or custom integrations.

Features

• Clean Laravel Syntax - Use Log::error(), Log::info(), etc. anywhere in your code
• Graceful Degradation - Works with or without Wonolog active
• wpify/scoper Support - Automatically detects scoped Wonolog namespace
• Zero Configuration - Works out of the box with sensible defaults
• Flexible Propagation - Control whether to stop at Wonolog or continue to other handlers

Requirements

• PHP >= 8.2
• WordPress >= 6.0
• Laravel Illuminate/Support ^10.0|^11.0|^12.0|^13.0
• Monolog ^2.0|^3.0

Note: Inpsyde's Wonolog is not required for the package to work. Without Wonolog, logs gracefully pass through to other handlers in your stack (e.g., file logging).

Installation

1. Install the handler package

In your Laravel + WordPress project (Sage theme, WP Starter, etc.):

The package auto-registers via service provider discovery.

2. Install WP Spaghetti Wonolog mu-plugin (optional)

For email notifications, sensitive data filtering, and advanced logging features, install the WP Spaghetti Wonolog mu-plugin, that provides a complete logging solution with production-ready configuration.

See the WP Spaghetti Wonolog documentation for setup and configuration options.

3. Configure logging

Update your config/logging.php:

See examples/logging.php for a complete configuration example.

Usage

Basic Logging

With Context

Channel Selection

Framework-Specific Examples

Sage Themes (Acorn)

WP Starter

Corcel

See examples/usage.php for more real-world examples including WordPress hooks, WooCommerce integration, API logging, and performance monitoring.

Advanced Configuration

Publish Configuration

To customize settings, publish the config:

This creates config/wonolog.php in your project:

Custom Wonolog Namespace (for wpify/scoper)

If Wonolog is scoped, override the namespace:

Via config:

Via filter:

Via environment:

Custom Action Hook (for wpify/scoper)

If Wonolog uses a custom action hook name:

Via config:

Via filter:

Via environment:

Control Log Propagation

By default, logs continue to other handlers in the stack after Wonolog (allowing file backup). You can change this:

Stop at Wonolog (no file backup):

Or via environment:

Use cases:

• false (default): Wonolog + file backup - recommended for production
• true: Only Wonolog - if you don't want file logs and trust Wonolog completely

How It Works

Architecture

Technical Details

Channel Handling:

• Wonolog expects channel at the top level of the action array, not inside context
• If user provides 'channel' => 'SECURITY' in context, it's extracted and moved to top level
• The channel is removed from context after extraction to avoid duplication
• If no channel is provided, it's NOT passed to Wonolog (Wonolog uses its default: DEBUG)
• Monolog's channel (e.g., stack, development) is NEVER used - it has nothing to do with Wonolog

Example behavior:

PSR-3 Placeholder Compatibility:

• The handler uses array format when calling do_action('wonolog.log', [...])
• This forces Wonolog's HookLogFactory::fromArray() method instead of fromString()
• Fixes PSR-3 placeholder substitution (e.g., {url}, {handle}) which breaks in fromString()
• Compatible with all Wonolog v2.x and v3.x versions

Extra Data:

• Monolog's extra data is passed as $context['extra'] (following Wonolog's convention)
• Datetime is passed as $context['datetime'] for full compatibility

Graceful Degradation

Without Wonolog mu-plugin:

• WonologHandler detects Wonolog is not active
• Handler does nothing and returns false
• Logs continue to other handlers (files, etc.)
• No errors or warnings

With Wonolog mu-plugin:

• Handler forwards logs to Wonolog
• Wonolog processes with email, filtering, etc.
• Logs optionally continue to file backup (based on stop_propagation)

Namespace Detection

The handler automatically detects Wonolog's namespace:

1. Checks default Inpsyde\Wonolog
2. Applies filter wonolog_handler_namespace
3. Supports scoped namespaces from wpify/scoper
4. Verifies Configurator::ACTION_SETUP was triggered
5. Caches result for performance

Troubleshooting

Logs not appearing in Wonolog

Check if Wonolog is active:

Wrong namespace or action detected

Override via filter or config (see Advanced Configuration).

Channel-related issues

Understanding channel behavior:

1. Custom Wonolog channel (when explicitly provided):

2. Default Wonolog channel (when not provided):

3. Channel extraction:

   • If 'channel' is in context, it's extracted and passed to Wonolog at top level
   • The 'channel' key is removed from context to avoid duplication
   • This ensures channel appears only once in emails (as "Channel: XXX", not in context)

4. Monolog vs Wonolog channels:

   • Monolog channels (development, stack, single) route logs in Laravel
   • Wonolog channels (DEBUG, SECURITY, HTTP) categorize logs in Wonolog
   • They are completely separate - Monolog channels are NOT sent to Wonolog
   • To set a Wonolog channel: Log::error('msg', ['channel' => 'SECURITY'])

5. Channel naming conventions ⚠️:

   • IMPORTANT: Wonolog uses UPPERCASE channel names by convention
   • Standard Wonolog channels: DEBUG, SECURITY, HTTP, DB, PHP-ERROR, CRON, etc.
   • Using lowercase (e.g., 'security' instead of 'SECURITY') may cause logs not to be tracked
   • Using non-configured channels (e.g., 'FOO') may also not be tracked
   • This behavior depends on your Wonolog configuration and filters
   • Best practice: Always use UPPERCASE for channel names
6. Custom channel names:
   • You can use custom channel names if configured in Wonolog
   • Examples: PAYMENT, API, WOOCOMMERCE, etc.
   • Make sure they're configured in your Wonolog setup
   • Always use UPPERCASE for consistency

Logs not in file backup

Ensure 'single' channel is in the stack:

And ensure stop_propagation is false (default).

Testing

More info

See LINKS file.

Changelog

Please see CHANGELOG for a detailed list of changes for each release.

We follow Semantic Versioning and use Conventional Commits to automatically generate our changelog.

Release Process

• Major versions (1.0.0 → 2.0.0): Breaking changes
• Minor versions (1.0.0 → 1.1.0): New features, backward compatible
• Patch versions (1.0.0 → 1.0.1): Bug fixes, backward compatible

All releases are automatically created when changes are pushed to the main branch, based on commit message conventions.

Contributing

For your contributions please use:

• Conventional Commits
• Pull request workflow

See CONTRIBUTING for detailed guidelines.

Sponsor

License

(ɔ) Copyleft 2026 Frugan.
GNU GPLv3, see LICENSE file.