[TASK] Raise minimum PHP to 8.2, update DDEV to PHP 8.2 and Node.js 20

[CybotTM]

Summary

Raises the project-wide minimum PHP version from 8.1 to 8.2, updates DDEV local development environment, and ensures all sub-packages declare proper PHP and extension requirements.

Changes

PHP 8.2 minimum across the board:

• Root composer.json: php ^8.2, platform 8.2.28
• All sub-packages (typo3-api, typo3-docs-theme, typo3-guides-cli, typo3-guides-extension, typo3-version-handling): added/updated php: ^8.2
• Added symfony/polyfill-php82 to replace section
• PHPStan: phpVersion: 80200
• PHP-CS-Fixer: @PHP82Migration
• CI matrix: dropped PHP 8.1, default set to 8.2
• Dockerfile: php:8.2-cli-alpine

Sub-package ext-* declarations completed:

• typo3-docs-theme: added ext-dom (uses DOMDocument)
• typo3-guides-cli: added ext-simplexml (uses SimpleXMLElement)
• typo3-version-handling: added ext-curl (uses curl functions)

DDEV update:

• PHP 8.1 → 8.2
• Node.js 18 → 20

Dependency updates:

• Full composer update to pull in newer package versions compatible with PHP 8.2+
• Integration test expected outputs updated for phpdocumentor/guides 1.9.6 rendering changes

Files changed (16)

File	Changes
.ddev/config.yaml	PHP 8.2, Node.js 20
.github/workflows/main.yaml	DEFAULT_PHP_VERSION 8.2, drop 8.1 from matrix
.github/workflows/docker-test.yaml	DEFAULT_PHP_VERSION 8.2
.php-cs-fixer.dist.php	@PHP82Migration
Dockerfile	php:8.2-cli-alpine
composer.json	php ^8.2, platform 8.2.28, polyfill-php82 replace
composer.lock	Full update for PHP 8.2 platform
packages/typo3-api/composer.json	php ^8.2
packages/typo3-docs-theme/composer.json	php ^8.2, ext-dom
packages/typo3-guides-cli/composer.json	php ^8.2, ext-simplexml
packages/typo3-guides-extension/composer.json	php ^8.2
packages/typo3-version-handling/composer.json	php ^8.2, ext-curl
phpstan.neon	phpVersion: 80200
tests/.../admonitions/expected/index.html	Updated for guides 1.9.6
tests/.../md-admonitions/expected/README.html	Updated for guides 1.9.6
tests/.../readme/expected/logs/warning.log	New expected warning

[linawolf]

Our decision is to align with the lowest supported PHP version to ensure we catch incompatible language features during local development.

We will drop PHP 8.1 and standardize on PHP 8.2. Even TYPO3 v14 supports PHP 8.2, so there is no need to target anything higher at this time.

[CybotTM]

Our decision is to align with the lowest supported PHP version to ensure we catch incompatible language features during local development.

Ok your choice, nothing I can do about it. But I do not agree on your reasoning.

Aligning DDEV to the lowest supported PHP version (8.2) does not actually “ensure we catch incompatible language features.”

Running 8.2 locally only prevents accidentally using features newer than 8.2. It does not prevent incompatibilities within the supported range (8.1^), and it does not guarantee compatibility with 8.4 or 8.5.

Compatibility across the supported PHP range is ensured by CI and automated tests, not by fixing a single local runtime version.

Therefore, choosing 8.2 vs 8.5 in DDEV does not inherently prevent incompatible code — it only changes which version developers happen to execute locally.

It just gives you an outdated development environment.

We will drop PHP 8.1 and standardize on PHP 8.2. Even TYPO3 v14 supports PHP 8.2, so there is no need to target anything higher at this time.

You cannot compare a framework with a tool on this matter - they have fundamental different requirements regarding supported RTE.

I don’t think the TYPO3 comparison is directly applicable here. TYPO3 is a production framework and must strictly align with customer runtime constraints.

This repository is a development tool with a controlled runtime (DDEV) and platform.php pinning dependency resolution. Its runtime choice does not affect consumer environments.

Therefore the PHP version decision here is about developer tooling strategy, not framework compatibility guarantees.

A framework must be conservative.
A toolchain should usually be progressive.

[CybotTM]

Just another note on this repo:

One structural concern: we’re mixing two different models.

composer.json declares a wide PHP support range (8.2–8.5), which is a library-style signal (“many environments are valid”). But the repo also ships a pinned environment via composer.lock and the container/DDEV config, which is an application/tool-style signal (“this exact stack is the supported way to run it”).

For a tool repo, I’d recommend choosing one: either (a) treat the container/lock as the canonical supported environment and narrow the declared runtime expectations accordingly, or (b) drop the “pinned tool” stance and truly embrace wide-environment support. Keeping both increases maintenance and support burden without clear benefit.

So we have the bad form two worlds: need to support a broad range of versions but using old tools/libs.

[CybotTM]

I rewrote the whole PR ... i should have made a new one, but was already half the way ... ;-)

[linawolf]

composer.json declares a wide PHP support range (8.2–8.5), which is a library-style signal (“many environments are valid”). But the repo also ships a pinned environment via composer.lock and the container/DDEV config, which is an application/tool-style signal (“this exact stack is the supported way to run it”).

There is a difference between the complete project delivered in the docker container, running on a specific PHP version and the possibility to use the packages developed in this mono reposistory independently.

Please also change the minimum requirements in the composer.json files of the other packages in folder "packages" to the new requirements. That way we can completely drop the php 8.1 dependency.

[CybotTM]

Hi @linawolf

There is a difference between the complete project delivered in the docker container, running on a specific PHP version and the possibility to use the packages developed in this mono reposistory independently.

Yes, root composer.json is for the tool and packages/*/composer.json is for the libs.
Tool should have a focused RTE, libs should support broader range - exactly as I wrote.

Please also change the minimum requirements in the composer.json files of the other packages in folder "packages" to the new requirements. That way we can completely drop the php 8.1 dependency.

There is only one PHP ^8.1 requirement, all other do ... support PHP 4 to 9 !? ;-)

[linawolf]

You are right! I guess by requiring the phpdocumento/guides libaries they would not be installable with PHP 4, but it would be better to also require PHP 8.2 there. Would you like to add the requirement?