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

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

Version 3.0 of **academic_projects** runs on TYPO3 13 and 14 only. The
project page renders inside the layout of the site and carries its content
itself, so the content load set of 2.4 is gone. The department category type of
this extension is renamed to `project_department`, the templates carry speaking
classes in place of the classes of a theme, the icons are replaced, and the
controller is final. 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_projects** 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 in place of 1.x. Composer updates it
    on its own. A classic installation updates
    **environment_state_manager** before it updates
    **academic_base**.
-   [`fgtclb/academic-base`](https://packagist.org/packages/fgtclb/academic-base) 3.0, the same release as this extension.
-   [`fgtclb/category-types`](https://packagist.org/packages/fgtclb/category-types) 3.0, the same release as this extension.

These changes have to ship in the same deployment as the update, because a
site, a request or a command fails until they are made:

-   A site that depends on `fgtclb/academic-projects-content-load` answers
    every page with HTTP 500, see
    [Remove the content load set](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-content-load@main).
-   A `Configuration/CategoryTypes.yaml` of the site package that changes
    or declares the type `department` of the group `projects` stops
    TYPO3 while it loads the category types, see
    [Rename the department category type](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-department@main).
-   A subclass or an XCLASS of the project controller stops with a fatal
    error, and so does code that names the renamed sorting constant, see
    [Adapt your code](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-code@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. The content element wizard
`academicProjects_pluginUpgradeWizard` 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_jobs**, **academic_persons** and
**academic_persons_edit** 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-projects: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-projects: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/category-types':'~3.0.0' \
    'fgtclb/academic-projects':'~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**, **category_types** and
**academic_projects** 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**.

This extension changes no column in 3.0. The comparison applies the changes of
the index definitions TYPO3 13.4.35 and 14.3.7 bring.

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

1.  `academicProjects_pluginUpgradeWizard`, **Migrate
    academic_projects plugins from "list_type" to "CType".**, on TYPO3 13,
    before the site moves to TYPO3 14. It turns the **Insert plugin**
    content elements of the plugins `academicprojects_projectlist` and
    `academicprojects_projectlistsingle` into content elements of the type
    of the same name, and it reads `tt_content.list_type`, which TYPO3 14
    no longer has. See [Breaking: Extbase plugins require CType on TYPO3 v14](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-plugins-require-ctype-on-typo3-v14@main).

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

    An installation that ran it with 2.4 has nothing left to migrate, and
    TYPO3 offers it only while an element of the old shape is left. Do not
    postpone it to TYPO3 14: once the database comparison of TYPO3 14 has
    removed the column, the wizard finds nothing to do and is recorded as done,
    and nothing records any more which plugin such a content element was.
    Configuration of the site that matches these plugins on `list_type`
    matches on `CType` instead.

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>`.

Version 3.0 adds no upgrade wizard for this extension. The department category
type is moved by a console command, see
[Rename the department category type](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-department@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 what no longer
reaches the academic extensions. For this extension it reports a dependency on
the removed content load set and an XCLASS of the controller, but neither a
subclass that is registered another way nor the category type file. Run it on
the staging copy right after the package update, and fix what it reports
before the deployment:

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

With the extension key and a site it also compares the override folders of the
site with the shipped files and reports an override of a file the extension no
longer ships:

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

Each finding, and what to do about it, is described in the upgrade check
of **academic_base**.

### Remove the content load set {#upgrade-from-2-4-to-3-0-content-load}

The project page renders the content of its main column from the variable
`projectContent` of its own page object now. The set
`fgtclb/academic-projects-content-load`, its static template
**Academic Projects: Content load override (academic_projects)** and
the file [`Configuration/TypoScript/ContentLoad/setup.typoscript`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.html#file-extension-configuration-typoscriptsetup-typoscript) are
removed, and no academic extension defines
`styles.content.getContent` any more. See
[Breaking: Project pages render their content without a global path](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-projects-content-load-set-removed@main).

1.  Remove `fgtclb/academic-projects-content-load` from the
    `dependencies` of every site configuration and of every set of the
    site package, in the same deployment as the update. A site that depends on
    the aggregate `fgtclb/academic-projects` needs no change.
1.  Remove the static template **Academic Projects: Content load
    override (academic_projects)** from every `sys_template` record, and an
    `@import` of the removed file from the site package.
1.  Move a customisation of `styles.content.getContent` that was
    meant for project pages to `page.10.variables.projectContent`,
    inside the condition on the project page type, see
    [The content of a project page](https://docs.typo3.org/permalink/fgtclb/academic-projects:project-page-content@main).
1.  A template of the site package that renders
    `styles.content.getContent` defines the object itself:

    ```typoscript
    styles.content.getContent < styles.content.get
    styles.content.getContent.select.where = {#colPos}=0
    ```

`academic:upgrade:check` reports a site that depends on the removed set as
`unavailable-set`, the removed static template as
`static-template` and an import of the removed file as
`typoscript-import`.

### Rename the department category type {#upgrade-from-2-4-to-3-0-department}

The department type of this extension is `project_department` now, because
**academic_programs** declares a type `department` as well and a
category stores its type without the group. Its label key and its icon
identifier follow. See
[Breaking: The projects department type is renamed](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-projects-project-department-category-type@main).

1.  Replace `department` with `project_department` in every
    `Configuration/CategoryTypes.yaml` of the site that changes or
    removes the type of the group `projects`, in the same deployment as
    the update. Not before it: 2.4 has no `project_department` to change.
1.  After the update and the cache flush, move the stored categories:

    ```bash
    vendor/bin/typo3 academic:projects:department:migrate
    ```

    The command lists the categories it cannot decide on. Open each of them in
    the backend and set its type. It can be run again. A site that removed the
    projects department in its `CategoryTypes.yaml` does not run it.
1.  Replace `department` with `project_department` in
    `plugin.tx_academicprojects.filter.categoryTypes` and in the
    templates of the site. Search the site package for
    `sys_category.projects.department` and
    `category_types.projects.department` as well.
1.  Flush the page cache.

### Check own route enhancers {#upgrade-from-2-4-to-3-0-route-enhancers}

The project lists answer a filter submission with a redirect to a URL that
carries the selection. A route enhancer of the site for these plugins must not
declare `defaults` for the sorting: the redirect for the default sorting
would otherwise end on the page URL without arguments, where the preset of the
content element applies again. Remove such `defaults`, or import the
enhancers of `Configuration/Routes/List.yaml` instead, see
[Feature: Project filter selections have a URL](https://docs.typo3.org/permalink/fgtclb/academic-projects:feature-1790226101@main) and [Feature: Route enhancers for the project lists](https://docs.typo3.org/permalink/fgtclb/academic-projects:feature-1791043403@main).

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

### Style the new markup {#upgrade-from-2-4-to-3-0-stylesheets}

The templates of this extension carry speaking classes now, such as `ace-item`,
`ace-list`, `ace-attribute`, `ace-label` and `ace-value`, in place of the card,
list group and utility classes of a theme. The extension ships no styles for
them. Move the selectors of the site stylesheet from the old classes to the new
ones, the changelog entry lists them side by side, see
[Breaking: Project templates carry speaking classes](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-projects-speaking-frontend-classes@main). [Styling](https://docs.typo3.org/permalink/fgtclb/academic-projects:styling@main) shows the
markup of every view and links the stylesheet partial the development instances
of the academic extensions use, [An example](https://docs.typo3.org/permalink/fgtclb/academic-projects:styling-example@main).

The images of the project list and the project page render as a
`<picture>` through the image partial of **academic_base**. CSS
that selects the image as a direct child of its container adjusts to the
wrapper. A plugin view whose partial root paths the site replaced completely
needs the path of **academic_base** below its own:

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

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

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

The project page type and the two content elements have icons of their own,
`tx-academicprojects-doktype-project` and
`tx-academicprojects-plugin-projects`, in place of the core icon
`actions-code-merge`. CSS that addressed them through that identifier names
the new one. The category type icons keep their identifiers, but are new
drawings from new files and render as an inline `<svg>` in the frontend,
so CSS that addressed an `<img>` addresses the `<svg>` now, and a
path to a file below `Resources/Public/Icons/CategoryTypes/` points at the
new file. See
[Breaking: Project icons are replaced and follow the colour scheme](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-projects-category-icons-follow-the-colour-scheme@main) and
[Important: Category type icons come from the frontend icon registry](https://docs.typo3.org/permalink/fgtclb/academic-projects:important-projects-category-icons-come-from-the-frontend-icon-registry@main).

### Render project pages in the site layout {#upgrade-from-2-4-to-3-0-page}

The page template of the project page type renders the section `Main` of
the layout `Default` of the site package, through five partials below
`Project/Page/`. A project page shows the header, the navigation and the
footer of the site now. See
[Breaking: Project pages render inside the site layout](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-project-page-renders-inside-the-site-layout@main).

-   A site package whose layout for project pages has another name sets
    `plugin.tx_academicprojects.page.layout`, see
    [The layout of a project page](https://docs.typo3.org/permalink/fgtclb/academic-projects:project-page-layout@main).
-   An override of `Pages/AcademicProject.html` made to change one part
    moves that change to the matching partial below `Project/Page/`, see
    [The parts of a project page](https://docs.typo3.org/permalink/fgtclb/academic-projects:project-page-partials@main), and the override goes.
-   A path the site set at the key `100` inside the condition on the project
    page type moves to `50`, or to a key above it to win over the extension.

### Compare 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, see [Overriding templates](https://docs.typo3.org/permalink/fgtclb/academic-projects:templates-override@main). The paths below
are relative to `Resources/Private/`:

| File | What changed | Entry |
| --- | --- | --- |
| `Pages/AcademicProject.html` | Renders the layout of the site and the partials below `Project/Page/`, and the content from `{projectContent -> f:format.raw()}` in place of `styles.content.getContent`. | [Render project pages in the site layout](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-page@main), [Remove the content load set](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-content-load@main) |
| `Templates/Project/List.html` | Renders the header of the content element while `renderContentElementHeader` is switched on. | [Feature: The project lists can render the content element header](https://docs.typo3.org/permalink/fgtclb/academic-projects:feature-1790440964@main) |
| `Partials/Project/SortingAndFilters.html` | Renders the new partials `Project/ActiveFilters.html` and `Project/ResultCount.html`. | [Feature: Active filter tags, a reset link and a result count](https://docs.typo3.org/permalink/fgtclb/academic-projects:feature-1790946475@main) |
| `Partials/Project/Item.html` | Renders the image through `Academic/Image.html` of **academic_base**, the category icons with the `ab:icon` ViewHelper, the title of an own category type, and the state of the project when the content element asks for it. | [Style the new markup](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-stylesheets@main), [Replace the icons](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-icons@main), [Feature: Own category types are named by their title](https://docs.typo3.org/permalink/fgtclb/academic-projects:feature-1791035984@main), [Feature: The state of a project on its card](https://docs.typo3.org/permalink/fgtclb/academic-projects:feature-project-active-state-badge@main) |
| `Partials/Project/DemandCategories.html` | Labels an own category type by its title. | [Feature: Own category types are named by their title](https://docs.typo3.org/permalink/fgtclb/academic-projects:feature-1791035984@main) |
| `Partials/Project/Header.html` | Takes the class of the heading as `class` in place of `positionClass`. | [Style the new markup](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-stylesheets@main) |
| Every file above, and `Partials/Project/DemandActiveState.html`, `Partials/Project/DemandSorting.html`, `Partials/Project/ItemList.html` | Speaking classes in place of the classes of a theme. | [Style the new markup](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-stylesheets@main) |

The upgrade check with the extension key and a site reports an override of a
file the extension no longer ships, see
[The upgrade check](https://docs.typo3.org/permalink/fgtclb/academic-projects:upgrade-from-2-4-to-3-0-upgrade-check@main).

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

-   `\FGTCLB\AcademicProjects\Controller\ProjectController` is final. A
    subclass, and an XCLASS of it, stop with a fatal error. Remove them, and
    the `configurePlugin()` call or the XCLASS registration that points at
    them, in the same deployment as the update. Move what they did to a
    listener of the project events, see [Breaking: The project controller is final](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-1791043407@main) and
    [For developers](https://docs.typo3.org/permalink/fgtclb/academic-projects:developers@main).
-   `SortingOptions::SORT_BY_STARTDATE_desc` is renamed to
    `SortingOptions::SORT_BY_STARTDATE_DESC`, without an alias. Its value
    and every stored sorting stay as they are. See
    [Breaking: The descending start date constant is renamed](https://docs.typo3.org/permalink/fgtclb/academic-projects:breaking-start-date-sorting-constant-renamed@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-projects:upgrade-from-2-4-to-3-0-upgrade-check@main). Run it again after each
    configuration step, and in the deployment pipeline.
-   The content elements are offered as **Projects** and
    **Selected Projects** now, see
    [Important: Content elements have new titles and descriptions](https://docs.typo3.org/permalink/fgtclb/academic-projects:important-content-element-titles-and-descriptions@main).
-   Every page of a site answers, none with HTTP 500.
-   `vendor/bin/typo3 academic:projects:department:migrate` lists no
    category left to decide on.
-   A project page renders inside the layout of the site, with its content and
    its categories, the department among them.
-   The project lists look as the site intends, with the speaking classes, and
    their department filter offers the departments of projects only.
-   A list keeps its preset categories of the category types its filter does
    not offer, see
    [Important: A filter keeps the preset categories of other types](https://docs.typo3.org/permalink/fgtclb/academic-projects:important-project-list-keeps-default-categories-of-other-types@main).