README

LiteLog is a fast, minimal, efficient, single-file JSON logger focused on robustness and runtime performance.
It provides atomic appends, safe log rotation, and strict error handling with zero dependencies.
Designed for high-traffic PHP applications that require reliable logging without external bloat (PHP 8.0+).

🚀 Features that make LiteLog stand out

• Blazing-fast writes – Appends JSON lines with atomic LOCK_EX safety.
• Safe concurrency – Multiple processes can write concurrently without losing lines.
• Log rotation – Automatically rotates logs when file size exceeds threshold.
• Retention policy – Configurable pruning of old rotated logs.
• JSON by default – Structured, machine-readable logs with timestamp, category, message, and optional context.
• Error-hardening – Fails fast if directory is missing, not writable, or JSON encoding fails.
• Minimal overhead – One file, static API, no runtime dependencies.
• Secure by default – Filenames are sanitized to prevent path traversal attacks.
• Production-ready – Verified by functional, benchmark, and concurrency tests.

📦 Installation

Via Composer (recommended):

composer require larsgmortensen/litelog

Or manually include the class file (e.g. src/LiteLog/LiteLog.php) with Composer’s autoloader or require_once:

use LiteLog\LiteLog;
require_once __DIR__.'/src/LiteLog/LiteLog.php';

Tip: Always place your log directory outside webroot, or protect it with .htaccess.

🚀 Quick Start

use LiteLog\LiteLog;

// Configure once at bootstrap
LiteLog::setDefaultDir('/path/to/logs');
LiteLog::setMaxFileSize(10 * 1024 * 1024); // 10 MB
LiteLog::setMaxRotatedFiles(5);            // keep 5 rotated files

// Write a log line
LiteLog::log(
    'app.json',  // Log filename (relative to log dir)
    'info',  // Category
    'Coffee supply is critically low',  // Message (string or array)
    ['cups_left' => 1, 'developer' => 'Sleepy']  // Context (optional)
);

Example log output (JSON line)

{
  "timestamp": "2025-09-18 02:53:18",
  "category": "warning",
  "message": "Coffee supply is critically low",
  "context": {
    "cups_left": 1,
    "developer": "Sleepy"
  }
}

🧰 API

LiteLog::setDefaultDir(string $dir, bool $createIfMissing = false): void
LiteLog::setMaxFileSize(int $bytes): void
LiteLog::setMaxRotatedFiles(?int $count): void
LiteLog::log(string $file, string $category, string|array|object $message, array $context = []): void

Parameters

• $dir: Log directory (must exist unless $createIfMissing=true).
• $file: Filename (e.g. app.json). Must be a clean name, no path traversal.
• $category: Category string (error, info, etc.).
• $message: String, array, or object. Arrays/objects are JSON-encoded automatically.
• $context: Optional associative array with extra metadata (e.g., request id, ip).
• $bytes: Maximum file size before rotation. Default: 10 MB.
• $count: Number of rotated logs to keep. null disables pruning.

📖 Usage Notes

• All log entries are one JSON line per entry → easy to parse with tools like jq or ELK.
• Rotation creates files like app_1695030618123.json.
• If retention is set, only the latest N rotated logs are kept; older are pruned.
• Fail-fast philosophy: if directory is missing or not writable, LiteLog throws immediately.

🧪 Tests

LiteLog is verified by three test suites:

1. Sanity tests (test_litelog_new.php) Validates JSON encoding, rotation, retention, and path sanitization.

2. Benchmarks (bench_litelog.php, bench_litelog_web.php) Measures performance vs. old implementation. Results (shared hosting, 100k lines):

   • OLD: ~1643 ops/s
   • NEW: ~1476 ops/s (≈10% overhead for safe locking)

3. Concurrency test (concurrency_run.php) Spawns multiple parallel PHP processes writing to the same log file. ✅ 400 000 lines written without loss or duplication under rotation.

💡 Why LiteLog?

LiteLog exists for developers who want reliable structured logging without dragging in heavy frameworks.

✨ Fast – 1.5–2k ops/s even on modest hardware.

✨ Safe – Atomic writes, no lost lines under concurrency.

✨ Structured – JSON lines are machine-readable.

✨ Lightweight – One file, static API, no dependencies.

✨ Robust – Strict error handling, sanitization, rotation + retention built-in.

📦 Packagist

LiteLog on Packagist: 👉 https://packagist.org/packages/larsgmortensen/litelog

📜 License

LiteLog is released under the GNU General Public License v3.0. See LICENSE for details.

🤝 Contributing

Contributions are welcome! Fork, submit issues, or open a pull request.

✍️ Author

Developed by Lars Grove Mortensen © 2025. Feel free to reach out or contribute!

LiteLog – the lightweight JSON logger you can trust 🚀

🌟 If you find this library useful, give it a star on GitHub! 🌟