Upgrading from 2.3 to 3.0 

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. An installation coming from 2.3 meets every path change of 2.4 and 3.0 at once, so run it on the staging copy right after the package update, and work through what it reports together with 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.

Page TSconfig imports 

The page TSconfig that labels the content element group Academic moved, and the directory Configuration/TsConfig/ is spelled Configuration/TSconfig/ now. An @import of an old path loads nothing and reports no error. The upgrade check reports it as tsconfig-import. Search the site package for the old paths and replace them:

An import that only served to label the group can be removed instead. The Configuration/page.tsconfig of this extension delivers the label to every installation, whatever the site configuration says.

Site configurations need no change. The set fgtclb/academic-base-ctype-group keeps its name, and the aggregate set fgtclb/academic-base depends on it. Two entries for the page field Include static Page TSconfig (from extensions) on the tab Resources are new as well and need not be selected. See Breaking: Site sets and page TSconfig have been restructured.

Position of the content element group 

The group Academic of the new content element wizard comes after the groups of TYPO3, and the wizard opens on Typical page content. Version 2.3 placed the group after Special elements and opened the wizard on that group. A site that wants that placement back sets it 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 

The items of a TCA select field that a frontend form of an academic extension offers, the job type of the job form of academic_jobs for example, read their label overrides from the path without underscores. Move an override from the extension key to the extension name, or to the path of the one plugin it is meant for:

# Before
plugin.tx_academic_jobs._LOCAL_LANG.default.tx_academicjobs_domain_model_job.jobtype.job = Position

# After
plugin.tx_academicjobs._LOCAL_LANG.default.tx_academicjobs_domain_model_job.jobtype.job = Position

See Important: Select item labels are read from the documented path. On TYPO3 14 the override of the plugin reaches these items as well, see Important: Select item labels read the plugin override on TYPO3 v14.

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.

The environment and state manager 

The classes of the namespaces \FGTCLB\AcademicBase\Environment , \FGTCLB\AcademicBase\Core12\Environment and \FGTCLB\AcademicBase\Core13\Environment are removed. They were marked @internal . Version 2.4 deprecated them in favour of the extension environment_state_manager, and 3.0 removes them, see Breaking: Removed internal environment / state-manager subsystem. Code of a project that uses them raises a fatal error until it:

1. Requires fgtclb/environment-state-manager ^2.0.1 in its own composer.json, or environment_state_manager in its own ext_emconf.php.
2. Replaces the namespace prefix with \FGTCLB\EnvironmentStateManager , and \Core13\Environment with Core13 . The class names stay the same. Version 2.x of environment_state_manager ships Core13 and Core14 , and nothing for TYPO3 12, so code that used \Core12\Environment names the class of the running TYPO3 version instead.
3. Types against the ExtendedStateInterface of Core13 where it calls the TypoScriptFrontendController accessors of a state, which StateInterface no longer declares.

Own handlers of a TCA select field 

An itemsProcFunc handler that is reached through GetSelectItemsForTcaManagedTableFieldMethodTrait receives the same $parameters['TSconfig'] as in the backend form: the page TSconfig below itemsProcFunc. of the field, or null . A handler that descended through the complete page TSconfig tree to compensate reads the setting directly instead:

// Before, only through the trait
$mySetting = $parameters['TSconfig']['TCEFORM.'][$table . '.'][$field . '.']['itemsProcFunc.']['mySetting'] ?? null;

// After, the same as in the backend form
$mySetting = $parameters['TSconfig']['mySetting'] ?? null;

The parameters of \FGTCLB\AcademicBase\Event\ModifyTcaSelectFieldItemsEvent declare that entry as nullable for the same reason. See Important: The select item helper passes the field TSconfig.

The trait passes an empty $parameters['row'] now, because there is no record outside the backend form, and the event declares row optional. A listener of the event reads the row, and every field of it, with a fallback:

$row = $parameters['row'] ?? [];
$pageId = (int)($row['pid'] ?? $parameters['effectivePid']);

See Important: The select item helper passes an empty row.

The event now declares the other parameters as TYPO3 passes them, as the PHPStan type alias ItemsProcFuncParameters . inlineParentUid and inlineTopMostParentUid are the empty string '' for a record that is not edited as an inline child and a NEW... string for a parent that is not saved yet, site is a NullSite for a record outside any site, and an item TYPO3 built is a SelectItem . A listener casts an inline uid, checks the site, and types an item as array|SelectItem :

$parentUid = (int)($parameters['inlineParentUid'] ?? 0);

See Important: The select item event declares what TYPO3 passes.

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. 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.
• The getters of PluginControllerActionContext for the site, the language and the content object renderer return null for a request attribute of another type, instead of failing. A try around such a call can go. See Important: The plugin action context never fails on the site or the language and Important: The plugin action context never fails on the content object.