Add a PSR-3 logger, and support any PSR-3 logger by pbowyer · Pull Request #265 · modxcms/xpdo

pbowyer · 2025-12-29T16:55:54Z

Context and history

In 2015 I opened an RFC to explore adding PSR-3 logging support to MODX.
This was superseded in 2016 by MAB-05 which recommended adopting the PSR-3 Logging Standard.
In 2021 @Mark-H opened Implement a PSR-3 logger #213. While that branch remains open, it provided the conceptual foundation for this implementation.
In late 2025 while developing custom MODX logging output to help with debugging, I realised there was no way to extend logging without modifying core files.

This PR builds on previous efforts to finally resolve those constraints while ensuring 100% backward compatibility.

Goals

100% backwards compatibility. xPDO users should not know anything has changed
Include a lightweight PSR-3 logger within xPDO, which preserves existing behavior
Enable any PSR-3 implementation to be registered with the service container

Implementation

I have integrated psr/log with a simple default implementation. The logic follows a "opt-in" flow:

If a custom PSR logger is provided, xPDO switches to PSR-3 output.
Otherwise, it continues using the legacy xPDO logging logic.

I’ve included exhaustive tests in xPDOLoggingHistoricTest.php to ensure no regressions from the current behaviour.

I started by looking at @Mark-H's branch but I wanted to preserve full backwards compatibility, so used it as inspiration rather than building directly on it. In my code MODX logging works exactly as it currently does, until a custom PSR logger is provided. Once a custom PSR logger is provided, it's assumed that you want PSR-3 output and you opt out of the traditional MODX logging.

Request for feedback

I have added a public property xPDO::$logger. Is this acceptable for ease of use, or should we strictly require the service container for access?
Monolog is a dev dependency purely so the tests can use it as a 3rd-party implementation
I added more code to xPDO than I wished to, and there is some duplication to support the current xPDO logging behaviours. Is this level of duplication acceptable to keep the "legacy" side untouched?
Currently xPDOLogger has a dependency on xPDO. It works, but it feels unclean. Would you prefer a different approach?
I opted not to mark old methods as @deprecated to keep this PR strictly about adding new features. Would you prefer I add those now?

Remaining Todos

Any duplicated tests in xPDOLoggingHistoricTest.php and xPDOLoggerTest.php need rationalising. I am satisfied that xPDOLoggingHistoricTest.php is exhaustive

`initConfig()` sorts out the data, so we don't have to look at `$options` when setting up the logger

opengeek · 2025-12-29T17:07:36Z

Thanks for this work, Peter! I will check this out as soon as possible and get some feedback to you.

opengeek

I'm still considering the necessity of the new methods on the xPDO class. Are these potential overkill? I am wondering if we could simply activate it if a PSR-3 logger was provided in the container… 🤔

src/xPDO/Logging/xPDOLogger.php

src/xPDO/xPDO.php

pbowyer · 2026-01-27T21:38:49Z

I agree, how about something like this: 3.x...pbowyer:xpdo:3.x-psr-logger-take2

Or were you thinking more pared back?

opengeek · 2026-01-30T22:27:26Z

I agree, how about something like this: 3.x...pbowyer:xpdo:3.x-psr-logger-take2

Or were you thinking more pared back?

Yeah, that is looking more like what I had in mind.

resolveLogLocation() in src/xPDO/xPDO.php was added but never used. Keeping it around increases maintenance surface and risk: its logic overwrote any backtrace-derived file with $_SERVER['SCRIPT_NAME'], which would produce misleading log locations if it were ever called. Remove the dead helper to avoid confusion and prevent accidental future use of incorrect location resolution.

When callers omit $file/$line, xPDO::_log() resolves the log location using debug_backtrace(). The default debug_backtrace() captures the full stack (including args), which is unnecessary overhead when we only need the immediate caller's file/line. Use debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 3) to keep the same frame indexing used by the existing logic while avoiding deep/arg-heavy traces. This preserves the resulting file/line values in log output while reducing CPU/memory cost.

pbowyer · 2026-02-01T13:35:59Z

Thanks @opengeek, I've cleaned it up further and merged it into this branch

Extend the change in c6ab4d9 to xPDOLogger

pbowyer · 2026-02-01T17:40:40Z

I've also done another "What if..." branch: 3.x...pbowyer:xpdo:3.x-psr-logger-take3

This lets the xPDOLogger class handle all legacy behaviour, streamlining xPDO.

I've included an optional BC break in a separate commit which removes protected \xPDO\xPDO::_getLogLevel($level). I suspect other code not least MODX relies on this method, but it was too tempting to leave out.

Mark-H · 2026-02-01T22:42:39Z

Lovely to see this moving!

JoshuaLuckers · 2026-02-02T07:13:25Z

Nice work @pbowyer !

opengeek · 2026-02-26T18:38:35Z

FYI @pbowyer — I am experimenting with Copilot reviews on your PR. I'm mostly curious to see the results. Do not take this as feedback to act on immediately.

Copilot

Pull request overview

This pull request adds PSR-3 logging support to xPDO while maintaining 100% backward compatibility. It introduces a lightweight PSR-3 logger implementation (xPDOLogger) that preserves the legacy xPDO logging format, and enables any PSR-3-compliant logger to be registered via the service container.

Changes:

Added psr/log dependency and created xPDOLogger class implementing PSR-3 interface with legacy format preservation
Modified xPDO class to support logger injection via service container while maintaining legacy logging behavior
Added comprehensive test suites covering historic behavior, fatal logging, and new PSR-3 functionality

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
composer.json	Added psr/log dependency (^1.1\|\|^2.0\|\|^3.0) and monolog dev dependency for testing
src/xPDO/xPDO.php	Added logger property and initialization logic, modified _log method to delegate to PSR-3 loggers when available
src/xPDO/Logging/xPDOLogger.php	New PSR-3 logger implementation preserving legacy xPDO log format and behavior
test/xPDO/Test/Logging/xPDOLoggingHistoricTest.php	Comprehensive tests ensuring legacy behavior is preserved
test/xPDO/Test/Logging/xPDOLoggingFatalTest.php	Tests for FATAL level logging with exit behavior
test/xPDO/Test/Logging/xPDOLoggerTest.php	Tests for new xPDOLogger functionality and PSR-3 integration
test/*.phpunit.xml	Added new test files to test suites

Copilot · 2026-02-26T18:42:21Z

src/xPDO/Logging/xPDOLogger.php

+     * @var array
+     */
+    protected $targetOptions = array();
+


The constructor is missing a docblock. Public methods including constructors should have documentation describing their parameters, especially since this accepts an options array with specific expected keys like 'target' and 'target_options'.

Suggested change

/**

* xPDOLogger constructor.

*

* @param xPDO $xpdo The xPDO instance used for configuration and debugging.

* @param array $options Optional logger configuration:

* - 'target' (string|array|null): Log destination or destinations.

* - 'target_options' (array): Options specific to the configured target(s).

*/

Copilot · 2026-02-26T18:42:21Z

src/xPDO/xPDO.php

+            $backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
+            if ($backtrace && isset($backtrace[1])) {
+                $file = $backtrace[1]['file'];
+                $line = $backtrace[1]['line'];


The backtrace depth is incorrect for resolving the caller's file and line. With depth 2, backtrace1 will point to the xPDO::log() method itself, not the actual caller of log().

The call stack is:

[2]: actual caller (what we want)

This should use depth 3 and access backtrace[2] to get the correct calling location, matching the legacy behavior that was removed from lines 2132+ in the original code.

Suggested change

$backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);

if ($backtrace && isset($backtrace[1])) {

$file = $backtrace[1]['file'];

$line = $backtrace[1]['line'];

$backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 3);

if ($backtrace && isset($backtrace[2])) {

$file = $backtrace[2]['file'];

$line = $backtrace[2]['line'];

@copilot code review[agent] Now this one's interesting because the tests pass, and I wrote the tests against the parent branch. So did I get the tests wrong - or have they been silently modified?

Copilot · 2026-02-26T18:42:22Z

src/xPDO/Logging/xPDOLogger.php

+            $this->targetOptions = $options['target_options'];
+        }
+    }
+


The public method handleXpdo is missing a docblock. Public methods should have documentation describing their purpose, parameters, and return values, consistent with other public methods in the codebase.

Suggested change

/**

* Handles logging using the legacy xPDO format.

*

* For fatal log levels, all output buffers are flushed and the script

* exits immediately after writing the formatted log message. For other

* levels, the message is delegated to {@see log()} with a context

* payload that preserves legacy xPDO fields.

*

* @param int|string $level Numeric or string log level (xPDO or PSR-3 style).

* @param string $msg Log message to record.

* @param string $target Optional log target identifier.

* @param string $def Optional log message definition or label.

* @param string $file Optional file name associated with the log entry.

* @param string|int $line Optional line number associated with the log entry.

*

* @return void

*/

opengeek · 2026-02-26T18:48:37Z

Well, that was underwhelming in terms of feedback. 🤔

pbowyer · 2026-02-26T18:49:00Z

FYI @pbowyer — I am experimenting with Copilot reviews on your PR. I'm mostly curious to see the results. Do not take this as feedback to act on immediately.

No problem! Unlike the Gemini code review bot, it looks like with Copilot you can't have a conversation about the changes?

opengeek · 2026-02-26T18:50:34Z

FYI @pbowyer — I am experimenting with Copilot reviews on your PR. I'm mostly curious to see the results. Do not take this as feedback to act on immediately.

No problem! Unlike the Gemini code review bot, it looks like with Copilot you can't have a conversation about the changes?

I thought you could by just mentioning it… hmm

pbowyer · 2026-02-26T18:52:10Z

FYI @pbowyer — I am experimenting with Copilot reviews on your PR. I'm mostly curious to see the results. Do not take this as feedback to act on immediately.

No problem! Unlike the Gemini code review bot, it looks like with Copilot you can't have a conversation about the changes?

I thought you could by just mentioning it… hmm

@opengeek can you try as (I assume) the bot's owner? My mention broke into text...

opengeek · 2026-02-26T18:56:33Z

FYI @pbowyer — I am experimenting with Copilot reviews on your PR. I'm mostly curious to see the results. Do not take this as feedback to act on immediately.

No problem! Unlike the Gemini code review bot, it looks like with Copilot you can't have a conversation about the changes?

I thought you could by just mentioning it… hmm

@opengeek can you try as (I assume) the bot's owner? My mention broke into text...

I guess I am wrong!

Any comments you add to Copilot's review comments will be visible to humans, but they won't be visible to Copilot, and Copilot won't reply.

pbowyer · 2026-02-26T18:58:48Z

cOpiLOt sUcKs

Another open source project I contribute to uses https://developers.google.com/gemini-code-assist/docs/review-github-code which has been rather helpful. Free up to 33 PR a day I believe. And OpenAI has their own too I believe.

opengeek · 2026-02-26T19:00:53Z

cOpiLOt sUcKs

Another open source project I contribute to uses https://developers.google.com/gemini-code-assist/docs/review-github-code which has been rather helpful. Free up to 33 PR a day I believe. And OpenAI has their own too I believe.

I'm going to reserve judgment for now. I had it review my PR yesterday and it was super insightful. I think you just wrote really good code and it is potentially confused on the backtrace level? 😅

pbowyer · 2026-02-26T19:03:05Z

Mine has already been reviewed by AI multiple times before submitting (and I've got AI reviewing the backtrace level locally to confirm) so that could be the case!

Here's an example Gemini code assist review: BadgerHobbs/BinDays-API#182 (review)

opengeek · 2026-02-26T19:04:22Z

Mine has already been reviewed by AI multiple times before submitting (and I've got AI reviewing the backtrace level locally to confirm) so that could be the case!

Here's an example Gemini code assist review: BadgerHobbs/BinDays-API#182 (review)

Nice! This is the kind of AI-assisted contribution I love to see. 🙌🏼

pbowyer · 2026-02-26T19:26:02Z

Copilot was right about debug_backtrace() not being the same as before. I like to think I'd changed it for good reason, but I can't remember if I did 😊 so I've made it match the 3.x behaviour.

I've also updated the alternative 'take3' branch: 3.x...pbowyer:xpdo:3.x-psr-logger-take3 (comparison with this PR: pbowyer/xpdo@3.x-psr-logger...pbowyer:xpdo:3.x-psr-logger-take3)

pbowyer added 7 commits December 29, 2025 16:12

First pass

c39b1a6

Always initialise xPDOLogger; extend tests

5ba82c7

Revisions to clean xPDO

eda4a17

Change composer.json to support PHP 7.2.5+

69a290a

Add logger to the container

ddfba9e

Test legacy logging

a3e952f

Simplify logger initialization

4ade225

`initConfig()` sorts out the data, so we don't have to look at `$options` when setting up the logger

pbowyer added 3 commits December 29, 2025 20:34

Extend historic logging

1d940cd

Fix regression in fatal logging, where the output was incorrect

2b27918

Re-enable xPDOLoggerTest

134e0b4

opengeek reviewed Jan 27, 2026

View reviewed changes

src/xPDO/Logging/xPDOLogger.php Outdated Show resolved Hide resolved

src/xPDO/xPDO.php Outdated Show resolved Hide resolved

pbowyer added 2 commits January 27, 2026 21:13

Strip back additions to xPDO, use PSR3 logger only when in container

44a54dd

Compact into one method

1382862

pbowyer added 3 commits February 1, 2026 11:56

Merge branch '3.x-psr-logger-take2' into 3.x-psr-logger

5cb1309

pbowyer added 2 commits February 1, 2026 13:40

Reduce backtrace overhead further

73c307e

Extend the change in c6ab4d9 to xPDOLogger

Allow psr/log ^3.0

126e675

opengeek added this to the 3.2.0 milestone Feb 26, 2026

opengeek added the feature label Feb 26, 2026

opengeek requested a review from Copilot February 26, 2026 18:34

Copilot started reviewing on behalf of opengeek February 26, 2026 18:34 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

Bugfix: debug_backtrace() was off by 1

4bcbbbb

+    /**
+     * xPDOLogger constructor.
+     *
+     * @param xPDO  $xpdo    The xPDO instance used for configuration and debugging.
+     * @param array $options Optional logger configuration:
+     *                       - 'target' (string|array|null): Log destination or destinations.
+     *                       - 'target_options' (array): Options specific to the configured target(s).
+     */

+    /**
+     * Handles logging using the legacy xPDO format.
+     *
+     * For fatal log levels, all output buffers are flushed and the script
+     * exits immediately after writing the formatted log message. For other
+     * levels, the message is delegated to {@see log()} with a context
+     * payload that preserves legacy xPDO fields.
+     *
+     * @param int|string $level  Numeric or string log level (xPDO or PSR-3 style).
+     * @param string     $msg    Log message to record.
+     * @param string     $target Optional log target identifier.
+     * @param string     $def    Optional log message definition or label.
+     * @param string     $file   Optional file name associated with the log entry.
+     * @param string|int $line   Optional line number associated with the log entry.
+     *
+     * @return void
+     */

Conversation

pbowyer commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context and history

Goals

Implementation

Request for feedback

Remaining Todos

Uh oh!

opengeek commented Dec 29, 2025

Uh oh!

opengeek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pbowyer commented Jan 27, 2026

Uh oh!

opengeek commented Jan 30, 2026

Uh oh!

pbowyer commented Feb 1, 2026

Uh oh!

pbowyer commented Feb 1, 2026

Uh oh!

Mark-H commented Feb 1, 2026

Uh oh!

JoshuaLuckers commented Feb 2, 2026

Uh oh!

opengeek commented Feb 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

pbowyer Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

opengeek commented Feb 26, 2026

Uh oh!

pbowyer commented Feb 26, 2026

Uh oh!

opengeek commented Feb 26, 2026

Uh oh!

pbowyer commented Feb 26, 2026

Uh oh!

opengeek commented Feb 26, 2026

Uh oh!

pbowyer commented Feb 26, 2026

Uh oh!

opengeek commented Feb 26, 2026

Uh oh!

pbowyer commented Feb 26, 2026

Uh oh!

opengeek commented Feb 26, 2026

Uh oh!

pbowyer commented Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pbowyer commented Dec 29, 2025 •

edited

Loading