Upgrading from 2.4 to 3.0

Version 3.0 drops TYPO3 12, removes the environment and state manager classes 2.4 deprecated and the file upload converter, and ships the form and image partials the other academic extensions render, with speaking classes and without a stylesheet. It also brings the console command academic:upgrade:check, which reports what an upgrade left behind. Work through the sections in order. Skip a step that does not apply to the installation.

Before you start

Version 3.0 runs on TYPO3 13.4 from 13.4.35 on and on TYPO3 14.3 from 14.3.7 on, with PHP 8.2 or later.

academic_base 3.0 needs a new major version of one package:

fgtclb/environment-state-manager 2.x, the extension environment_state_manager. It is declared in composer.json as ^2.0.1 and in ext_emconf.php as 2.0.1-2.99.99. Version 2.4 required 1.x, see Important: fgtclb/environment-state-manager 2 is required. Composer updates it on its own. A classic installation updates it before it activates academic_base 3.0.

Every other academic extension depends on this one. Upgrade it in the same deployment as all academic extensions of the installation, and on a classic installation before them.

These changes have to ship in the same deployment as the update, because the site fails until they are made:

A project that requires fgtclb/environment-state-manager in its own composer.json raises the requirement to ^2.0.1, see Update the package.
Code that uses a removed environment and state manager class or the file upload converter moves to their replacements, see Adapt your code.
A subclass or an XCLASS of a plugin controller of an academic extension goes, see Subclasses and XCLASSes.

The module paths on this page are those of TYPO3 13, where the upgrade runs.

Update TYPO3 first

Update TYPO3 to 13.4.35 or later while the site still runs 2.4, which supports TYPO3 13.4. Version 3.0 no longer installs on TYPO3 12, and Composer and the Extension Manager refuse it next to an older patch release of TYPO3 13.

Stay on TYPO3 13 until the upgrade is complete when the installation also has academic_jobs, academic_persons, academic_persons_edit or academic_projects. Their content element wizards read the column tt_content.list_type, which TYPO3 14 removes, so they only run on TYPO3 13. Move to TYPO3 14.3.7 or later once they have run.

See Breaking: Removed TYPO3 v12 support and Important: TYPO3 13.4.35 or 14.3.7 is required.

Update the package

composer require -W \
    'fgtclb/academic-base':'~3.0.0'

Composer updates fgtclb/environment-state-manager to 2.x with it. This extension no longer requires the Composer plugin typo3/class-alias-loader , which loaded the class alias 2.4 kept for the deprecated namespace. A project that requires fgtclb/environment-state-manager in its own composer.json, as the upgrade to 2.4 asked of code that uses its classes, raises that requirement to ^2.0.1 in the same command:

composer require -W \
    'fgtclb/environment-state-manager':'^2.0.1' \
    'fgtclb/academic-base':'~3.0.0'

On a classic installation, update environment_state_manager to 2.x from the TER in Admin Tools > Extensions first, because academic_base 3.0 cannot be activated without it. Then update academic_base there, and after it every other academic extension of the installation. Run the commands of this page with typo3/sysext/core/bin/typo3 instead of vendor/bin/typo3.

vendor/bin/typo3 cache:flush

Update the database

vendor/bin/typo3 extension:setup

Or apply the changes in Admin Tools > Maintenance > Analyze Database Structure.

This extension has no table of its own. The comparison applies the changes of the index definitions TYPO3 13.4.35 and 14.3.7 bring, and the changes of the other academic extensions, which their upgrade chapters describe.

Adapt the configuration

The upgrade check

academic_base 3.0 ships the console command academic:upgrade:check. Without an argument it reads the stored configuration of the installation and reports what no longer reaches the academic extensions: a static template that delivers nothing, a page TSconfig import of a file that is gone, a site that depends on a set a release removed, an XCLASS of a class that is final now. Run it on the staging copy right after the package update, and work through what it reports before the next steps:

vendor/bin/typo3 academic:upgrade:check

With the key of an academic extension and --site it also compares the template overrides of a site with the templates that extension ships:

vendor/bin/typo3 academic:upgrade:check <extension key> --site=<site identifier>

Each finding, and what to do about it, is described in Upgrade check.

Position of the content element group

The group Academic of the new content element wizard comes after the groups of TYPO3 now, and the wizard opens on Typical page content again. A site that wants the group placed as before sets the position in its page TSconfig:

mod.wizards.newContentElement.wizardItems.academic.after = special

See Important: The academic group comes last in the content element wizard, and Where the group appears for the other placements.

Label overrides of select items on TYPO3 14

On TYPO3 14 the items of a TCA select field that a frontend form of an academic extension offers read the _LOCAL_LANG override of the plugin as well, not only the one of the extension. An override written for a plugin reaches those items now. Check that it is meant for them. See Important: Select item labels read the plugin override on TYPO3 v14.

Adapt templates and assets

Site stylesheets

No academic extension ships a stylesheet for its markup in 3.0, and the templates carry speaking classes with the prefix ace- instead of the classes of the theme they were developed with, see What the extensions ship. The site package styles the markup. How the class system is built, and which classes of Bootstrap the templates keep, is described in Styling. The stylesheet of the development instances of the academic extensions is a complete example to start from, see A complete stylesheet as a reference.

The form field partials and the image partial of this extension are rendered by the new job form of academic_jobs and by every image of a list item or a page of the other extensions. Move the selectors of the site stylesheet that styled those fields, their messages and those images to the new classes, ace-field, ace-control, ace-field-errors, ace-errors, ace-image, ace-figure and the others the table of Breaking: Form and image partials carry speaking classes lists. A Bootstrap theme no longer shows the message of a field by itself, because it shows invalid-feedback only.

The upgrade chapter of each academic extension names the changes of its own plugins.

The partials of this extension

The partials below Resources/Private/Partials/Academic/ are new in 3.0, so no project overrides them yet. The academic extensions register their path in the partial root paths of their plugins with the key -1. A project that replaces the partial root paths of an academic plugin completely, instead of adding a path of its own, lists that path itself:

plugin.tx_academicpersons.view.partialRootPaths {
    -1 = EXT:academic_base/Resources/Private/Partials/
}

Without it, the plugin fails on the partial it cannot resolve. See Overriding the partial and Feature: A responsive image partial to share.

A project that overrides a form field partial passes invalid as errorClass, and an override of Form/Textarea.html keeps the class ace-ckeditor on a rich text area, which the rich text editor of the job form starts on. See The form partials.

Frontend icons

The icons a visitor sees come from a frontend icon registry of this extension now, which every extension and site package fills through its own Configuration/FrontendIcons.php. The templates of the academic extensions render them with the icon view helper of this extension, no longer with <core:icon>. A site package that replaced an icon of an academic extension in its Configuration/Icons.php registers the replacement in Configuration/FrontendIcons.php, under the identifier the extension uses in 3.0, and depends on the extension it replaces the icon of. See Feature: A frontend icon registry and an icon view helper, Replacing an icon in a site package and the upgrade chapter of the extension that renders the icon.

Adapt your code

The environment and state manager

The classes of the namespaces \FGTCLB\AcademicBase\Environment, \FGTCLB\AcademicBase\Core12\Environment and \FGTCLB\AcademicBase\Core13\Environment are removed, together with the class alias of \FGTCLB\AcademicBase\Environment\StateBuildContext. Code that still uses one of them raises a fatal error. Require fgtclb/environment-state-manager and use its namespace \FGTCLB\EnvironmentStateManager, as the upgrade to 2.4 described.

Version 2.x of environment_state_manager ships the namespaces \FGTCLB\EnvironmentStateManager\Core13 and \FGTCLB\EnvironmentStateManager\Core14, and no longer \FGTCLB\EnvironmentStateManager\Core12. Code that named a class of Core12 names the one of the running TYPO3 version. See Breaking: Removed internal environment / state-manager subsystem and Important: fgtclb/environment-state-manager 2 is required.

The file upload converter

\FGTCLB\AcademicBase\Extbase\Property\TypeConverter\FileUploadConverter is removed, together with the language file EXT:academic_base/Resources/Private/Language/locallang.xlf and its German translation, which held its error messages. Code that registered the converter for an argument of its own uses the native file upload handling of Extbase, a FileUploadConfiguration on the argument. An override of one of the removed labels can go. See Breaking: Removed FileUploadConverter.

Subclasses and XCLASSes

The chapter Extension points names what a project may build on in every academic extension. Everything else may change in any release, and every plugin controller is final in 3.0, so a subclass or an XCLASS of a controller no longer loads. Move such code to the events the chapter lists. academic:upgrade:check reports every XCLASS of an academic class, as an error where the class is final or gone, and as a notice where it is a domain model, which a project may extend. See Important: What a project may build on is now named.

Listeners of the plugin events

The events one plugin rendering dispatches share one plugin action context now. A listener that checked for the class \FGTCLB\AcademicBase\Domain\Model\Dto\PluginControllerActionContext checks for \FGTCLB\AcademicBase\Domain\Model\Dto\PluginControllerActionContextInterface instead, because the persons plugins hand the view event their own context. See Important: The events of one plugin rendering share their context.
PluginControllerActionContext::getContentObjectRenderer() returns null for a request attribute that is not a content object renderer, instead of failing. A try around the call can go. See Important: The plugin action context never fails on the content object.

Check the result

vendor/bin/typo3 academic:upgrade:check exits with 0. A notice alone does not fail it. Run it with an extension key and --site for every academic extension whose templates the project overrides, see Letting a site name the folders.
On a classic installation, environment_state_manager 2.x is listed as active in Admin Tools > Extensions.
The new content element wizard opens on Typical page content and shows the group Academic after the groups of TYPO3, or where the page TSconfig of the site places it.
A field of the job form of academic_jobs that fails validation shows its message right below it, see Important: The form partials mark rejected fields.
With academic_persons installed, the images of the profile cards and of the public profile are rendered as a <picture> and are styled by the site stylesheet.
A search of the site package and of own extensions for AcademicBaseEnvironment, EnvironmentStateManagerCore12 and FileUploadConverter finds nothing any more.