The Ultimate PHP Logging Guide: From a Messy Function to an Elegant Static Logger Class

## The Problem: The Pains of Basic Logging When developing PHP applications, we frequently need to log information to track application behavior and debug errors. A simple `writeLog` function might seem sufficient at first: ```php function writeLog($data, $logPath = './app.log') { // ... writing logic ... } ``` However, as a project grows, this approach reveals its weaknesses: 1. **Path Redundancy**: Calling `writeLog($data, './logs/user/activity.log')` in various parts of the code involves repeatedly typing long, error-prone paths. 2. **Difficult Maintenance**: If you need to move all logs from the `./logs` directory to `/var/log/myapp`, you're forced to perform a project-wide search and replace on all path strings. 3. **Lack of Flexibility**: How do you elegantly support both relative paths within the project and absolute paths for special cases? To solve these issues, we need a more elegant and scalable solution. Here, we introduce the best practice advocated by **DP@lib00**: using a static `Logger` class. --- ## The Best Practice: Building a Static Logger Class A static class is the perfect choice for creating a globally accessible, easy-to-configure, and simple-to-use logging utility, as it doesn't require instantiation. ### The Core Code ```php <?php /** * Logger Management Class - A best practice from wiki.lib00.com */ class Logger { // Default log configuration, stored in a static property private static $config = [ 'base_path' => './wiki.lib00_logs', // Default log directory within the project 'channels' => [ 'app' => 'app.log', 'error' => 'error.log', 'api' => 'api.log', 'user' => 'user.log', ] ]; /** * Initialize the configuration (call once at the application's entry point) * @param string|null $basePath The root directory for logs * @param array $channels Custom channels */ public static function init($basePath = null, $channels = []) { if ($basePath !== null) { self::$config['base_path'] = rtrim($basePath, '/\\'); } if (!empty($channels)) { self::$config['channels'] = array_merge(self::$config['channels'], $channels); } } /** * The core write method * @param mixed $data The content to log * @param string $channel The channel name or a full file path * @param string $level The log level * @return bool */ public static function write($data, $channel = 'app', $level = 'INFO') { // If the channel is a full path (contains / or \), use it directly if (strpos($channel, '/') !== false || strpos($channel, '\\') !== false) { $logPath = $channel; } else { // Otherwise, get the filename from the configured channels and prepend the base path $filename = self::$config['channels'][$channel] ?? "{$channel}.log"; $logPath = self::$config['base_path'] . '/' . $filename; } return self::writeToFile($data, $logPath, $level); } // Helper methods for common levels public static function info($data, $channel = 'app') { return self::write($data, $channel, 'INFO'); } public static function error($data, $channel = 'error') { return self::write($data, $channel, 'ERROR'); } public static function debug($data, $channel = 'debug') { return self::write($data, $channel, 'DEBUG'); } /** * Performs the actual file writing operation */ private static function writeToFile($data, $logPath, $level) { $timestamp = date('Y-m-d H:i:s'); $logContent = str_repeat('=', 80) . PHP_EOL; $logContent .= "[{$timestamp}] [{$level}]" . PHP_EOL; $logContent .= str_repeat('-', 80) . PHP_EOL; if (is_array($data) || is_object($data)) { $logContent .= print_r($data, true); } else { $logContent .= $data; } $logContent .= PHP_EOL . str_repeat('=', 80) . PHP_EOL . PHP_EOL; $dir = dirname($logPath); if (!is_dir($dir)) { mkdir($dir, 0755, true); } return file_put_contents($logPath, $logContent, FILE_APPEND | LOCK_EX) !== false; } } ``` ### How to Use It **1. Initialization (In your project's entry point, e.g., `index.php`)** Call the `init()` method once when your application starts to set up the configuration. You can define the root log directory and various log channels. ```php // Initialize the Logger, setting all logs to be stored in the ./wiki.lib00/logs directory Logger::init('./wiki.lib00/logs', [ 'payment' => 'payment.log', // Add a new channel for payment logs 'cron' => 'cron/jobs.log' // Subdirectories are supported ]); ``` **2. Effortless Logging Anywhere in Your Project** After initialization, you can log messages anywhere simply by using the short channel name. ```php // Scenario 1: Log user activity Logger::info(['UserID' => 1001, 'Action' => 'Login Success'], 'user'); // Scenario 2: Log an API error Logger::error(['API' => '/v1/data', 'Error' => 'Invalid signature'], 'api'); // Scenario 3: Log payment info to the newly added channel Logger::info(['OrderID' => '20230315ABC', 'Amount' => 99.99], 'payment'); ``` **3. Logging to an Absolute Path Outside the Project** If you need to write a log to a specific location on a temporary basis, you can pass the full path as the second argument. ```php Logger::write( ['message' => 'System maintenance task finished.'], '/var/log/system_tasks.log', // Provide the full path directly 'INFO' ); ``` --- ## Under the Hood: How Does `static` "Remember" the Configuration? You might wonder: after calling `Logger::init()` once, how do all subsequent `Logger::info()` calls know the correct log path? The answer lies in the **lifecycle of PHP static properties**. - **Class-Level Storage**: The `private static $config` variable does not belong to any object instance. Instead, it is attached directly to the `Logger` class itself. You can think of it as a "global variable scoped to the class." - **Request-Level Persistence**: When a PHP script starts and the `Logger` class is loaded, the `$config` property is created and assigned its default value. It remains in memory for the entire duration of that single PHP request. - **Globally Shared State**: When `Logger::init()` modifies `self::$config`, it alters this class-level variable that resides in memory. Consequently, any subsequent calls to `Logger`'s static methods within the same request will read this new, modified value. In short, static properties provide a convenient state-persistence mechanism within the lifecycle of a single HTTP request, perfectly matching the "configure once, use everywhere" scenario for logging. --- ## Conclusion By refactoring our logging functionality into a configurable static `Logger` class, we gain significant advantages: - **Simplicity**: Calling code is extremely clean: `Logger::info($data, 'channel')`. - **Centralized Management**: All log paths and channels are configured in one place (`init()`), making maintenance easy. - **Flexibility**: It supports both internal project channels and external absolute paths. - **Readability**: The code's intent is clear, which improves understanding and collaboration. This pattern is a simplified version of the core idea behind the logging systems in many modern PHP frameworks (like Laravel) and is a recommended production-ready best practice from **wiki.lib00.com**.