---
title: "Migration from version 4"
manual: "Calien - XLS Exporter"
version: "5.1"
permalink: "https://docs.typo3.org/permalink/calien/xlsexport:migration@5.1"
source: "Migration/Index.rst"
rendered: "2026-11-19T10:49:27+00:00"
---

# Migration from version 4 {#migration}

**Table of contents**

-   [Breaking changes](https://docs.typo3.org/permalink/calien/xlsexport:breaking-changes@5.1)
-   [Rewriting an export](https://docs.typo3.org/permalink/calien/xlsexport:rewriting-an-export@5.1)

Version 5 is a hard break. There is no automatic upgrade path, because the SQL statements of a
version 4 export cannot be translated to the declarative format without knowing their intent. Read the
[breaking changes](https://docs.typo3.org/permalink/calien/xlsexport:migration-breaking@5.1), then [rewrite each export](https://docs.typo3.org/permalink/calien/xlsexport:migration-rewrite@5.1).

## Breaking changes {#migration-breaking}

> [!WARNING]
> Existing exports stop working after the upgrade until they are rewritten.

### Supported versions {#supported-versions}

TYPO3 12 support is dropped. Version 5 requires TYPO3 13.4 LTS or 14.3 LTS and PHP 8.2 to 8.5, and
depends on [PhpSpreadsheet](https://phpspreadsheet.readthedocs.io/) 3.

### Export format and TSconfig namespace {#export-format-and-tsconfig-namespace}

The export format changed completely. The `check`, `list` and `export` SQL statements are
gone; an export is now the declarative definition described in [Configuration](https://docs.typo3.org/permalink/calien/xlsexport:configuration@5.1). The TSconfig
namespace also changed:

| Version 4 | Version 5 |
| --- | --- |
| `mod.tx_xlsexport.settings.exports.<key>` | `mod.web_xlsexport.<key>` |

### Extension points {#extension-points}

The Extbase controller was replaced by a plain backend controller. The legacy
`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['xlsexport']['alternateQueries']` hooks and the old
events (`AddColumnsToSheetEvent`, `AlternateCheckQueryEvent`, `AlternateExportQueryEvent`, the
former `AlternateHeaderLineEvent` and `ManipulateCellDataEvent`) were removed. Use the three
PSR-14 events under `\Calien\Xlsexport\Event\Export` instead — see [Developer](https://docs.typo3.org/permalink/calien/xlsexport:developer@5.1).

## Rewriting an export {#migration-rewrite}

Take the `export` query of a version 4 definition and express its parts as configuration: the
`FROM` table becomes `table`, the selected columns become `select`, and each
`WHERE` clause becomes a [condition](https://docs.typo3.org/permalink/calien/xlsexport:configuration-where@5.1). The `%d` placeholder that was
filled with the page id becomes `###CURRENT_ID###`.

**Version 4**

```typoscript
mod.tx_xlsexport.settings.exports {
    addresses {
        label = Addresses
        table = tt_address
        export (
            select uid, first_name, last_name from tt_address
            where pid = %d and deleted = 0 and hidden = 0
        )
        exportfields {
            10 = uid
            20 = first_name
            30 = last_name
        }
        exportfieldnames {
            10 = ID
            20 = First name
            30 = Last name
        }
    }
}
```

**Version 5**

```typoscript
mod.web_xlsexport {
    addresses {
        label = Addresses
        table = tt_address
        select {
            10 = uid
            20 = first_name
            30 = last_name
        }
        fieldLabels {
            10 = ID
            20 = First name
            30 = Last name
        }
        where {
            10 {
                fieldName = pid
                parameter = ###CURRENT_ID###
                expressionType = eq
                type = int
            }
        }
    }
}
```

> [!NOTE]
> The `deleted` and `hidden` conditions from the version 4 SQL are no longer needed: the
> QueryBuilder applies TYPO3's default record restrictions automatically.
