---
title: "Upgrading from 2.4 to 3.0"
manual: "Academic Jobs"
version: "3.0"
permalink: "https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0@3.0"
source: "Upgrade/From24To30.rst"
rendered: "2026-10-26T17:55:19+00:00"
---

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

Version 3.0 drops TYPO3 12, applies the validation settings of
**academic_jobs** to the backend record editor as well, renders the job
views with speaking classes and their icons from the frontend icon registry of
**academic_base**, and loads the editor configuration of the job form
as an ES module. It changes no database table of this extension. 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_jobs** 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 requires 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
    **academic_base** 3.0.
-   [`fgtclb/academic-base`](https://packagist.org/packages/fgtclb/academic-base) 3.0, the same release as this extension.

A site package that ships its own
`Configuration/AcademicJobs/Settings.yaml` changes it in the same
deployment as the update:

-   Replace `number` with `tel` on `contactPhone`, or remove
    the field from the file so the shipped flags apply. The flags reach the
    backend record editor of a job now, and a `number` there stores
    `+49 30 123` as `49` when an editor saves the job. Move a TCA
    override of `required` or `readOnly` of a job field into the
    settings file, the settings win over it now. See
    [Breaking: The job validation settings reach the backend](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-job-validation-settings-reach-the-backend@3.0).
-   The files of all packages are merged per field now. A field the copy left
    out to make it optional keeps the flags **academic_jobs** ships.
    Name it with an empty list instead, and drop the fields the site package
    does not change. See
    [Breaking: The job validation settings are merged per field](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-job-validation-settings-merged-per-field@3.0).
-   Flags are read regardless of case, a flag outside the shared vocabulary is
    ignored, and `readonly`, `disabled` and
    `frontendreadonly` take effect. Check the flags of the file against
    [Validation settings](https://docs.typo3.org/permalink/fgtclb/academic-jobs:configuration-validations@3.0), see
    [Important: The job validation flags follow the persons vocabulary](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-job-validation-flags-follow-the-shared-vocabulary@3.0).

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. The content element wizard
`academicJobs_pluginContent` of this extension reads the column
`tt_content.list_type`, which TYPO3 14 removes, so it only runs on
TYPO3 13. The same holds for the content element wizards of
**academic_persons**, **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-jobs:breaking-removed-typo3-v12-support@3.0) and
[Important: TYPO3 13.4.35 or 14.3.7 is required](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-minimum-typo3-versions@3.0).

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

```bash
composer require -W \
    'fgtclb/academic-base':'~3.0.0' \
    'fgtclb/academic-jobs':'~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** and **academic_jobs** 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 the columns other
academic extensions add in 3.0.

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

1.  `academicJobs_pluginContent`, **Migrate plugin list element from
    academic_jobs to normal content elements**. It turns every content element
    that is still stored as **Insert plugin** with one of the plugins
    `academicjobs_newjobform`, `academicjobs_list` or `academicjobs_detail`
    into a content element of the type of the same name. Such elements are
    left from version 1.x. The wizard reads `tt_content.list_type`, which
    TYPO3 14 removes, so run it on TYPO3 13, by its name, in
    **Admin Tools > Upgrade > Upgrade Wizard** or on the command line:

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

    Once the column is gone, the wizard finds nothing to do, and the elements
    it would have migrated keep a type nothing renders. TypoScript, page
    TSconfig or SQL of a site package that names one of the plugins through
    `list_type` matches on `CType` instead. See
    [Breaking: Extbase plugins require CType on TYPO3 v14](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-plugins-require-ctype-on-typo3-v14@3.0).

A wizard that TYPO3 recorded as done is offered again once it is marked
undone. TYPO3 13 marks a wizard undone with
`vendor/bin/typo3 upgrade:mark:undone <identifier>`.

## 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_jobs --site=<site identifier>
```

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.

-   The notification mail about a new job is rendered from the Fluid mail
    template `JobCreated` now, with a default message in the language of the
    page. A site that set `plugin.tx_academicjobs.email.template`
    keeps its own text in the mail. One that wants the old sentence sets it
    there. See [Feature: The notification mail about a new job is a Fluid template](https://docs.typo3.org/permalink/fgtclb/academic-jobs:feature-1790666339@3.0) and
    [The notification mail about a submitted job](https://docs.typo3.org/permalink/fgtclb/academic-jobs:configuration-general-notification-mail@3.0).
-   A site that loads its own editor, or none, switches the two scripts of the
    job form off with `plugin.tx_academicjobs.assets.js = 0`, see
    [Feature: The scripts of the new job form can be switched off](https://docs.typo3.org/permalink/fgtclb/academic-jobs:feature-1791566501@3.0).

## 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 extension shipped no
stylesheet in 2.4 and ships none in 3.0, so a site that relied on the card and
list group classes of a Bootstrap theme styles the new classes itself. Move
the selectors of the site stylesheet to the classes in the table of
[Breaking: Job templates carry speaking classes](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-jobs-speaking-frontend-classes@3.0). The chapter [Styling](https://docs.typo3.org/permalink/fgtclb/academic-jobs:styling@3.0)
describes the markup, and [An example](https://docs.typo3.org/permalink/fgtclb/academic-jobs:styling-example@3.0) names the stylesheet of the
development instances as a starting point. The new job form renders the form
partials of **academic_base**, whose classes are described in its
[changelog](https://docs.typo3.org/p/fgtclb/academic-base/main/en-us/Changelog/3.0/Breaking-SpeakingFrontendClasses.html#breaking-base-speaking-frontend-classes).

### The job image {#upgrade-from-2-4-to-3-0-images}

The job image is a `<picture>` with WebP sources now. CSS that selects
the image as a direct child of the card no longer matches. The job views and
the new job form render partials of **academic_base**, so a site that
replaced the partial root paths of the plugin completely adds the path of
**academic_base** below its own:

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

See [Breaking: Job images render as a responsive picture](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-jobs-images-render-as-picture@3.0).

### The editor configuration {#upgrade-from-2-4-to-3-0-rich-text}

The editor configuration of the new job form is an ES module now:

| Old path | New path |
| --- | --- |
| `EXT:academic_jobs/Resources/Public/JavaScript/frontend/ckeditor.js` | `EXT:academic_jobs/Resources/Public/JavaScript/frontend/rich-text.js`, loaded as the module `@fgtclb/academic-jobs/frontend/rich-text.js` |

An override of `Templates/Job/New.html` loads it with
`<f:asset.module identifier="@fgtclb/academic-jobs/frontend/rich-text.js" />`.
`<f:asset.script>` does not execute a module. See
[Breaking: The editor configuration is an ES module](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-ckeditor-configuration-is-a-module@3.0).

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

Every icon of the extension has a new identifier. The icons of the job
properties and of the contact block are registered for the frontend icon
registry of **academic_base** in
`Configuration/FrontendIcons.php` and rendered with `ab:icon`, the
icons of the content elements and of the job record stay backend icons 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). The old identifiers and the icon files of the
extension are removed. Replace the identifiers in templates, TCA, page TSconfig
and PHP code, register a replacement icon under its new identifier in the
matching file of a site package that depends on **academic_jobs**, and
adapt a stylesheet that selected the icon as an `<img>`. See
[Breaking: The job icons are renamed and moved to the frontend icons](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-jobs-job-icons-moved-to-the-frontend-icon-registry@3.0),
[Important: The job contact block shows its own icons](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-job-contact-block-shows-its-own-icons@3.0) and
[Replace the icon of a job property](https://docs.typo3.org/permalink/fgtclb/academic-jobs:templates-override-icons@3.0).

### 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/Job/List.html` | The jobs and the new pagination sit in an `ace-content`, and the list renders one page of the paginator while the pagination is enabled. A project that paginated the list itself removes its own switch. | [Classes and styles](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-classes@3.0), [Feature: The job list can be paginated](https://docs.typo3.org/permalink/fgtclb/academic-jobs:feature-1790660966@3.0) |
| `Templates/Job/Show.html` | Speaking classes, the description in a `ce-bodytext`. | [Classes and styles](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-classes@3.0) |
| `Templates/Job/New.html` | Loads the editor configuration as a module, only while `settings.assets.js` is set, and renders the new partial `Partials/Job/Forms/AdditionalFields.html`. | [The editor configuration](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-rich-text@3.0), [Feature: The scripts of the new job form can be switched off](https://docs.typo3.org/permalink/fgtclb/academic-jobs:feature-1791566501@3.0), [Feature: Additional fields partial in new job form](https://docs.typo3.org/permalink/fgtclb/academic-jobs:feature-new-job-form-additional-fields-partial@3.0) |
| `Partials/Job/Item.html`, `Partials/Job/Information.html` | Speaking classes, the image through the image partial of **academic_base**, and a list of properties that maps each property to the name of its icon. | [Classes and styles](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-classes@3.0), [The job image](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-images@3.0), [Icons](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-icons@3.0) |
| `Partials/Job/Contact.html` | Speaking classes, and its own phone and e-mail icons. | [Important: The job contact block shows its own icons](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-job-contact-block-shows-its-own-icons@3.0) |
| `Partials/Job/Header.html`, `Partials/Job/SectionHeader.html` | They take the class of the heading as `class` instead of `positionClass`. | [Classes and styles](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-classes@3.0) |
| `Partials/Job/Properties/Job.html` | The two job flags are offered as checkboxes, and a select reads `disabled` from its element. | [Important: New job form offers the job flags](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-new-job-form-offers-the-job-flags@3.0), [Important: The new job form renders the shared form partials](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-new-job-form-fields-render-shared-partials@3.0) |
| `Partials/Job/Forms/*.html` | They render the shared form partials of **academic_base**. The ViewHelpers `j:validation.requiredFromValidation` and `j:validation.fieldTypeFromValidation` are removed, a copy that calls them fails. It reads the validation with `validationEnsure` of **academic_base**. `Partials/Job/Forms/ErrorMessage.html` is removed. | [Adapt your code](https://docs.typo3.org/permalink/fgtclb/academic-jobs:upgrade-from-2-4-to-3-0-code@3.0), [Change the fields of the new job form](https://docs.typo3.org/permalink/fgtclb/academic-jobs:templates-override-form-fields@3.0) |

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

-   A listener of
    `\FGTCLB\AcademicJobs\Event\ModifyJobControllerNewActionViewEvent` is
    no longer called. It listens to
    `\FGTCLB\AcademicBase\Event\ModifyPluginViewEvent` instead and returns
    early for every other plugin, see
    [Breaking: The view event of the new job form is gone](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-removed-job-new-action-view-event@3.0),
    [Feature: The plugins dispatch the plugin view event](https://docs.typo3.org/permalink/fgtclb/academic-jobs:feature-plugin-view-event@3.0) and
    [ModifyPluginViewEvent](https://docs.typo3.org/permalink/fgtclb/academic-jobs:developers-event-modify-plugin-view-event@3.0).
-   PHP code that uses
    `\FGTCLB\AcademicJobs\Loader\AcademicJobsSettingsLoader`,
    `\FGTCLB\AcademicJobs\Registry\AcademicJobsSettingsRegistry` or the
    exceptions of `\FGTCLB\AcademicJobs\Exception` uses the settings
    classes of **academic_base**, see
    [Breaking: The validation settings classes of jobs were removed](https://docs.typo3.org/permalink/fgtclb/academic-jobs:breaking-job-validation-settings-classes-removed@3.0).
-   Code that names
    `\FGTCLB\AcademicJobs\SaveForm\FlashMessageCreationMode` imports
    `\FGTCLB\AcademicBase\Form\FlashMessageCreationMode`. The old name
    keeps working until version 4.0, see
    [Deprecation: FlashMessageCreationMode moved to EXT:academic_base](https://docs.typo3.org/permalink/fgtclb/academic-jobs:deprecation-flash-message-creation-mode-moved@3.0).
-   The FlexForm files moved from `Configuration/Flexforms/Core12/` and
    `Configuration/Flexforms/Core13/` to one file each in
    `Configuration/FlexForms/`. Own TCA that names a data structure of
    this extension by its path takes over the new one, see
    [Important: The FlexForm files moved to Configuration/FlexForms/](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-job-flexform-files-moved@3.0).

## 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-jobs:upgrade-from-2-4-to-3-0-upgrade-check@3.0).
-   The content elements are offered as **Job Form**,
    **Job List** and **Job Details** now, see
    [Important: Content elements have new titles and descriptions](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-content-element-titles-and-descriptions@3.0).
-   Saving a job in the backend keeps its contact phone number, and a job
    without a company name or a description can only be saved there once both
    are filled in, unless the settings make them optional.
-   A logo uploaded through the form is stored with a random suffix to its
    file name, and a form shown again with errors asks for the logo once
    more. Check code that relies on the file name of an uploaded logo, see
    [Important: Job image upload uses native Extbase upload handling](https://docs.typo3.org/permalink/fgtclb/academic-jobs:important-migrated-job-image-upload-to-native-extbase-file-upload-handling@3.0).
-   The rich text fields of the form start the editor, and the job views show
    their icons in the colour of the text.