---
title: "Upgrading from 2.4 to 3.0"
manual: "Academic Contacts for Pages"
version: "main"
permalink: "https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-4-to-3-0@main"
source: "Upgrade/From24To30.rst"
rendered: "2026-10-26T19:20:19+00:00"
---

# Upgrading from 2.4 to 3.0 {#upgrade-from-2-4-to-3-0}

Version 3.0 drops TYPO3 12, renders the contact list with speaking classes and
the profile images as responsive pictures, and renames the icons of the
extension. With **academic_persons** 3.0 the contract a page contact
belongs to becomes workspace aware. It changes no database table of this
extension and brings no upgrade wizard. Work through the sections in order.
Skip a step that does not apply to the installation.

## Before you start {#upgrade-from-2-4-to-3-0-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_contacts4pages** 3.0 needs these packages. Upgrade them
first or in the same deployment, in this order:

-   [`fgtclb/environment-state-manager`](https://packagist.org/packages/fgtclb/environment-state-manager) 2.x, which
    **academic_base** 3.0 and **academic_persons** 3.0 require
    instead of 1.x. Composer updates it on its own. A classic installation
    replaces **environment_state_manager** 1.x with 2.x before it
    activates either of them.
-   [`fgtclb/academic-base`](https://packagist.org/packages/fgtclb/academic-base) 3.0, the same release as this extension.
-   [`fgtclb/academic-persons`](https://packagist.org/packages/fgtclb/academic-persons) 3.0, the same release as this
    extension. Its upgrade chapter has steps of its own.

These changes have to ship in the same deployment as the update:

-   A site package that imports the `setup.typoscript` of this extension
    by path imports the `constants.typoscript` of the same folder as
    well, see [Adjust your own configuration](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-4-to-3-0-own-configuration@main).
-   A view that renders the persons partials with replaced partial root paths
    lists the path of **academic_base**, see
    [The contact image and the persons partials](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-4-to-3-0-images@main).

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

## Update TYPO3 first {#upgrade-from-2-4-to-3-0-typo3}

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. This extension requires
**academic_persons**, whose content element wizard reads the column
`tt_content.list_type`, which TYPO3 14 removes, so it only runs on
TYPO3 13, see its [upgrade chapter](https://docs.typo3.org/p/fgtclb/academic-persons/main/en-us/Upgrade/From24To30.html).
The same holds for the content element wizards of **academic_jobs**,
**academic_persons_edit** and **academic_projects** when the
installation also has them. Move to TYPO3 14.3.7 or later once they have run.

See [Breaking: Removed TYPO3 v12 support](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-removed-typo3-v12-support@main) and
[Important: TYPO3 13.4.35 or 14.3.7 is required](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-minimum-typo3-versions@main).

## Update the package {#upgrade-from-2-4-to-3-0-package}

```bash
composer require -W \
    'fgtclb/academic-base':'~3.0.0' \
    'fgtclb/academic-persons':'~3.0.0' \
    'fgtclb/academic-contacts4pages':'~3.0.0'
```

On a classic installation, update **environment_state_manager** to 2.x
from the TER in **Admin Tools > Extensions** first, then update
**academic_base**, **academic_persons** and
**academic_contacts4pages** there, in this order. Run the commands of
this page with `typo3/sysext/core/bin/typo3` instead of
`vendor/bin/typo3`.

```bash
vendor/bin/typo3 cache:flush
```

## Update the database {#upgrade-from-2-4-to-3-0-database}

```bash
vendor/bin/typo3 extension:setup
```

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

The comparison changes no table of this extension. It applies the changes of
the index definitions TYPO3 13.4.35 and 14.3.7 bring, and those of
**academic_persons**. The contract table of that extension, to which
page contacts belong as inline children, gains the columns of a workspace
aware table, so a contract and its page contacts are drafted and published
together. The section **Update the database** of the [upgrade chapter
of academic_persons](https://docs.typo3.org/p/fgtclb/academic-persons/main/en-us/Upgrade/From24To30.html)
describes the comparison of that table on SQLite. See
[Important: The contact inline parent is now workspace aware](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-contact-inline-parent-is-workspace-aware@main).

## Adapt the configuration {#upgrade-from-2-4-to-3-0-configuration}

### The upgrade check {#upgrade-from-2-4-to-3-0-upgrade-check}

The console command `academic:upgrade:check` of **academic_base**
reads the stored configuration of the installation and reports the static
templates, page TSconfig imports and site sets that no longer reach an academic
extension. Run it on the staging copy right after the package update:

```bash
vendor/bin/typo3 academic:upgrade:check
```

With the extension key and a site it also compares the template overrides of
the site with the templates this extension ships:

```bash
vendor/bin/typo3 academic:upgrade:check academic_contacts4pages --site=<site identifier>
```

A folder that overrides the persons partials for this plugin as well is
checked with **academic_persons**. The check of
**academic_contacts4pages** compares it with the partials of this
extension, which ships no `Profile/` partials, and reports every file in
it as `missing-upstream`. Each finding, and what to do about it, is
described in the [upgrade check](https://docs.typo3.org/p/fgtclb/academic-base/main/en-us/UpgradeCheck/Index.html#upgrade-check)
of **academic_base**.

### Adjust your own configuration {#upgrade-from-2-4-to-3-0-own-configuration}

The site set, the static templates and the page TSconfig of this extension keep
their names and paths from 2.4.

-   A site whose content element layout renders no header can switch the
    header of the contact list on with
    `plugin.tx_academiccontacts4pages.renderContentElementHeader = 1`.
    A site package that imports the `setup.typoscript` of this extension
    by path imports the `constants.typoscript` of the same folder as
    well, otherwise the header renders as if it were switched on. See
    [Feature: The contact list can render the content element header](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-1790440965@main) and [The header of the content elements](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:configuration-content-element-header@main).
-   The contacts take the crop variant and the gender placeholders of the
    persons lists, set in the site settings of **academic_persons**.
    See [Important: Contacts follow the image settings of the persons extension](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-1790709369@main).

## Adapt templates and assets {#upgrade-from-2-4-to-3-0-templates}

### Classes and styles {#upgrade-from-2-4-to-3-0-classes}

The templates render speaking classes now, shared by all academic extensions,
and no classes of the theme they were developed with. The card of a contact is
the profile item of **academic_persons**, which carries the speaking
classes of that extension, see its [chapter Styling](https://docs.typo3.org/p/fgtclb/academic-persons/main/en-us/Styling/Index.html).
The extension shipped no stylesheet in 2.4 and ships none in 3.0. Move the
selectors of the site stylesheet to the classes in the table of
[Breaking: Contact list carries speaking classes](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-contacts4pages-speaking-frontend-classes@main). The chapter
[Styling](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:styling@main) describes the markup, and [An example](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:styling-example@main) names the
stylesheets of the development instances as a starting point.

### The contact image and the persons partials {#upgrade-from-2-4-to-3-0-images}

The image of a contact is a `<picture>` with WebP sources now, and a
contact whose profile has no image shows the placeholder of the persons
plugins. CSS that selects the image as a direct child of the card no longer
matches. To keep contacts without an image empty, set
`plugin.tx_academicpersons.image.placeholder.default` to an empty
value. A view that renders `Profile/Item`, the plugin view with replaced
partial root paths or the page view of a page template, lists the path of
**academic_base** below the others:

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

See [Breaking: Profile images render as a responsive picture](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-contacts4pages-profile-images-render-as-picture@main).

The partial `Profile/Item.html` of **academic_persons**, which
renders every contact, is built from small partials now: the detail link, the
name, the contracts and the image. A copy of `Profile/Item.html` keeps
rendering what it rendered before. Drop it in favour of the small partial it
was meant to change, described in the [chapter Templates of academic_persons](https://docs.typo3.org/p/fgtclb/academic-persons/main/en-us/Templates/Index.html).
This plugin reads the persons partials through partial root paths of its own,
so an override of them is registered for
`plugin.tx_academiccontacts4pages` as well as for
`plugin.tx_academicpersons`. See
[Important: The profile item is built from small partials](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-profile-item-partials-are-overridable@main).

### Icons {#upgrade-from-2-4-to-3-0-icons}

The icons of the extension are replaced and have new identifiers. They are
backend icons, registered in [`Configuration/Icons.php`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/Icons.html#file-extension-configuration-icons-php):

| 2.4 identifier | 3.0 identifier |
| --- | --- |
| `academic_contacts4pages` | `tx-academiccontacts4pages-plugin-contacts` |
| `tx_academiccontacts4pages_domain_model_contact` | `tx-academiccontacts4pages-record-contact` |
| `tx_academiccontacts4pages_domain_model_role` | `tx-academiccontacts4pages-record-role` |

`tx_academiccontacts4pages_domain_model_contract` is removed without a
successor, and the files `Resources/Public/Icons/Contract.svg` and
`Resources/Public/Icons/Role.svg` are removed. Replace the identifiers
in templates, page TSconfig, TCA overrides and PHP code, move a replacement
icon in the [`Configuration/Icons.php`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/Icons.html#file-extension-configuration-icons-php) of a site package to the new
identifier, and change `.icon-*` selectors. See
[Breaking: Icons replaced and their identifiers renamed](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-contacts4pages-icon-identifiers-renamed@main).

### Template overrides {#upgrade-from-2-4-to-3-0-overrides}

Version 3.0 changes these templates and partials. A copy of one of them in a
site package keeps rendering the copy, so compare each copy with the shipped
file and take over the changes. The paths below are relative to
`Resources/Private/`:

| File | What changed | Entry |
| --- | --- | --- |
| `Templates/Contacts/List.html` | The contacts sit in an `ace-content`, each group in an `ace-itemlist`, the outermost element carries `academic-contacts4pages-list`, and the header of the content element renders while `settings.renderContentElementHeader` is set. | [Classes and styles](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-4-to-3-0-classes@main), [Feature: The contact list can render the content element header](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-1790440965@main) |
| `Partials/Contacts/Item.html` | The role carries `ace-role`. | [Classes and styles](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-4-to-3-0-classes@main) |

The upgrade check with the extension key and a site compares a copy with the
shipped file, see [The upgrade check](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-4-to-3-0-upgrade-check@main).

## Adapt your code {#upgrade-from-2-4-to-3-0-code}

-   A copy of the controller of the content element, or a subclass of
    `\FGTCLB\AcademicContacts4pages\DataProcessing\ContactsProcessor`,
    that only changes which contacts a page shows is replaced by a listener of
    `\FGTCLB\AcademicContacts4pages\Event\ModifyPageContactsEvent`. See
    [Feature: Page contacts processor options and contacts event](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-1790767100@main) and [ModifyPageContactsEvent](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:developers-page-contacts-event@main).
-   Additional view variables of the content element come from a listener of
    `\FGTCLB\AcademicBase\Event\ModifyPluginViewEvent`, see
    [Feature: The plugin dispatches the plugin view event](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-plugin-view-event@main) and
    [ModifyPluginViewEvent](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:developers-event-modify-plugin-view-event@main).

## Check the result {#upgrade-from-2-4-to-3-0-check}

-   The upgrade check exits with `0`, without and with the extension key,
    see [The upgrade check](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-4-to-3-0-upgrade-check@main). A folder that overrides
    the persons partials for this plugin as well is the exception: the check
    with this extension key reports its files as `missing-upstream`, so
    check that folder with **academic_persons** instead.
-   The content element is offered as **Person’s Contacts on the Page**
    now, see [Important: Content elements have new titles and descriptions](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-content-element-titles-and-descriptions@main).
-   A contact whose profile carries a title shows it in front of the name.
-   Every release of version 2 can hold page contacts that lost their page or
    their contacts role when a workspace was published by its publish date, or
    when a page and a contacts role were edited in the same workspace. The
    queries in [Important: Page contacts keep their page and role when either is published](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-page-contacts-keep-their-page-on-publish@main) find
    them.
-   Translated contacts that point at a page without a translation in their
    language are left from older versions. They are not rendered twice, and
    can be deleted, see [Important: Contacts of untranslated pages stay untranslated](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-1788197604@main).