Upgrading from 2.4 to 3.0.0

Version 3.0.0 changes the shape of Configuration/AcademicPersons/Settings.yaml, the public detail template and - together with fgtclb/academic-persons-edit - the complete profile editing frontend. Each of those changes carries its own changelog entry with the detail; this page is the order they have to be applied in.

The order matters. One wizard reads a database column TYPO3 v14 no longer has, and one repairs relations the new editor then writes. Work through the steps from top to bottom, on a copy of the production database first.

The steps at a glance

Step	What it does	What happens if it is skipped
Update the packages	Installs 3.0.0 of every academic extension of the installation.	Nothing below applies.
Run the plugin migration wizards, still on TYPO3 v13	Moves the `list_type` plugin records onto their own `CType`.	The content elements stop rendering on TYPO3 v14, where the column the wizards read no longer exists.
Update the database schema	Applies the column changes of 3.0.0, among them the unsigned timeline year columns and the workspace columns.	The wizard of step 4 finds no repaired schema and the editor writes into columns the installation does not have.
Repair the profile image relations	Reduces duplicate references, corrects relation counters and marks the translations that carry an image of their own.	A translation loses its own image at the next synchronisation, and duplicate references keep rendering the wrong file.
Migrate the settings override	Replaces the pre-3.0 keys of a site package with the section maps.	The installation runs on the legacy overlay, which is removed in 4.0 - and a renamed `type` or `fieldName` stays silently broken.
Adapt templates, icons and TypoScript	Re-applies project overrides to the new template tree and makes the JSON page type reachable.	The editor cannot save, and an overridden detail view loses the configurable layout.

Note

The TYPO3 core update itself is not a step of this page; it is an upgrade of its own with its own manual. Where it belongs matters for exactly one step: the plugin migration wizards of step 2 read a column TYPO3 v14 no longer declares, so the core update comes after step 2. Every other step works the same on TYPO3 v13 and on v14.

1. Update the packages

The academic extensions are released together and depend on each other, so they are updated in one go:

composer require 'fgtclb/academic-persons':'^3' 'fgtclb/academic-persons-edit':'^3'

In a classic (non-Composer) installation, update every academic extension in the Extension Manager and activate rte_ckeditor, which academic_persons_edit requires for its rich text fields since 3.0.0.

Flush all caches afterwards. The settings graph is cached in the core cache and the cache identifier changed with the file format, so a stale entry is not read back - but the TypoScript and TCA caches are.

2. Run the plugin migration wizards while still on TYPO3 v13

academicPersons_MigrateListTypeToCTypeContentElements and academicPersonsEdit_pluginContent move the content elements of both extensions from CType = list plus list_type onto their own CType. Both read tt_content.list_type, and TYPO3 v14 removed that column.

vendor/bin/typo3 upgrade:run academicPersons_MigrateListTypeToCTypeContentElements
vendor/bin/typo3 upgrade:run academicPersonsEdit_pluginContent

Run them on TYPO3 v13, before the core update. TYPO3 v14 removed tt_content.list_type from the TCA, so the database analyzer of a v14 installation offers the column for removal and a fresh v14 installation never has it. Both wizards ask the live schema: once the column is gone their content element half finds nothing to do, and the records they would have migrated keep a content type nothing renders. The academicPersons_ wizard also migrates the explicit_allowdeny values of the backend user groups, and that half stays available on both versions.

Warning

academicPersons_MigrateListTypeToCTypeContentElements is not repeatable: a wizard that reports "nothing to do" is recorded as done and disappears from the upgrade module. That is why this step names both wizards instead of running a bare vendor/bin/typo3 upgrade:run - a bare run on TYPO3 v14, with the column already removed, marks the wizard as done although it migrated nothing. The flag is cleared with

vendor/bin/typo3 upgrade:mark:undone academicPersons_MigrateListTypeToCTypeContentElements

but that only helps while tt_content.list_type still holds the values. Once the column is dropped, nothing records which plugin such a content element was, and the records have to be repaired by hand.

academicPersonsEdit_removeProfileSwitcherContent deletes the content elements of the removed profile switcher plugin and handles both shapes, so it can be run on either core version.

3. Update the database schema

vendor/bin/typo3 extension:setup

In the backend the same thing is Admin Tools > Maintenance > Analyze Database Structure. It applies every column change of 3.0.0. Nothing is converted here and no value is rewritten: the timeline keeps its year, year_start and year_end columns, which only turn unsigned because the corrected TCA declares a lower bound of 0.

Note

The analyzer reports a column that left ext_tables.sql as unused and never drops it on its own. Accepting such an offer is a decision of the installation, not a step of this upgrade.

4. Repair the profile image relations

Only relevant where academic_persons_edit is installed, and only worth running where profiles have images.

vendor/bin/typo3 upgrade:run academicPersonsEdit_repairLocalizedProfileImages

The profile image column is translatable from 3.0.0 on. Until then it was excluded from localisation and the upload path wrote the relation rows by hand, which left three shapes behind that are defects under the new model: duplicate references on one profile, a relation counter that disagrees with the number of references, and a translation carrying its own reference without the custom localisation state - the state that keeps the next synchronisation from replacing it with a localisation of the default-language image.

The wizard repairs all three through the TYPO3 DataHandler, so the reference index, the record history and the localisation state are the core's. No file is deleted; a file left without a relation is for the unused files tooling of the Install Tool to report. Prefer the command line over the Install Tool module for it.

Run it after step 3 and before editors start working in the new editor of a multilingual installation. It is repeatable as well; where a 3.0.0 pre-release recorded it as done, vendor/bin/typo3 upgrade:mark:undone academicPersonsEdit_repairLocalizedProfileImages offers it again. See Breaking: The profile image translates.

5. Migrate the settings override

Only relevant for an installation whose site package ships Configuration/AcademicPersons/Settings.yaml.

The pre-3.0 top-level keys validations and profileInformationsTypes are mapped onto the four section maps at runtime, with a warning in the log, so such a file keeps working. The overlay is transitional and is removed in academic_persons 4.0.

vendor/bin/typo3 academic:persons:settings:migrate

The command prints, for every active package that still ships a legacy key, the profile, special, contracts and documentSections maps the overlay produces - the document that replaces the legacy keys of that package. It never writes the file, and it exits with 1 while such a package exists, so a deployment pipeline can gate on it. Paste the printed maps into the site package, review them, and flush all caches.

Warning

Read the notes the command prints. A renamed type or fieldName of a legacy profileInformationsTypes entry is not applied, and is reported instead: since 3.0.0 the seven profile relations and the record type each of them selects are declared by the TCA of the profile table, and applying such a rename would move the editing frontend alone, leaving the backend column and the editor writing different record types. The section keeps the values that match the TCA, so the installation is consistent - but the intention of the override is silently not honoured. A timeline type of your own needs its own column in a TCA override of the profile table, and its section under documentSections - see The document sections. The same applies to a type or fieldName written directly into the new documentSections map: that one is read, and it is the shape that diverges from the TCA.

Migrating a pre-3.0 override has the complete key mapping and what is deliberately not mapped; Breaking: Section-based AcademicPersons settings describes the new shape.

6. Adapt templates, icons and TypoScript

The public detail view

Resources/Private/Templates/Profile/Detail.html was rewritten: it is a dispatcher over the profile.structure and profile.details layout, and every element is one partial below Resources/Private/Partials/Profile/PublicProfile/.

An installation that overrides the detail template keeps rendering its own copy, so nothing looks broken - and it loses the configurable layout completely. The timeline properties it reads are unchanged: {item.year}, {item.yearStart} and {item.yearEnd} are still there and still integers. Two of the partials the old detail template rendered are now only used by the list and card views, and the third, Partials/Profile/DataHeader.html, is deleted - a project template that still renders it fails at render time. See What an override of the detail template loses and Breaking: The partials of the detail view change.

The profile editing view

The editing plugin of academic_persons_edit was replaced in place. Every Fluid file of the removed form flow is gone, so an override of one of them renders nothing; the new tree is Templates/Profile/Index.html with the partials below Partials/Profile/, and the markup of the two regions the browser builds is authored in Fluid as <template data-pe-proto> prototypes. The profile editing chapter of that extension names every file, every hook and the four prototype attributes an override has to keep.

Icons

The icon set of the editor was replaced. Five identifiers of the form flow are gone - academic-persons-edit-add-image, -add-item, -cancel, -sort and -to-top - and the thirteen action icons of the new set are registered in Configuration/Icons.php of academic_persons_edit, under the identifiers listed in the icon table. A template or PHP file addressing a removed identifier renders TYPO3's default-not-found placeholder. The new icons are inlined as <svg> rather than emitted as <img>, so they follow the text colour - and a site stylesheet that selects .t3js-icon img no longer matches them.

TypoScript and the JSON page type

The write path of the editor is a PAGE object with typeNum = 1733735, which is delivered by the site set fgtclb/academic-persons-edit-profile-editing or by the static template Academic Persons Edit: Profile editing. There was no such page type in 2.4, because the old editor was a server-rendered form flow.

Check that the site really includes one of the two. A site package that copied the extension's TypoScript into its own instead of including it renders the new editor and would answer every save with the page's HTML instead of JSON. The editor detects that case: where the request carries no such PAGE object it renders a role="alert" message above itself and logs the cause, naming the site set. Such a site package has to add the academicPersonsProfileEditingAjax object by hand, or include the delivered TypoScript.

A PageType route enhancer has to map the page type, and a web application firewall or reverse proxy has to let it and the X-Requested-With header through - see the page type section.

Verifying the result

A timeline entry of a profile shows its year in the frontend and in the backend record editor, and the backend form rejects a year above 9999.
The profile editing plugin loads without the "cannot be saved" alert above it, a field can be saved, and the browser console shows no failed request to the page type 1733735.
A profile image is shown in every language of a translated profile, and uploading a new one in one language does not change the other.
vendor/bin/typo3 academic:persons:settings:migrate exits with 0, and the log carries no legacy settings warning.