Add a PSR-3 logger, and support any PSR-3 logger

[pbowyer]

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

1. 100% backwards compatibility. xPDO users should not know anything has changed
2. Include a lightweight PSR-3 logger within xPDO, which preserves existing behavior
3. 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

[opengeek]

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… 🤔

[opengeek]

We can remove this conditional logic as 5.4 is well below our support matrix.

[opengeek]

Again, I don't think we need this.

[pbowyer]

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

Or were you thinking more pared back?

[opengeek]

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.