---
title: "Upgrading from 2.4 to 3.0"
manual: "Academic StudyPlan"
version: "main"
permalink: "https://docs.typo3.org/permalink/fgtclb/academic-study-plan:upgrade-from-2-4-to-3-0@main"
source: "Upgrade/From24To30.rst"
rendered: "2026-10-17T08:48:10+00:00"
---

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

Version 3.0 drops TYPO3 12, makes the three record tables of the study plan
workspace aware, ships no stylesheet any more, loads the script from the
template as an ES module, renders speaking classes and the shared icons of
**academic_base**, and splits the template into partials with a markup
contract of data attributes. Until the database is updated, the backend list of
the study plan categories and every study plan fail. 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_study_plan** 3.0 declares no new dependency of its own. It
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. Version 2.4 required 1.x. Composer
    updates it on its own. A classic installation updates
    **environment_state_manager** 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.

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

-   The database update, without which the backend list of the study plan
    categories and every study plan fail, see
    [Update the database](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:upgrade-from-2-4-to-3-0-database@main).
-   The rules of the site stylesheet for the study plan. From 3.0 on the site
    package styles the study plan, and without its rules a semester header
    shows both of its glyphs and the filter does not collapse, see
    [Site stylesheet](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:upgrade-from-2-4-to-3-0-stylesheet@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 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](https://docs.typo3.org/permalink/fgtclb/academic-study-plan: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-study-plan: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-study-plan':'~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_study_plan** 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 tables `tx_academicstudyplan_domain_model_category`,
`tx_academicstudyplan_domain_model_semester` and
`tx_academicstudyplan_domain_model_module` are workspace aware now and get
the columns `t3ver_oid`, `t3ver_wsid`, `t3ver_state` and
`t3ver_stage` with an index. Until the columns are there, the backend
list of the study plan categories and the frontend of every study plan fail
with a database error. No stored record is changed. See
[Important: Study plan records are now workspace aware](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-1787907823@main). The comparison also applies the changes of the
index definitions TYPO3 13.4.35 and 14.3.7 bring.

The column `credit_points` of the semester and module tables is no longer
declared in [`ext_tables.sql`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ExtTablesSql.html#file-extension-ext-tables-sql). TYPO3 derives it from the TCA, a decimal
column with two decimals, as in 2.4. On MariaDB, MySQL and PostgreSQL the
comparison leaves it alone. An installation that redefined the column in an
[`ext_tables.sql`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ExtTablesSql.html#file-extension-ext-tables-sql) of its own removes that definition before the
comparison, because a declared column wins over the derived one. See
[Important: The credit point columns are derived from the TCA](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-ace-722-academic-study-plan-derived-column@main).

On SQLite two things differ:

-   `vendor/bin/typo3 extension:setup` can create the index over
    `t3ver_oid` and `t3ver_wsid` without adding the four columns,
    and reports success. Check afterwards that all three tables carry the four
    columns, and take the schema from a database built with the new state
    where they are missing.
-   The database analyzer can report "table … already exists" and "no such
    table: \_\_temp\_\_…" for the semester and module tables, because both changes
    rebuild those tables in one run. The tables end up complete with every
    value kept, and a second comparison offers nothing more.

## 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 what no longer
reaches the academic extensions. Run it on the staging copy right after the
package update. For this extension it reports, among others, a site that
depends on the alias set `fgtclb/academic-study-plan-default`, and a site
that delivers this extension through its site set and a static template at
once:

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

With the extension key and a site it also lists the template overrides of the
site that no longer match a file of this extension, or that are identical to
the shipped file:

```bash
vendor/bin/typo3 academic:upgrade:check academic_study_plan --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**.

### Site sets {#upgrade-from-2-4-to-3-0-site-sets}

A site that depends on `fgtclb/academic-study-plan-default` keeps
working. The set is an alias of `fgtclb/academic-study-plan`, which the
upgrade check reports as a notice and which goes away in version 4.0. Depend
on `fgtclb/academic-study-plan` instead, see
[What the sets contain](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:configuration-components@main).

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

### Site stylesheet {#upgrade-from-2-4-to-3-0-stylesheet}

The study plan ships no stylesheet any more. The file
`EXT:academic_study_plan/Resources/Public/Css/frontend/academic-study-plan.css`
of 2.4 is removed, and the page loads no stylesheet for the element. Style it
in the site package. Three parts of the element do not work without rules of
the site:

-   A semester header shows the expand and the collapse glyph at the same
    time. The stylesheet shows one of them.
-   The collapsible filter stays on screen while it is collapsed whenever a
    rule of the site gives the filter list a `display`. The stylesheet
    needs `.ace-filter .ace-list[hidden] { display: none }`.
-   The accordion of a narrow viewport and the highlighting of a category have
    no visible effect. The script only writes the classes `open` and
    `highlighted`.

The rules 2.4 shipped live on as an example, the stylesheet of the development
instances of the academic extensions. Copy what the site needs, or the rules of
the stylesheet the installation loaded so far, and adapt them to the theme. See
[Breaking: The study plan ships no stylesheet](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:breaking-study-plan-ships-no-stylesheet@main), [Style the element](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:styling@main) and the example
in [An example](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:styling-example@main).

### Speaking classes {#upgrade-from-2-4-to-3-0-classes}

The templates carry speaking classes with the prefix `ace-` now, instead of
the classes of the theme they were developed with. The content element keeps
`academic-study-plan`, but loses `container`. The filter, the semesters, the
modules and the dialog carry the classes the table of
[Breaking: Study plan templates carry speaking classes](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:breaking-study-plan-speaking-frontend-classes@main) lists, the grid classes
`row` and `col` stay. Move the selectors of the site stylesheet to the new
classes. How the markup of the study plan is built up is described in
[Styling](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:styling-markup@main), the class system of all academic extensions in the
[Styling chapter of academic_base](https://docs.typo3.org/p/fgtclb/academic-base/main/en-us/Styling/Index.html#styling).

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

The icons of the study plan are renamed, and the three controls of the
frontend are the shared action icons of **academic_base** now:

| 2.4 identifier | 3.0 identifier |
| --- | --- |
| `academic-study-plan` | `tx-academicstudyplan-plugin-study-plan` |
| `academic-study-plan-category` | `tx-academicstudyplan-record-category` |
| `academic-study-plan-semester` | `tx-academicstudyplan-record-semester` |
| `academic-study-plan-module` | `tx-academicstudyplan-record-module` |
| `academic-study-plan-plus` | `tx-academicbase-action-expand` |
| `academic-study-plan-minus` | `tx-academicbase-action-collapse` |
| `academic-study-plan-close` | `tx-academicbase-action-close` |

Replace the previous identifiers in TCA overrides, page TSconfig, templates and
selectors such as `.icon-academic-study-plan-plus`. A site package that
replaced a control registers its replacement under the 3.0 identifier in its
`Configuration/FrontendIcons.php`, not 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),
and depends on **academic_base**. The replacement then shows in every
academic extension that renders the icon. See
[Breaking: The study plan icons are renamed and the controls are frontend icons](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:breaking-study-plan-control-icons-moved-to-the-frontend-icon-registry@main)
and [The glyphs of a semester header](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:templates-glyphs@main).

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

The script of the study plan is an ES module now, which the template of the
content element loads with `<f:asset.module>`, and only on a page that
renders a study plan. The TypoScript of the extension no longer adds it, or
the stylesheet, to the page. Remove own `includeCSS` or
`includeJSFooter` entries for the files of 2.4 below
`frontend/`. A classic script tag does not run the module. See
[Breaking: The study plan assets are loaded by the template, as module](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:breaking-frontend-assets-are-es-modules@main).

An installation that overrode the template only to leave out the script, or to
bring its own, sets `plugin.tx_academicstudyplan.assets.js` to off
instead and drops the copy, see [Skip the script](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:asset-switches@main).

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

One template file changed in 3.0,
`Resources/Private/Frontend/Default/Templates/AcademicStudyPlan.html`,
and four partials are new. A copy of the 2.4 template in a site package keeps
rendering, but misses these changes. Compare it with the 3.0 files, or better,
replace it with an override of the one partial it is really about. The paths
below are relative to `Resources/Private/`:

| File | What changed | Entry |
| --- | --- | --- |
| `Frontend/Default/Templates/AcademicStudyPlan.html` | Renders the filter, the semesters, the modules and the dialogs through the partials `StudyPlan/Filter`, `StudyPlan/Semester`, `StudyPlan/Module` and `StudyPlan/ModuleDialog`, and marks every part the script drives with a `data-study-plan-*` attribute. | [Feature: Study plan partials and a markup contract](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:feature-study-plan-partials-and-data-attributes@main) |
| `Frontend/Default/Templates/AcademicStudyPlan.html` | Loads the script with `<f:asset.module>` inside an `<f:if>` on `settings.assets.js`, and registers no stylesheet. | [Skip the script](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:asset-switches@main) |
| `Frontend/Default/Partials/StudyPlan/Filter.html` | Renders the item the script clones with the attribute `hidden`, so its placeholder text never shows. | [Important: The study plan filter template item is hidden](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-study-plan-filter-template-item-is-hidden@main) |
| `Frontend/Default/Partials/StudyPlan/Semester.html`, `Frontend/Default/Partials/StudyPlan/ModuleDialog.html` | Render the controls with `<ab:icon>` of **academic_base** and the 3.0 identifiers, no longer with `<core:icon>`. | [The glyphs of a semester header](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:templates-glyphs@main) |
| `Frontend/Default/Partials/StudyPlan/Semester.html`, `Frontend/Default/Partials/StudyPlan/Module.html`, `Frontend/Default/Partials/StudyPlan/ModuleDialog.html` | Receive `idPrefix` and start the dialog id with it, so a plan shown again through an "Insert records" element opens its own dialogs. | [Important: A study plan shown again gets dialog ids of its own](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-study-plan-dialog-ids-in-inserted-records@main) |

The script still finds the parts of an override by the class names of 2.4 when
it carries none of the data attributes, but that fallback is deprecated and is
removed in version 4.0. Add the attributes on the elements
[The data attributes](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:templates-attributes@main) names. See
[Deprecation: The study plan class selectors](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:deprecation-study-plan-class-selectors@main).

The upgrade check with the extension key and the site lists the overrides of a
site that no longer match a file of the extension, see
[The upgrade check](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:upgrade-from-2-4-to-3-0-upgrade-check@main).

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

### A script of your own {#upgrade-from-2-4-to-3-0-own-script}

An installation that drives the study plan with a script of its own, with
`plugin.tx_academicstudyplan.assets.js` switched off or from a copy of
the template, takes the attribute `hidden` off every filter item it
builds from the template item, as the shipped script does:

```javascript
item.removeAttribute('hidden');
```

Without it, the filter shows no button at all. See
[Important: The study plan filter template item is hidden](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-study-plan-filter-template-item-is-hidden@main) and
[Feature: The study plan script can be switched off](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:feature-study-plan-assets-can-be-switched-off@main).

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

-   The backend list of the study plan categories opens, and a translated
    study plan renders. Both fail while the workspace columns are missing.
-   Existing study plans render with their semesters, modules and credit
    points. The new content element wizard offers the element as
    **Study Plan** now, with a new description, see
    [Important: Content elements have new titles and descriptions](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-content-element-titles-and-descriptions@main).
-   The category, semester and module records show icons in the text colour of
    the backend, also in a dark colour scheme, see
    [Important: Record icons follow the backend colour scheme](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-study-plan-record-icons-follow-the-colour-scheme@main).
-   A semester header shows one glyph, the filter highlights the modules of a
    category, and a module opens its dialog. The browser loads the module
    `@fgtclb/academic-study-plan/frontend/academic-study-plan.js` only
    on pages with a study plan, and no stylesheet of the extension.
-   On an installation that uses workspaces, the live site no longer shows
    semesters, modules or categories that only exist as a draft in a
    workspace, and a workspace preview shows the workspace state, see
    [Important: The study plan frontend is now workspace aware](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:important-1787924557@main).
-   The upgrade check exits with `0`, without the extension key and with
    it for every site that renders a study plan, see
    [The upgrade check](https://docs.typo3.org/permalink/fgtclb/academic-study-plan:upgrade-from-2-4-to-3-0-upgrade-check@main).