---
title: "Upgrading from 2.3 to 2.4"
manual: "Academic Contacts for Pages"
version: "3.0"
permalink: "https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:upgrade-from-2-3-to-2-4@3.0"
source: "Upgrade/From23To24.rst"
rendered: "2026-10-26T17:55:07+00:00"
---

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

Version 2.4 delivers the configuration of **academic_contacts4pages**
per component, hides its content element until a site enables it and gives a
contact a position of its own in its contract and in its contacts role. A new
upgrade wizard migrates the content elements of version 1.x. Work through the
sections in order. Skip a step that does not apply to the installation.

## Before you start {#upgrade-from-2-3-to-2-4-before-you-start}

Version 2.4 runs on TYPO3 12.4 from 12.4.22 on and on TYPO3 13.4, with PHP 8.1
or later. That is the same as for 2.3, so the TYPO3 core does not have to
change for this upgrade.

**academic_contacts4pages** 2.4 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) 1.x, new in 2.4, which
    **academic_base** 2.4 and **academic_persons** 2.4 require.
    Composer installs it on its own. A classic installation installs
    **environment_state_manager** before it activates either of them.
-   [`fgtclb/academic-base`](https://packagist.org/packages/fgtclb/academic-base) 2.4, the same release as this extension.
-   [`fgtclb/academic-persons`](https://packagist.org/packages/fgtclb/academic-persons) 2.4, the same release as this
    extension. Its upgrade chapter has steps of its own.

The extension now declares the system extension **install** as a
dependency, for its upgrade wizards. TYPO3 keeps that extension active in every
installation, so this needs no action.

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

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

A project that requires branch `2` as `2.x-dev` keeps an inline alias such
as `2.x-dev as 2.4.x-dev` working, see [Important: The development branch installs as 2.4.x-dev](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-1790796661@3.0).

On a classic installation, install **environment_state_manager** 1.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-3-to-2-4-database}

Apply the database changes in **Admin Tools > Maintenance > Analyze
Database Structure**, or on the command line:

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

For this extension the comparison adds five columns to
`tx_academiccontacts4pages_domain_model_contact`:

-   `contract_sorting` and `role_sorting`, the order of a contact in
    its contract and in its contacts role. Until the wizard of the next section
    fills them, both hold `0`, see
    [Important: Contracts and contacts roles sort their contacts on their own](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-contract-and-role-sort-their-contacts@3.0).
-   `email_address`, `phone_number` and `physical_address`, the
    address records a contact displays. The default `0` means
    **Display all**, the output of every existing contact, see
    [Feature: Dedicated selection of address records](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-dedicated-address-record-selection@3.0).

The language columns of the table are declared in its TCA now. They exist
already, so the schema does not change for them, see
[Important: Translations of page contacts keep their parent](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-1791547202@3.0).

## Run the upgrade wizards {#upgrade-from-2-3-to-2-4-wizards}

Both wizards need the database changes of the previous section. Run them in
this order, in **Admin Tools > Upgrade > Upgrade Wizard** or on the
command line. Mind the identifiers, the first one is spelled without the s
of Contacts.

1.  `academicContact4pages_seedContactSecondarySorting`, **Seed the
    contact sort order of contracts and contacts roles**. It fills the two new
    sort columns with the order the contract and contacts role forms show
    today. Run it right after the database comparison: until it has run, every
    contact holds `0` in both columns, and a contact saved in the backend
    gets no position of its own in those lists. Running it again is
    harmless.

    ```bash
    vendor/bin/typo3 upgrade:run academicContact4pages_seedContactSecondarySorting
    ```

    See [Important: Contracts and contacts roles sort their contacts on their own](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-contract-and-role-sort-their-contacts@3.0).
1.  `academicContacts4pages_pluginUpgradeWizard`, **Migrate the
    academic_contacts4pages plugins of version 1.x**. It renames the content
    type `academiccontacts4pages_contactslist` of version 1.x to
    `academiccontacts4pages_list` in every content element, and carries
    the permission of backend user groups over. It replaces
    `academicContact4pages_pluginUpgradeWizard` of versions 2.0 to 2.3, which
    looked for a misspelled type and never migrated anything. The new wizard is
    a new class, and TYPO3 records a wizard as done by its class, so it is
    offered also where the old one is marked done. It is offered only while a
    content element or a backend user group of version 1.x is left, so an
    installation that started with 2.0 or later never sees it.

    ```bash
    vendor/bin/typo3 upgrade:run academicContacts4pages_pluginUpgradeWizard
    ```

    TypoScript, page TSconfig or templates of a site package that name the old
    type change it to `academiccontacts4pages_list` by hand. See
    [Important: A new upgrade wizard migrates the plugins of version 1.x](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-ace-897-academic-contacts4pages@3.0) and
    [Upgrading from version 1.x](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:installation-upgrade-from-version-1@3.0).

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

The TypoScript and the page TSconfig are now delivered per content element,
and the **Contacts for this page** content element is hidden in the
whole installation until the page TSconfig of its component is included. See
[Breaking: Site sets and static templates have been restructured](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-site-sets-and-static-templates-restructured@3.0).

### Include the components {#upgrade-from-2-3-to-2-4-components}

-   **Site set, TYPO3 13 only.** A site that depends on the set
    `fgtclb/academic-contacts4pages` needs no change. The set keeps its name
    and now brings the page TSconfig along.
-   **Static template.** The stored entry of 2.3 keeps working as
    **Academic Contacts4Pages: Path up to 2.3 (deprecated, use All
    components) (academic_contacts4pages)**, which is removed in version 4.0.
    Replace it with **Academic Contacts4Pages: All components
    (academic_contacts4pages)** in the field **Include TypoScript sets**
    on the tab **Advanced Options** of the template record. That entry
    brings the shared plugin settings of **academic_persons** along, so
    remove a separate entry **Academic Persons: Shared plugin settings
    (academic_persons)**, called **Academic Persons Settings
    (academic_persons)** in 2.3, from the same record. See
    [Deprecation: The static template path of version 2.3](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:deprecation-legacy-static-template-path@3.0).
-   **Page TSconfig.** A site without the site set, which is every site on
    TYPO3 12, adds **Academic Contacts4Pages: All components
    (academic_contacts4pages)** in the field **Include static Page
    TSconfig (from extensions)** on the tab **Resources** of its root
    page, see [Include static page TSconfig](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:static-pagetsconfig@3.0). Without it the content element is not
    offered for new content.
-   Use one of the two mechanisms per site, see
    [Do not combine both](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:one-mechanism-per-site@3.0).

Until the component is included, an existing content element keeps rendering
and keeps its type: **academic_base** 2.4 shows the stored type in the
field **Type** followed by **(not enabled on this page)**, and
saving keeps it. The warning of the changelog entry that saving such a record
rewrites its type describes the state before that fix. A content element that
an older version or a page TSconfig of your own already turned into another type
is not repaired. Correct it by hand from its record history.

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

-   The page TSconfig directory is `Configuration/TSconfig/` now, and the
    TypoScript moved into `Configuration/TypoScript/List/`. Take the new
    path of every `@import` from the table of
    [Breaking: Site sets and static templates have been restructured](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-site-sets-and-static-templates-restructured@3.0). An import of a
    missing file fails silently.
-   The setup reads three constants now, the Fluid root paths of the plugin. A
    site package that imports a `setup.typoscript` of this extension
    imports the `constants.typoscript` of the same folder into its
    constants as well, otherwise the plugin fails with a missing template:

    **TypoScript constants of the site package**

    ```typoscript
    @import 'EXT:academic_contacts4pages/Configuration/TypoScript/List/constants.typoscript'
    ```
-   A site package that replaces the shipped setup with a copy of its own adds
    `plugin.tx_academiccontacts4pages.settings.groupByRole = 1` to
    the copy. Existing content elements store no value for the new option
    **Group by role** and read this default, see
    [Feature: Optional role grouping and one partial per contact](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-1790316809@3.0).
-   On TYPO3 12, add
    `tx_academiccontacts4pages_domain_model_contact:sys_language_uid` to the
    allowed excludefields of every backend user group whose members set the
    language of a page contact, see [Important: Translations of page contacts keep their parent](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-1791547202@3.0).

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

A copy of a template or partial 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` | Contacts without a role are rendered after the role groups, from the new variable `{contactsWithoutRole}`. The option **Group by role** switches the role groups off, and every contact renders through the new partial `Partials/Contacts/Item.html`. | [Important: Contacts without a role are listed too](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-ace-322-academic-contacts4pages@3.0), [Feature: Optional role grouping and one partial per contact](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-1790316809@3.0) |
| `Partials/Contacts/Item.html` | New. A site package that already ships a partial of that name in a partial root path of this plugin has it rendered for every contact now. Rename it, or turn it into the contact card. | [Feature: Optional role grouping and one partial per contact](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:feature-1790316809@3.0) |
| `Partials/Profile/Item.html` of **academic_persons** | The name leaves out an empty middle name, which a copy of the partial takes over in its `header` argument. | [Important: Contact names leave out an empty middle name](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-ace-853-academic-contacts4pages@3.0) |

The view variable `{contacts}` is a plain list now, no query result. A
template that reads `{contacts.first}` gets nothing, see
[Important: Contacts without a visible profile are skipped](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-contacts-without-visible-profile-are-skipped@3.0).

No asset of this extension changed.

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

-   A class that extends
    `\FGTCLB\AcademicContacts4pages\Domain\Repository\ContactRepository`
    and overrides `findByPid()` adds the parameter
    `bool $showHidden = false`, see
    [Breaking: Extended ContactRepository::findByPid() signature](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-ace-250-academic-contacts4pages@3.0).
-   `\FGTCLB\AcademicContacts4pages\Backend\FormEngine\ContractItemsProcFunc`
    is removed. Own TCA or FlexForm configuration uses
    `\FGTCLB\AcademicPersons\Backend\FormEngine\ContractItems->itemsProcFunc`
    instead, see [Breaking: Removed duplicated ContractItemsProcFunc in EXT:academic_contacts4pages](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:breaking-1783613369@3.0).
-   A subclass of
    `\FGTCLB\AcademicContacts4pages\DataProcessing\ContactsProcessor`
    that is named in TypoScript has to be autowired by the `Services.yaml`
    of its site package, because the processor takes its collaborator through
    the constructor now. Code that reads the contacts of the processor or the
    plugin as a query result accepts a list. See
    [Important: Contacts without a visible profile are skipped](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-contacts-without-visible-profile-are-skipped@3.0).

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

-   The **Contacts for this page** content element is offered for new
    content on the pages that should have it, and existing ones keep their
    type.
-   The order of the contacts on a page, in a contract and in a contacts role
    stays as it was after one of them is saved.
-   Pages that mix contacts with and without a role list all of them.
-   On TYPO3 12, translations of page contacts that an import created may point
    at a wrong original. The query in [Important: Translations of page contacts keep their parent](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-1791547202@3.0) finds them.
-   Translated contacts may point at a translation of their contacts role, and
    localizing a contacts role may have left duplicates. The queries in
    [Important: Translated contacts keep their contacts role](https://docs.typo3.org/permalink/fgtclb/academic-contacts4pages:important-translated-contacts-keep-their-role@3.0) find both.
-   The address selects of a page contact are relations now. Existing page
    contacts get their rows in the reference index on their next save, or at
    once with `vendor/bin/typo3 referenceindex:update`.