Upgrade plan — Symfony 6.4 → 7.1 → 7.2 → 7.3 → 7.4 + API Platform 3.4 → 4.x #8723

Context

Chamilo 2.0 currently runs on Symfony 6.4 LTS (PHP 8.2) with api-platform/core 3.4.17. This issue tracks the upgrade plan to Symfony 7.4 LTS (stepping through 7.1 → 7.2 → 7.3 → 7.4) and API Platform 4.x, landing in the Chamilo 3.0 release. Preparation PRs are tagged with this milestone.

Verified requirements (July 2026)

Out of scope: Doctrine ORM 3 / DBAL 4 (staying on ORM 2.20 / DBAL 3.10, supported by both targets), PHPUnit 10/11, Symfony 8 (requires PHP 8.4).

Composer blockers (verified with composer why-not)

All other third-party bundles installed already support Symfony 7 (a2lix 3.2.4, gregwar/captcha-bundle 2.5, lexik-jwt 2.21, vich, stof, oneup-flysystem, knpu-oauth2, fos-jsrouting, nelmio-cors, reset-password, security-acl 3.4, glide-symfony 2.1, monolog-bundle, gedmo 3.22, doctrine-bundle 2.18).

Code inventory

The codebase is already in good shape for SF7 (0 ContainerAware, 0 getDoctrine(), 0 @ORM annotations, security already on SecurityBundle\Security, 35 commands on #[AsCommand]). Remaining work:

• 3 normalizers implementing ContextAwareNormalizerInterface (removed in 7.0) and missing getSupportedTypes(): src/CoreBundle/Serializer/{Document,Glossary,StudentPublicationComment}AiAssistedNormalizer.php.
• 69 soft-deprecated $request->get() calls in 19 files under src/.
• src/CoreBundle/Controller/AccessUrlController.php imports ApiPlatform\Api\IriConverterInterface (removed in AP4).
• config/packages/api_platform.yaml exception_to_status maps two legacy ApiPlatform\Core\Exception\* classes (AP4 boot blocker).
• 86 Put operations across 60 files, none with standard_put — in AP4, PUT becomes unconditional replace, which breaks the Vue SPA's partial payloads.
• Central Vue error handler assets/vue/services/api.js (toServiceError) plus ~33 views read hydra:description/hydra:title without an RFC 7807 detail/title fallback (AP4 default error format).
• SYMFONY_DEPRECATIONS_HELPER=999999 in .env.test currently masks all deprecations.

Phase plan

Track A (Symfony)             Track B (API, parallel from day 1)
F0.1 deprecation visibility   F0.5 RFC 7807 on AP 3.4 + api.js fallbacks
F0.2 composer companions      F0.6a PUT→PATCH Forum (22 ops)
F0.3 SF7-ready code fixes     F0.6b PUT→PATCH Attendance/Document/Link
F0.4 settings-bundle fork     F0.6c PUT→PATCH remaining (~55 ops)
      └──► H1 (7.1) → H2 (7.2) → H3 (7.3) → H4 (7.4) ──► F-AP4 (needs H4 + Track B)

Every PR is independently mergeable into master. H1 requires F0.1–F0.4. Track B only blocks the final AP4 phase.

Phase 0 — groundwork on 6.4

• PR-0.1: make deprecations visible — .env.test → SYMFONY_DEPRECATIONS_HELPER='max[self]=0&max[direct]=999999&verbose=1' (or a committed baseline file), plus a monolog handler for the deprecation channel in dev.
• PR-0.2: composer companions (all dual-compatible 6.4/7.x): drop proxy-manager-bridge; bump knp-components ^4, webpack-encore-bundle ^2.2, carbon ^3, dama ^8.0. Adapt PaginationSubscriber.php (+ question_pool.php, gradebook_list.php, questions.php) and TimestampableAgoTrait.php (write an "ago" unit test before the Carbon 3 bump — diff*() behavior changed).
• PR-0.3: forward-compatible code fixes — migrate the 3 ContextAwareNormalizerInterface normalizers (template: src/CoreBundle/Serializer/Normalizer/UserNormalizer.php); replace the 69 $request->get() calls; repoint IriConverterInterface and the two exception_to_status legacy classes to ApiPlatform\Metadata\* (both new namespaces already exist in 3.4).
• PR-0.4: fork work on chamilo/SyliusSettingsBundle — constraints symfony ^6.4|^7.0, php ^8.2; SF7 sweep (native return types on form types, DI extension/compiler passes, Twig extensions, event subscribers); run the bundle suite against 6.4 (--prefer-lowest) and 7.x (SYMFONY_REQUIRE=7.1.*); tag v1.4.0, then bump chamilo/settings-bundle ^1.4 here. Plan B if the fork proves unviable: absorb the bundle into src/CoreBundle/Settings/Bundle/ under a Chamilo\ namespace (all 77 consumers already live in src/CoreBundle/Settings/).
• PR-0.5 (Track B): adopt RFC 7807 already on AP 3.4 — defaults.extra_properties.rfc_7807_compliant_errors: true (the key AP4 expects); add data.detail || data["hydra:description"] / data.title || data["hydra:title"] fallbacks in toServiceError() and sweep the 67 hydra:description usages (centralizing where possible). Keep serializer.hydra_prefix: true — the SPA depends on hydra:member/hydra:totalItems/hydra:view.
• PR-0.6a/b/c (Track B): PUT→PATCH migration. Audit each of the 86 Put ops: partial Vue payload → add Patch (merge-patch is already configured) and switch the caller; full-object payload → keep Put with extraProperties: ['standard_put' => true]; no caller → PATCH by default. Order by volume: 0.6a Forum (CForumPost 7, CForumThread 6, CForum 5, CForumCategory 4), 0.6b CAttendance/CDocument/CLink, 0.6c the rest. Backend + Vue caller in the same PR. Goal: zero Put without standard_put before the AP4 flip, with ApiTestCase regression tests (PATCH must not reset absent fields).

H1 — 6.4 → 7.1 (the big hop: absorbs all 7.0 removals)

composer.json: all symfony/* 6.4.* → 7.1.* + extra.symfony.require, then composer update "symfony/*" --with-all-dependencies and composer recipes:update (review recipe diffs one by one). Main risk: native parameter/return types added to Symfony 7.0 interfaces — incompatible signatures in our voters/subscribers/form types/Twig extensions are fatal, not deprecations; caught by PHPStan/Psalm + lint:container + prod cache warmup. Runtime checks: gradebook export (SonataExporterBundle bridge has no direct symfony constraint) and legacy public/main/ pages (static service locator Chamilo\CoreBundle\Framework\Container, 36 usages in api.lib.php) — if a get() fails, add a targeted public: true alias.

H2 / H3 — 7.1 → 7.2 → 7.3 (short hops)

Same mechanics. Known items: session sid_length/sid_bits_per_character options (7.2); UserInterface::eraseCredentials() deprecation affects src/CoreBundle/Entity/User.php (7.3); Console invokable-command deprecations vs our 35 commands (7.3).

H4 — 7.3 → 7.4 LTS (final destination)

7.4 deprecates everything 8.0 removes → the gate here is zero self+direct deprecations from src/ and public/main/. Afterwards harden .env.test to max[self]=0&max[direct]=0 permanently. Keep phpstan 1.x / psalm 5.x unless actually broken (tooling bumps as separate follow-up).

F-AP4 — API Platform 3.4 → 4.x (requires H4 + Track B)

1. api-platform/core: ^4.2 (stay on the metapackage; the api-platform/symfony + api-platform/doctrine-orm split is an optional follow-up).
2. api_platform.yaml: drop keep_legacy_inflector; rfc_7807_compliant_errors already under defaults.extra_properties; keep hydra_prefix: true.
3. Adapt the 8 custom filters in src/CoreBundle/Filter/ (CidFilter, SidFilter, ExtraFieldFilter, GlobalEventFilter, ParentNullFilter, PartialSearchOrFilter, SocialWallFilter, UserExtraFieldFilter) to the new AbstractFilter constructor signature.
4. PHPStan sweep over the 77 state providers + 74 processors + 23 query extensions (namespaces persist; only signatures may change).
5. GraphQL: unused in this project → no action.

Verification gate (every PR/hop)

composer validate
php bin/console cache:clear && php bin/console lint:container && php bin/console lint:yaml config/
php bin/console debug:container --deprecations
composer phpcs && composer phpstan && composer psalm
php bin/phpunit
vendor/bin/behat tests/behat/features/    # full suite on hops; forum/documents features on PUT→PATCH PRs
yarn build                                 # PRs touching Vue

Manual smoke: admin login/dashboard → save a setting in /admin/settings (settings-bundle fork) → course documents upload/rename/delete → forum create/edit post (PATCH) → question pool + gradebook list (Knp pagination) + gradebook export (Sonata) → any legacy public/main/ page in course context (Container::) → trigger a Vue form validation error (error format).

Hop gate: zero self+direct deprecations from our code (vendor-indirect ones are recorded), green QA gates, smoke OK.

Residual risks

• Settings-bundle fork harder than expected → timebox + plan B (absorb into monorepo).
• Carbon 3 diff* output / knp-components 4 pagination events → tests written before the bumps.
• RFC 7807 breaking uncovered Vue views → dual fallback centralized in toServiceError; flag is reversible on 3.4.
• New AP4 AbstractFilter signature side effects on cid/sid filters → naturally covered by Behat (course context on every request).