LogFileModelTraits
Defines a set of traits that are intended to be used by Models to read, decompress and process log files.
Table of Contents
Methods
- read_log() : array<string|int, mixed>
- Reads all available logs for a given base log file path and returns the contents as an array of lines.
- check_file_exists() : void
- Checks if a given log file exists.
- gather_log_filepaths() : array<string|int, mixed>
- Gather all log filepaths for a given base log, ordered newest-first. The current (unrotated) log file is always first, followed by rotated logs in ascending rotation number (0, 1, 2...).
- get_log_type() : string
- Determines the compression type of a log file by normalizing its path (stripping numeric rotation suffixes).
- read_bzip2_log() : array<string|int, mixed>
- Decompresses a bzip2 compressed log file and returns the contents as an array of lines.
- read_compressed_tail_lines() : array<string|int, mixed>
- Reads a compressed log file and returns only the last $limit lines using streaming.
- read_gzip_log() : array<string|int, mixed>
- Decompresses a gzip compressed log file and returns the contents as an array of lines.
- read_log_forward() : array<string|int, mixed>
- Reads log entries starting from the newest, with pagination support.
- read_log_reverse() : array<string|int, mixed>
- Reads log entries starting from the oldest, with pagination support.
- read_tail_lines() : array<string|int, mixed>
- Reads the last $limit lines from a plain text file by seeking backwards from EOF.
- read_uncompressed_log() : array<string|int, mixed>
- Reads a given log file with no compression and returns the contents as an array of lines.
- read_xz_log() : array<string|int, mixed>
- Decompresses a xz compressed log file and returns the contents as an array of lines.
- stream_tail_lines() : array<string|int, mixed>
- Streams a compressed file line-by-line using a file handle, keeping only the last $limit lines via a ring buffer. Memory usage is O(limit) instead of O(decompressed_file_size).
Methods
read_log()
Reads all available logs for a given base log file path and returns the contents as an array of lines.
public
read_log(string $base_log[, int $limit = 0 ][, int $offset = 0 ][, bool $reverse = false ]) : array<string|int, mixed>
This will include rotated logs, including compressed logs.
When $limit > 0 and $reverse is false, reads newest log files first and stops as soon as enough lines are collected, avoiding loading the entire log history into memory.
When $reverse is true, reads from the oldest entries first (beginning of oldest log files) and paginates from there. This is useful for reading logs in chronological order.
When $limit is 0 (default), all log files are read for full backward compatibility.
Parameters
- $base_log : string
-
The base log file path.
- $limit : int = 0
-
Maximum total lines to return. 0 means unlimited (read everything).
- $offset : int = 0
-
Number of entries to skip before collecting.
- $reverse : bool = false
-
When true, read from oldest entries first; when false, read from newest first.
Tags
Return values
array<string|int, mixed> —An array of all log file contents for the given base log.
check_file_exists()
Checks if a given log file exists.
private
check_file_exists(string $filepath) : void
Parameters
- $filepath : string
-
The path to the log file.
Tags
gather_log_filepaths()
Gather all log filepaths for a given base log, ordered newest-first. The current (unrotated) log file is always first, followed by rotated logs in ascending rotation number (0, 1, 2...).
private
gather_log_filepaths(string $base_log) : array<string|int, mixed>
Only matches the base log itself and files with a rotation suffix (e.g. .0, .1.gz, .2.bz2).
Parameters
- $base_log : string
-
The base log file path.
Return values
array<string|int, mixed> —An array of all log file paths ordered newest-first.
get_log_type()
Determines the compression type of a log file by normalizing its path (stripping numeric rotation suffixes).
private
get_log_type(string $filepath) : string
Parameters
- $filepath : string
-
The log file path.
Return values
string —The file extension indicating the log type (e.g. 'log', 'gz', 'bz2', 'xz').
read_bzip2_log()
Decompresses a bzip2 compressed log file and returns the contents as an array of lines.
private
read_bzip2_log(string $filepath) : array<string|int, mixed>
Parameters
- $filepath : string
-
The path to the log file.
Return values
array<string|int, mixed> —An array of log file contents.
read_compressed_tail_lines()
Reads a compressed log file and returns only the last $limit lines using streaming.
private
read_compressed_tail_lines(string $filepath, int $limit, string $type) : array<string|int, mixed>
Uses PHP stream wrappers (compress.zlib://, compress.bzip2://) and popen for xz, all of which return standard file handles compatible with fread()/feof(). Memory usage is O(limit) instead of O(decompressed_file_size).
Parameters
- $filepath : string
-
The path to the compressed log file.
- $limit : int
-
Maximum number of lines to return.
- $type : string
-
Compression type: 'gz', 'bz2', or 'xz'.
Tags
Return values
array<string|int, mixed> —The last $limit non-empty lines from the file, in chronological order.
read_gzip_log()
Decompresses a gzip compressed log file and returns the contents as an array of lines.
private
read_gzip_log(string $filepath) : array<string|int, mixed>
Parameters
- $filepath : string
-
The path to the log file.
Return values
array<string|int, mixed> —An array of log file contents.
read_log_forward()
Reads log entries starting from the newest, with pagination support.
private
read_log_forward(array<string|int, mixed> $log_filepaths, int $limit, int $offset) : array<string|int, mixed>
Parameters
- $log_filepaths : array<string|int, mixed>
-
Log file paths ordered newest-first.
- $limit : int
-
Maximum entries to return.
- $offset : int
-
Number of newest entries to skip.
Return values
array<string|int, mixed> —Log entries with 'text' property.
read_log_reverse()
Reads log entries starting from the oldest, with pagination support.
private
read_log_reverse(array<string|int, mixed> $log_filepaths, int $limit, int $offset) : array<string|int, mixed>
Returns entries in reverse chronological order (newest first within the page).
Parameters
- $log_filepaths : array<string|int, mixed>
-
Log file paths ordered newest-first.
- $limit : int
-
Maximum entries to return.
- $offset : int
-
Number of oldest entries to skip.
Return values
array<string|int, mixed> —Log entries with 'text' property, in reverse chronological order.
read_tail_lines()
Reads the last $limit lines from a plain text file by seeking backwards from EOF.
private
read_tail_lines(string $filepath, int $limit) : array<string|int, mixed>
Memory usage is O(limit) instead of O(file_size).
Parameters
- $filepath : string
-
The path to the log file.
- $limit : int
-
Maximum number of lines to return from the end of the file.
Return values
array<string|int, mixed> —The last $limit non-empty lines from the file, in chronological order (oldest first).
read_uncompressed_log()
Reads a given log file with no compression and returns the contents as an array of lines.
private
read_uncompressed_log(string $filepath) : array<string|int, mixed>
Parameters
- $filepath : string
-
The path to the log file.
Return values
array<string|int, mixed> —An array of log file contents.
read_xz_log()
Decompresses a xz compressed log file and returns the contents as an array of lines.
private
read_xz_log(string $filepath) : array<string|int, mixed>
Parameters
- $filepath : string
-
The path to the log file.
Return values
array<string|int, mixed> —An array of log file contents.
stream_tail_lines()
Streams a compressed file line-by-line using a file handle, keeping only the last $limit lines via a ring buffer. Memory usage is O(limit) instead of O(decompressed_file_size).
private
stream_tail_lines(resource $fh, int $limit) : array<string|int, mixed>
Parameters
- $fh : resource
-
An already-opened readable file handle (from gzopen, bzopen, or popen).
- $limit : int
-
Maximum number of lines to keep.
Return values
array<string|int, mixed> —The last $limit non-empty lines from the stream, in chronological order.