README

A simple, lean logging library for WordPress plugins and themes with smart defaults and registry pattern support. Zero-config initialization that automatically follows WordPress debug conventions.

Features

🚀 Zero Configuration: Works immediately with WordPress debug settings
📦 Registry Pattern: Centralized logger management across plugins
🎯 Smart Defaults: Automatically follows WP_DEBUG - no boilerplate needed
📝 Standard Log Levels: Error, warning, info, and debug logging
🔒 Automatic Security: Built-in .htaccess and index.php protection
🐛 Exception Handling: Native support for exceptions and WP_Error objects
📂 Flexible Paths: Use simple filenames or full paths
⚡ Lightweight: Minimal, focused code
🎛️ Plugin-Specific Control: Enable debugging per plugin via wp-config.php

Requirements

PHP 7.4 or later
WordPress 5.0 or later

Installation

composer require arraypress/wp-logger

Basic Usage

Using the Registry (Recommended)

// Register once in your main plugin file
// Creates: wp-content/uploads/my-plugin/my-plugin.log
register_logger( 'my-plugin' );

// Get and use anywhere in your plugin
$logger = get_logger( 'my-plugin' );
$logger->error( 'Payment processing failed' );
$logger->warning( 'Low inventory alert' );
$logger->info( 'Order processed successfully' );
$logger->debug( 'Debug information' );

Direct Instantiation

use ArrayPress\Logger\Logger;

// Create directly if you prefer
// Creates: wp-content/uploads/my-plugin/my-plugin.log
$logger = new Logger( 'my-plugin' );

// Start logging
$logger->error( 'Payment processing failed' );
$logger->info( 'Order processed successfully' );

Custom Configuration

// Custom filename within plugin directory
// Creates: wp-content/uploads/my-plugin/errors.log
register_logger( 'my-plugin', [
    'log_file' => 'errors.log'
] );

// Multiple loggers for different purposes
register_logger( 'my-plugin' );           // → uploads/my-plugin/my-plugin.log
register_logger( 'my-plugin-api', [
    'log_file' => 'api.log'                // → uploads/my-plugin-api/api.log
] );
register_logger( 'my-plugin-payments', [
    'log_file' => 'payments.log'           // → uploads/my-plugin-payments/payments.log
] );

// Full path override
register_logger( 'my-plugin', [
    'log_file' => WP_CONTENT_DIR . '/logs/custom.log'
] );

// Force enable logging regardless of WP_DEBUG
register_logger( 'my-plugin', [
    'enabled' => true
] );

Smart Debug Control

The logger automatically detects debug settings in this order:

Plugin-specific constant (if defined)
WP_DEBUG constant (WordPress standard)

Via wp-config.php

// Enable debugging for specific plugin only
define( 'MY_PLUGIN_DEBUG', true );

// Or use WordPress debug (affects all loggers using defaults)
define( 'WP_DEBUG', true );

Plugin Integration Pattern

namespace MyPlugin;

use function ArrayPress\Logger\register_logger;
use function ArrayPress\Logger\get_logger;

class Plugin {
    
    public function __construct() {
        // Register logger once
        // Creates: wp-content/uploads/my-plugin/my-plugin.log
        register_logger( 'my-plugin' );
    }
    
    public function process_order( $order_data ) {
        $logger = get_logger( 'my-plugin' );
        $logger->info( 'Processing order', ['order_id' => $order_data['id']] );
        
        try {
            // Process order logic
            $logger->info( 'Order processed successfully' );
        } catch ( Exception $e ) {
            $logger->exception( $e, ['order_data' => $order_data] );
            throw $e;
        }
    }
}

Creating Plugin Wrapper Functions (Optional)

For convenience, you can create wrapper functions in your plugin:

namespace MyPlugin;

use ArrayPress\Logger\Logger;
use function ArrayPress\Logger\get_logger;

function logger(): ?Logger {
    return get_logger( 'my-plugin' );
}

function log_error( string $message, array $context = [] ): void {
    logger()?->error( $message, $context );
}

function log_info( string $message, array $context = [] ): void {
    logger()?->info( $message, $context );
}

// Usage anywhere in your plugin
\MyPlugin\log_error( 'Database connection failed' );
\MyPlugin\log_info( 'Cache cleared successfully' );

Exception and Error Handling

Exceptions

try {
    process_payment( $data );
} catch ( Exception $e ) {
    $logger->exception( $e, ['user_id' => 123] );
    // Automatically logs message, file, line, and stack trace
}

WordPress Errors

$result = wp_remote_get( $url );

if ( is_wp_error( $result ) ) {
    $logger->wp_error( $result, ['url' => $url] );
    // Automatically logs error code, message, and data
}

Context Data

$logger->error( 'Database connection failed', [
    'host'     => DB_HOST,
    'database' => DB_NAME,
    'user_id'  => get_current_user_id(),
    'memory'   => memory_get_usage()
] );

Configuration Options

Option	Type	Default	Description
`enabled`	bool	Follows `{PLUGIN}_DEBUG` or `WP_DEBUG`	Whether logging is enabled
`log_file`	string	`uploads/{plugin-name}/{plugin-name}.log`	Log file path or filename

File Locations

Default location pattern:

wp-content/uploads/{plugin-name}/{plugin-name}.log

Examples:

sugarcart → wp-content/uploads/sugarcart/sugarcart.log
my-plugin → wp-content/uploads/my-plugin/my-plugin.log
woocommerce → wp-content/uploads/woocommerce/woocommerce.log

The library automatically:

Creates directories as needed
Adds .htaccess to deny direct access
Adds index.php for additional security
Uses proper WordPress file permissions

Log Format

[2025-01-15T10:30:45+00:00] ERROR: Payment processing failed {"user_id":123,"amount":99.99}
[2025-01-15T10:30:46+00:00] INFO: Order processed successfully {"order_id":"12345"}
[2025-01-15T10:30:47+00:00] DEBUG: Cache cleared {"cache_key":"user_123_orders"}

API Reference

Registry Functions

register_logger( string $name, array $options = [] ): Logger - Register a new logger
get_logger( string $name ): ?Logger - Get a registered logger
has_logger( string $name ): bool - Check if a logger exists
remove_logger( string $name ): bool - Remove a logger

Logging Methods

error( string $message, array $context = [] ) - Log error messages
warning( string $message, array $context = [] ) - Log warnings
info( string $message, array $context = [] ) - Log informational messages
debug( string $message, array $context = [] ) - Log debug information
log( string $message, array $context = [], string $level = 'INFO' ) - Generic logging

Specialized Methods

exception( Throwable $exception, array $context = [] ) - Log exceptions with trace
wp_error( WP_Error $wp_error, array $context = [] ) - Log WordPress errors

Utility Methods

clear() - Clear the log file
get_contents() - Get log file contents
get_file() - Get log file path
is_enabled() - Check if logging is enabled

Why This Logger?

Unlike complex logging libraries, this logger is designed specifically for WordPress with just enough features:

No configuration required - Uses WordPress conventions by default
No dependencies - Just one simple class
WordPress-native - Uses WordPress functions and follows WordPress patterns
Registry pattern - Centralized management without globals
Smart naming - Each plugin gets its own named log file automatically
Predictable - Does exactly what you expect, nothing more

Perfect for plugins and themes that need reliable logging without the overhead of large logging frameworks.

arraypress / wp-logger

Maintainers

Details