README

A modern, PSR-compliant successor to Apache Log4PHP (now unmaintained).

Xsga Log4PHP is a heavily refactored and redesigned logging library for PHP, originally inspired by Apache Log4PHP and rebuilt for the current PHP ecosystem. It targets PHP 8.4+, follows PSR-3, ships with PSR-4 autoloading, and provides a flexible logging pipeline with appenders, layouts, context interpolation, and XML or programmatic configuration.

Why this project exists
Key Features
What makes it different
Quick Start
Basic Configuration
Documentation
Who should use this
License
Acknowledgements

📌 Why this project exists

Apache Log4PHP is no longer actively maintained and does not align with current PHP versions, tooling, or interoperability expectations.

This project exists to:

Provide a conceptual successor for teams familiar with Apache Log4PHP
Preserve the strengths of the original model while removing outdated constraints
Modernize the architecture, code style, and runtime requirements
Align the library with current PHP standards, especially PSR-3 and PSR-4
Offer a maintainable codebase suitable for static analysis, code style checks, and ongoing development

✨ Key Features

✅ PSR-3 compatible logging interface and context placeholder interpolation
✅ PSR-4 autoloading support via Composer
✅ PHP 8.4+ compatibility
✅ XML-based and programmatic array-based configuration
✅ Multiple appenders, including File, DailyFile, RollingFile, Console, and Loki
✅ Multiple layouts, including Pattern, JSON, and Simple
✅ Full log level support from ALL through OFF, aligned with modern logging expectations
✅ Refactored architecture with cleaner separation of responsibilities
✅ Improved maintainability, extensibility, and static-analysis friendliness

🔍 What makes it different

Compared to the original Apache Log4PHP:

The internals have been substantially refactored for modern PHP and stricter typing expectations
The package is distributed as a Composer-first library with PSR-4 autoloading
Logging follows the PSR-3 method set and context conventions
Configuration remains familiar, but the implementation is cleaner and easier to maintain
Appenders and layouts are designed for present-day use cases, including structured JSON output and Loki integration
Development tooling now includes linting, PSR-12 style checks, and Psalm-based static analysis

For a detailed comparison, see:

👉 doc/differences-from-apache-log4php.md

🚀 Quick Start

Install via Composer:

composer require xsga/log4php

Basic usage:

use Xsga\Log4Php\Logger;

// Load configuration from an XML file.
Logger::configure('path/to/log4php.xml');

// Obtain a named logger.
$logger = Logger::getLogger('MyApp');
$logger->info('Application started.');
$logger->warning('Disk space running low.', ['threshold' => '90%']);

// Or use the root logger.
$root = Logger::getRootLogger();
$root->debug('Root logger is ready.');

If you prefer to configure the library without XML, you can also pass a PHP array directly to Logger::configure().

⚙️ Basic Configuration

Configuration can be defined using XML or arrays.

XML example:

<?xml version="1.0" encoding="UTF-8" ?>
<configuration xmlns="http://logging.apache.org/log4php/" threshold="all">

  <!-- File appender with pattern layout: one line per event -->
  <appender name="default" class="LoggerAppenderFile">
    <param name="file" value="logs/app.log" />
    <layout class="LoggerLayoutPattern">
      <param name="conversionPattern" value="%date{Y-m-d H:i:s} [%-5level] %message%newline" />
    </layout>
  </appender>

  <root>
    <level value="debug" />
    <appender_ref ref="default" />
  </root>
</configuration>

Programmatic example:

use Xsga\Log4Php\Logger;

Logger::configure([
    'appenders' => [
        'default' => [
            'class' => 'LoggerAppenderFile',
            'params' => [
                'file' => 'logs/app.log',
            ],
            'layout' => [
                'class' => 'LoggerLayoutPattern',
            ],
        ],
    ],
    'rootLogger' => [
        'level' => 'debug',
        'appenders' => ['default'],
    ],
]);

📚 Documentation

Project documentation is currently centered on the repository itself:

Differences from Apache Log4PHP: doc/differences-from-apache-log4php.md
Project documentation: doc/DOCUMENTATION.md

👥 Who should use this

This project is a good fit if you:

Are currently using Apache Log4PHP and need a modern successor with a familiar mental model
Need a PHP 8.4+ logging library with PSR-3 semantics
Want XML-driven logging configuration without giving up programmatic configuration options
Need appenders for local files, rolling files, console output, or Grafana Loki
Prefer a lightweight logging library over larger framework-coupled solutions

📄 License

This project is based on Apache Log4PHP and remains licensed under the Apache 2.0 License. See LICENSE for details.

It includes substantial refactoring, modernization, and new implementation work tailored to the current PHP ecosystem.

🙌 Acknowledgements

Apache Log4PHP
Apache Software Foundation

xsga / log4php

Maintainers

Package info

Statistics

Security