Apache log4php 2.3.0 介绍与核心概念详解

目标：讲清 Apache log4php 2.3.0 的项目定位、核心架构（Logger/Appender/Layout/Filter/MDC/NDC）与退役现状，并给出与 Monolog、Analog 的选型对比。概念与示例均已在 Ubuntu 22.04 + PHP 8.1 实测通过。重要前提：项目已进入 Apache Attic 退役，终版 2.3.0，仅建议存量维护参考，新项目请选 Monolog 等替代。

一、环境信息

逐项说明：log4php 是纯 PHP 实现，无原生扩展依赖，实测在 PHP 8.1 上基础功能可运行（个别已知缺陷见 FAQ）；源码取自 Apache 归档发行目录，发行包时间戳 2013 年 1 月。

二、log4php 概述

2.1 项目定位与退役声明

Apache log4php 是 Apache Logging Services 旗下面向 PHP 的日志框架，同样源自 log4j 1.x 模型：Logger 层次、Appender、Layout、Filter、MDC/NDC 概念一脉相承，配置文件提供 properties（INI）、XML、PHP 数组三种格式。

必须明确的项目状态：

上表是本文写作与实测的首要结论：log4php 值得学习的价值在于其 log4j 同构的架构思想与存量系统的维护需求，不建议任何新项目引入。

2.2 终版 2.3.0 组成

解压发行包后的目录结构（实测）：

apache-log4php-2.3.0/
├── CHANGELOG  INSTALL  LICENSE  NOTICE  README
├── apidocs/            预生成 API 文档
├── src/main/php/       框架核心（Logger.php 入口）
├── src/examples/php/   33 个官方示例脚本
├── src/site/           文档源
└── src/test/           测试

核心目录 src/main/php 内的类文件（实测列表节选）：Logger.php、LoggerAppender.php、LoggerAppenderPool.php、LoggerAutoloader.php、LoggerHierarchy.php、LoggerLayout.php、LoggerLevel.php、LoggerMDC.php、LoggerNDC.php、LoggerRoot.php，以及 appenders/configurators/filters/layouts/pattern/renderers/xml 子目录——与 log4j 的包结构一一对应。

三、核心架构

3.1 日志处理流水线

业务代码 $logger->info($msg)
  → Logger 按有效级别判断（isEnabledFor）
  → 构造 LoggerLoggingEvent（时间戳、线程号、级别、NDC/MDC、位置信息）
  → Logger 关联的每个 Appender 依次执行 Filter 链
  → Layout 将事件渲染为字符串
  → Appender 写往目标

注意一个实测发现：2.3.0 的 Logger::log() 实现中，additivity 转发分支位于级别判断之外——被本 Logger 过滤掉的消息仍会向上转发给父 Logger 处理并改挂父名，这是与 log4j 语义不同的缺陷（规避方法与验证见集成篇与 FAQ）。

3.2 Logger 与层次结构

root Logger 类为 LoggerRoot，普通 Logger 由 LoggerHierarchy 缓存创建，同名 getLogger 返回同一实例。

3.3 Level 级别体系

log4php 内置级别从低到高：TRACE、DEBUG、INFO、WARN、ERROR、FATAL，另有 OFF。三个过滤点：

3.4 Appender 输出目标

2.3.0 内置 Appender（类名即配置值，实测 filters 目录与官方示例双证）：

💡 技术拓展：同步与异步的分野——2.3.0 没有异步 Appender，全部 Appender 在调用线程内同步写出，高并发 Web 请求下文件 IO 抖动会直接放大到业务耗时；这是它与后续现代框架（如 Monolog 组合 handler）的代差之一。本文实测以同步 Console/RollingFile 为主。

3.5 Layout 日志布局

💡 技术拓展：Pattern 与 JSON 的取舍在 log4php 上很现实——2.3.0 没有内置 JSON 布局，实测配置 LoggerLayoutJson 直接告警回退：log4php: Nonexistant layout class [LoggerLayoutJson] specified for appender [jsonAppender]. Reverting to default layout.。结构化输出只能用 LoggerLayoutPattern 手工拼 JSON 行（实测用 %d/%p/%c/%X{key} 拼出合法 JSON），或者选 Monolog 的 JsonFormatter。本文实测两种方式均有验证。

3.6 Filter 过滤器

Appender 内 Filter 链（XML/数组配置），返回 NEUTRAL/ACCEPT/DENY：

实测验证（XML 配置 LevelMatchFilter 匹配 WARN + DenyAllFilter 收口）：INFO/WARN/ERROR 三条仅 WARN 输出，行为与 log4j 一致。

3.7 MDC 与 NDC

实测验证：MDC 写入 userId 后，PatternLayout 的 %X{userId} 输出 admin；LoggerLayoutXml 的事件里出现 properties 元素（data name=userId value=admin）与 NDC 元素。

四、功能特性

1. 三种配置格式：INI/properties、XML、PHP 数组（Composer 数组配置实测通过）。
2. log4j 同构：概念、配置语法、Pattern 转换符与 log4j 1.x 高度一致，Java 背景零学习成本。
3. Appender 覆盖面广：文件、滚动、数据库、邮件、MongoDB、Socket、Syslog 等 12 类。
4. MDC/NDC 双上下文：Web 请求级上下文注入完整可用。
5. 可扩展点齐备：自定义 Appender/Layout/Filter/Renderer（renderers 目录含默认与映射渲染器）。
6. 轻量：核心纯 PHP 单包，无强制扩展依赖，include Logger.php 即用。
7. 历史包袱明确：终版 2.3.0 停止维护于 2013 年，无安全更新（最重要的一条，决定其定位）。

五、适用场景

六、同类选型对比

PHP 生态日志选型对比（log4php vs Monolog vs Analog）：

选型建议：

1. 新项目一律 Monolog——PSR-3 兼容、JSON 结构化、生态最广，Laravel/Symfony 内置。
2. 极小脚本、不想引依赖——Analog 单文件可用。
3. 团队需要 log4j 心智统一——学概念用 log4php 案例可以，写生产请把概念平移到 Monolog 的 Handler 体系。
4. 存量 log4php 系统——维持冻结版本、封堵外部输入解析面、按本文 FAQ 排查已知缺陷，逐步迁移计划列入技术债。

七、常见问题（FAQ）

Q1：log4php 还能用于新项目吗？ A：不能。项目已进入 Apache Attic 退役，终版 2.3.0 停止于 2013 年，无任何安全维护；实测 Composer 安装时官方仓库明确输出 Package apache/log4php is abandoned, you should avoid using it. 新项目请选 Monolog 等替代。

Q2：log4php 2.3.0 在 PHP 8.1 上能跑吗？ A：基础功能实测可以：Logger 加载、properties/XML/数组三种配置、Console 与 RollingFile 输出、Filter 均正常，未见致命错误。但这是"能跑"而非"受支持"——退役版本没有针对 PHP 8.x 的官方兼容承诺，生产使用风险自担。

Q3：给子 Logger 运行时 setLevel(INFO) 后，DEBUG 消息为什么还输出了，而且 Logger 名变成了父 Logger？ A：这是 2.3.0 的实现缺陷。实测复现：setLevel(INFO) 后 $daoLogger->debug(...) 仍输出且 logger 名显示为父 Logger。根因在 Logger::log() 源码——additivity 转发分支写在 isEnabledFor 判断之外，被过滤的消息仍会转发给父 Logger 并以其名义重建事件。规避：为该 Logger 配置 additivity=false（实测该行彻底消失），或不用运行时 setLevel、改在配置文件里定级。

Q4：配置里写了 LoggerLayoutJson 为什么报错？ A：实测报 log4php: Nonexistant layout class [LoggerLayoutJson] specified for appender [jsonAppender]. Reverting to default layout.——2.3.0 没有 JSON 布局，内置布局只有 Simple/Pattern/TTCC/Html/Xml 五种。要 JSON 行只能用 PatternLayout 手拼，或换 Monolog 用 JsonFormatter。

Q5：logger 配置了级别但没配 appender，行为对吗？ A：合法且常用——只收紧级别不挂输出端（实测 properties 写 log4php.logger.X=INFO）。但结合 Q3 的缺陷，建议同时写 additivity=false，否则被过滤的消息会经叠加通道漏到父 Logger 输出。

Q6：为什么同一条日志输出两次？ A：additivity 叠加：Logger 自己的 Appender 输出一次，事件再传父 Logger 的 Appender 又一次。实测 XmlDemo 的 ERROR 重复出现两次，给该 logger 加 additivity="false" 后恢复单条。

Q7：%t 输出的是什么？ A：2.3.0 的线程概念映射为进程 PID（实测 [8364] 与进程号一致），PHP 是单线程模型，日志里它起"请求标识"作用，Web 环境建议用 %X{requestId} 之类的 MDC 键替代。

Q8：Composer 安装报 zip 相关错误怎么办？ A：实测报 The zip extension and unzip/7z commands are both missing, skipping.——composer 解包发行 zip 需要 PHP zip 扩展或系统 unzip。安装 php-zip（或 apt install unzip）后重试即可。

Q9：DailyFile 与 RollingFile 的滚动语义差在哪？ A：RollingFile 按大小切（maxFileSize 触发，maxBackupIndex 保留个数，实测 roll.log.1~.3）；DailyFile 按日期切（datePattern 模板，一天一个文件，不按大小）。高频日志建议 Rolling 限总量，归档需求用 Daily。

Q10：从 log4php 迁移到 Monolog，概念怎么对应？ A：Logger 对应 Logger；Appender 对应 Handler；Layout 对应 Formatter；Filter 对应 Handler 的 level/processor 或自定义 Handler；MDC 对应上下文数组与 processors；配置文件驱动对应代码内 pushHandler 组合。四件套思想可平移，API 风格换成面向对象的管道式。

八、参考链接

1. Apache Attic（已退役项目名录）：https://attic.apache.org/
2. log4php 归档发行目录（2.3.0 源码）：https://archive.apache.org/dist/logging/log4php/2.3.0/
3. log4php 归档站点快照（API 文档）：https://logging.apache.org/log4php/
4. Composer 包页（abandoned 标记）：https://packagist.org/packages/apache/log4php
5. Monolog（替代方案）：https://github.com/Seldaek/monolog
6. PSR-3 日志接口规范：https://www.php-fig.org/psr/psr-3/