Oihana PHP System

LoggerManager

AbstractYes

Abstract base class for managing log files and PSR-3 loggers.

LoggerManager provides utility methods to handle log files and directories, including creating, reading, counting lines, clearing logs, and retrieving log paths and names.

Features:

  • Abstract createLogger() method to return a PSR-3 compliant logger.
  • Automatic creation of log directories if they do not exist.
  • Directory creation uses a temporary umask 0002 to ensure group writable permissions (e.g., 0664 for files, 2775 for directories) in collaborative environments.
  • Utilities to read log lines as structured entries (createLog()).
  • Counting lines (countLines()) and clearing files (clear()).
  • Listing log files (getLoggerFiles()), filtered by name and extension.
  • Flexible configuration via constructor array:
    • directory: Base log directory path.
    • dirPermissions: Permissions for new directories.
    • path: Subfolder path within the base directory.
    • extension: Log file extension.
    • name: Optional logger channel name.

Example usage:

$loggerManager = new class(['directory' => '/var/log/myapp']) extends LoggerManager
{
    public function createLogger(): LoggerInterface
    {
        // return a PSR-3 logger instance
    }
};

$loggerManager->ensureDirectory();
$lines = $loggerManager->getLogLines(null); // read lines from default log file
Tags
author

Marc Alcaraz

since
1.0.0

Table of Contents

Constants

DEFAULT_EXTENSION  = '.log'
Default log file extension.
DEFAULT_NAME  = 'log'
Default log file name.
DEFAULT_PATH  = 'log'
Default log folder path (relative to $directory).

Properties

$directory  : string
Default permissions for newly created directories.
$dirPermissions  : int|float
The directory permission.
$extension  : string
The file extension used for log files (e.g., ".log").
$name  : string|null
Optional name of the logging channel.
$path  : string
Subfolder or path where log files are stored (relative to $directory).

Methods

__construct()  : mixed
Creates a new LoggerManager instance.
clear()  : bool
Clears the content of a specific log file.
countLines()  : int
Returns the number of lines in a log file.
createLog()  : Log|null
Parses a log line into a structured array.
createLogger()  : LoggerInterface
Must be implemented by subclasses to return a PSR-3 compliant logger.
ensureDirectory()  : void
Ensure the log directory exists and is writable.
getDirectory()  : string
Returns the full path of the log directory.
getExtension()  : string
Returns the file extension used for log files.
getFileName()  : string
Returns the base name of the log file.
getFilePath()  : string
Returns the full path to a log file.
getLoggerFiles()  : array<string|int, mixed>|false
Returns the list of log files in the log directory matching the current logger name and extension.
getLogLines()  : array<string|int, mixed>|null
Returns the lines of a log file as an array of structured entries.

Constants

DEFAULT_EXTENSION

Default log file extension.

public mixed DEFAULT_EXTENSION = '.log'

DEFAULT_NAME

Default log file name.

public mixed DEFAULT_NAME = 'log'

DEFAULT_PATH

Default log folder path (relative to $directory).

public mixed DEFAULT_PATH = 'log'

Properties

$directory

Default permissions for newly created directories.

public string $directory = \oihana\enums\Char::EMPTY

Group writable (g+w) for collaborative environments.

$dirPermissions

The directory permission.

public int|float $dirPermissions = 0775

$extension

The file extension used for log files (e.g., ".log").

public string $extension = '.log'

$name

Optional name of the logging channel.

public string|null $name = null

Used as prefix for log files and as a descriptive label.

$path

Subfolder or path where log files are stored (relative to $directory).

public string $path = \oihana\enums\Char::EMPTY

Methods

__construct()

Creates a new LoggerManager instance.

public __construct([array{directory?: string|null, dirPermissions?: int|null, extension?: string|null, path?: string|null} $init = [] ][, string|null $name = null ]) : mixed
Parameters
$init : array{directory?: string|null, dirPermissions?: int|null, extension?: string|null, path?: string|null} = []

Optional initialization options

$name : string|null = null

Optional logger channel name.

clear()

Clears the content of a specific log file.

public clear(string $file) : bool
Parameters
$file : string

Log file name.

Tags
throws
FileException

If clearing fails due to filesystem permissions or errors.

Return values
bool —

True if the file was cleared, false if file does not exist.

countLines()

Returns the number of lines in a log file.

public countLines(string $file) : int
Parameters
$file : string

Log file name.

Tags
throws
FileException

If file cannot be read.

Return values
int —

Number of lines in the file.

createLog()

Parses a log line into a structured array.

public createLog(string $line) : Log|null

Example: "2025-08-21 10:30:00 INFO Some message" becomes: [ 'date' => '2025-08-21', 'time' => '10:30:00', 'level' => 'INFO', 'message' => 'Some message' ]

Parameters
$line : string

Raw log line.

Tags
throws
ReflectionException
Return values
Log|null —

Parsed log entry or null if line is empty or malformed.

createLogger()

Must be implemented by subclasses to return a PSR-3 compliant logger.

public abstract createLogger() : LoggerInterface
Return values
LoggerInterface

ensureDirectory()

Ensure the log directory exists and is writable.

public ensureDirectory() : void

If the directory does not exist, it will be created recursively. A temporary umask 0002 is applied so that the directory is group writable according to $this->dirPermissions (default 2775). Files created within the directory will inherit group write permission (0664 by default).

Throws a DirectoryException if the directory cannot be created or is not writable.

Tags
throws
DirectoryException

if the directory cannot be created or is not writable.

getDirectory()

Returns the full path of the log directory.

public getDirectory() : string

Combines the base $this->directory and $this->path using canonical path normalization. The returned path is absolute (or relative if $this->directory is relative) and can be safely used for file operations.

Return values
string —

Absolute or relative path to the log folder.

getExtension()

Returns the file extension used for log files.

public getExtension() : string
Return values
string —

Log file extension, including dot (e.g., ".log").

getFileName()

Returns the base name of the log file.

public getFileName() : string
Return values
string —

Log file name.

getFilePath()

Returns the full path to a log file.

public getFilePath([string|null $file = null ]) : string

If $file is null, returns the default log file path: /. Uses joinPaths() to safely concatenate directory and file name.

Parameters
$file : string|null = null

Optional custom file name. Defaults to .

Return values
string —

Full path to the log file.

getLoggerFiles()

Returns the list of log files in the log directory matching the current logger name and extension.

public getLoggerFiles() : array<string|int, mixed>|false

The search uses findFiles() with options:

  • Pattern: "*"
  • Mode: files only
  • Order: ascending by file name

Throws a DirectoryException if the log directory cannot be read.

Tags
throws
DirectoryException

if the log directory cannot be read.

Return values
array<string|int, mixed>|false —

List of log file names or false on error.

getLogLines()

Returns the lines of a log file as an array of structured entries.

public getLogLines(string|null $file) : array<string|int, mixed>|null
Parameters
$file : string|null

Log file name.

Tags
throws
FileException

If the file cannot be read.

Return values
array<string|int, mixed>|null —

Array of parsed log entries or null if file does not exist.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results