[TASK] Declare psr/log in the packages that use it

[CybotTM]

Problem

Seven packages use PSR-3 in their production code without requiring it. Psr\Log\LoggerInterface is a required constructor argument in classes such as ParseFileHandler, and Psr\Log\LogLevel is read in the DI extension — but no package's require mentions psr/log. packages/guides declares it under require-dev, which does not cover production use.

It resolves today because symfony/http-client (a require of phpdocumentor/guides) and monolog/monolog (a require of phpdocumentor/guides-cli) both pull psr/log in. That is a stable path, not a coincidence, but it is undeclared: if either dependency is dropped or makes psr/log optional, every LoggerInterface type hint breaks at autoload time and Composer will not have warned about it. Since each package is sub-split into its own published package, the indirection becomes a consumer's problem rather than this repository's.

Changes

psr/log: ^1.0 || ^2.0 || ^3.0 added to require of guides, guides-cli, guides-code, guides-graphs, guides-markdown, guides-restructured-text and guides-theme-bootstrap. For packages/guides this is a move out of require-dev.

The range is deliberately the one symfony/http-client already allows, so no consumer loses a resolution it has today and nothing here needs to be excluded from a 1.0 backport. It is also what phpdocumentor/dev-server already declares in this repository.

That range is safe for the code as written: only LoggerInterface and LogLevel are used, both unchanged across the three majors, and no class in any package implements LoggerInterface — which is where a v1/v3 signature difference would bite.

Verification

composer-require-checker is present in .phive/phars.xml but is not invoked by any workflow, composer script or Makefile, so nothing currently detects this class of defect. I ran it manually as a controlled before/after on a standalone install of guides-code, the smallest affected package: without the declaration Psr\Log\LoggerInterface is listed as an unknown symbol, with it the symbol is gone.

Full suite on the branch: 828 tests, no failures. Also run with --prefer-lowest, which resolves psr/log to 2.0.0 and passes. composer validate --strict passes for the root and every package.

Note on the lock

The lock refresh carries three corrections that were already stale before this branch: scrivo/highlight.php in guides-code, and the doctrine/deprecations and phpdocumentor/guides-restructured-text entries in guides-theme-bootstrap. They are a side effect of composer update --lock, not edits to those composer.json files.

Out of scope

An earlier revision of this branch also added fig/log-test to the require-dev of guides-code and guides-restructured-text, whose tests use Psr\Log\Test\TestLogger. That is dropped: every package marks /tests export-ignore, so the published packages contain no tests and the declaration would describe a dependency nothing in the package uses. The root composer.json, where the tests actually run, already declares it.

The same tool run against guides-code reports further unknown symbols beyond Psr\Log, among them Symfony\Component\DependencyInjection\*, Symfony\Component\Config\*, Twig\* and phpDocumentor\Guides\*. That is the same class of defect at a larger scale and some of it may be deliberate for optional integrations, so it is left alone. Happy to open an issue, or to wire composer-require-checker into CI so it stops recurring.

Assisted by claude-code:claude-fable-5 — Session

[linawolf]

We are currenlty requiring "symfony/http-client": "^6.4.9 || ^7.4 || ^8", which allow psr/log: ^1|^2|^3

Adding "psr/log": "^3.0" to our requirements could be a breaking change for some Projects and could therefore not be backported to Guides 1.0.

[CybotTM]

You are right, and ^3.0 was the wrong call. 2e4c765 changes it to ^1.0 || ^2.0 || ^3.0, which is exactly what symfony/http-client already allows, so no consumer loses a resolution it has today and nothing here blocks a 1.0 backport. It is also the range phpdocumentor/dev-server already declares in this repository, so the convention was there to follow.

The range is safe for the code as written, which I checked rather than assumed: the production code uses only Psr\Log\LoggerInterface and Psr\Log\LogLevel, both unchanged across the three majors, and no class in any package implements LoggerInterface — that is the place where the v1 versus v3 signature difference would actually bite.

Also dropped from this branch: the fig/log-test entries I had added to the require-dev of guides-code and guides-restructured-text. Every package marks /tests export-ignore, so the published packages ship no tests and that declaration would name a dependency nothing in the package uses. The root composer.json, where the tests do run, already declares it.

Branch rebased on current main. Full suite 828 tests, no failures, and green again with --prefer-lowest, which resolves psr/log to 2.0.0.

Assisted by claude-code:claude-fable-5 — Session

[CybotTM]

Copilot has no review quota left this month, so no bot review was possible on this head. Reviewed it myself instead; here is what was checked rather than assumed.

The mapping is exact and complete. Ten packages, eight of which use Psr\Log in their production src: dev-server (3 files), guides (19), guides-restructured-text (22), guides-markdown (13), guides-theme-bootstrap (4), guides-cli (3), guides-graphs (3), guides-code (1). All eight now declare it — dev-server already did, the other seven are this diff. The two that do not use it, filesystem and guides-theme-rst, are correctly left alone. No package is missing from the change and none declares a dependency it does not use.

The constraint is not a narrowing. symfony/http-client requires psr/log: ^1|^2|^3 and monolog/monolog requires ^2.0 || ^3.0; this declares ^1.0 || ^2.0 || ^3.0, so every resolution a consumer can reach today stays reachable. phpdocumentor/dev-server already carried the same range in this repository.

The range is safe for the code as written. Only LoggerInterface and LogLevel are used, both unchanged across the three majors, and no class in any package implements LoggerInterface — which is the one place where the v1 and v3 signatures differ.

Verified with the tool the repository already ships. composer-require-checker run per split package in isolation, each with its own composer install: Psr\Log\LoggerInterface no longer appears for any of the seven. Worth noting for whoever picks this up next: the composer-require-checker version pinned in .phive/phars.xml, 3.5.1, aborts on symfony/config v8 with a parse error, so the runs above used composer-require-checker 4.24.0.

Full suite 828 tests, no failures. PHPStan and PHPCS clean. composer validate --strict passes for the root and every package. Rebased on current main.

One CI note that is not about this change: the xml-lint job has been stuck in Install libxml2-utils since 15:23 and never reached tools/xmllint.sh. This branch touches no XML — only seven composer.json files and the lock — and the same job passed on #1338 an hour earlier. It needs a re-run rather than a fix.

Assisted by claude-code:claude-fable-5 — Session