Download the PHP package larsgmortensen/litelog without Composer

LiteLog – A Lightweight & High-Performance JSON Logger for PHP

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):

`

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

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

🚀 Quick Start

Example log output (JSON line)

🧰 API

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! 🌟