Feature: "academic:upgrade:check" finds dead overrides

Description

EXT:academic_base ships the console command academic:upgrade:check. It compares the Fluid files below one or more project override folders with the files the installed academic extension ships, and reports every file that no longer matches one.

vendor/bin/typo3 academic:upgrade:check academic_persons_edit \
    --override-path=EXT:my_site/Resources/Private/Extensions/AcademicPersonsEdit/

EXT:my_site/Resources/Private/Extensions/AcademicPersonsEdit/
  compared with EXT:academic_persons_edit/Resources/Private/
  x missing-upstream  Templates/Profile/Show.html
  = identical         Partials/Profile/Image.html
  ! case-mismatch     Pages/Academicprogram.html -> Pages/AcademicProgram.html

2 problems and 1 notice in 1 override folder.

Three findings are reported:

Finding	Meaning	Exit status
`missing-upstream`	The extension ships no file at that relative path, not even one differing in case. Fluid never resolves the override.	problem
`case-mismatch`	The extension ships the file under a name that differs only in case. Such an override resolves on a case insensitive file system and is dead on the Linux server next to it.	problem
`identical`	The override is a byte identical copy. It renders, and it freezes the markup of that one file at the version it was taken from.	notice

A changed copy of a file the extension still ships is not reported: it is a deliberate override that works.

The command exits with 1 when at least one problem is reported, with 2 on invalid input, and with 0 otherwise - a notice alone does not fail a pipeline. It only reads; it changes no file.

Naming the folders

extension

Type: string
Required: true

The extension key of the academic extension the overrides belong to, for example academic_persons_edit.

--override-path

Type: string

A folder holding the project overrides, as an EXT: path or an absolute path. May be given more than once. It is compared with EXT:<extension>/Resources/Private/.

--upstream-path

Type: string

The folder the override folders are compared with, when the override folder mirrors a single one rather than Resources/Private/:

vendor/bin/typo3 academic:upgrade:check academic_persons \
    --override-path=EXT:my_site/Resources/Private/Partials/Academic/ \
    --upstream-path=EXT:academic_persons/Resources/Private/Partials/

--site

Type: string

Take the override folders from the TypoScript of that site instead of from the command line, by its site identifier. It may be combined with --override-path.

Taking the folders from a site

With --site the command builds a frontend environment for the site's root page and reads the view root paths the site's TypoScript configures for the extension's plugins - plugin.tx_academicpersons.view.templateRootPaths, partialRootPaths and layoutRootPaths. Each folder is compared with the upstream folder of its own kind, so --upstream-path is not needed there.

vendor/bin/typo3 academic:upgrade:check academic_persons --site=main

A root path is only treated as a project override when it lies outside the checked extension, outside every extension it depends on and outside the TYPO3 system extensions. The partial root paths of the academic plugins name the shared partials of EXT:academic_base, and those of EXT:academic_persons_edit name the partials of EXT:fluid_styled_content; neither is a project override, and reporting them would bury the findings that matter.

The command exits with 2 and names the site when the site does not exist, when its frontend environment cannot be built, when its TypoScript configures no view root path for the extension at all, or when a root path names a folder that does not exist - the last one together with the TypoScript path that named it.

For the page.10 root paths of a site the command is deliberately not used: they are shared with the site's theme, so every theme template would be reported as missing-upstream. Point --override-path at the page template folder instead.

Impact

Integrators get a check they can run before and after an upgrade of the academic extensions, and in continuous integration. Nothing in TYPO3 reports a template override that no longer resolves, so before this command such an override was found by noticing that the frontend no longer looks the way the project configured it.

EXT:academic_base requires fgtclb/environment-state-manager for the --site mode and declares it in composer.json and in ext_emconf.php. The dependency came with 2.4.0, for the internal environment subsystem that 3.0 removed, and 3.0 raises it to version 2, see Important: fgtclb/environment-state-manager 2 is required. Composer managed installations update the package on their own. Classic installations update the environment_state_manager extension to 2.x first.