---
title: "Feature: #107519 - Add \"discard\" command to DataHandler"
manual: "TYPO3 Core Changelog"
version: "main"
permalink: "https://docs.typo3.org/permalink/changelog:feature-107519-1742215067"
source: "Changelog/14.0/Feature-107519-AddDiscardCommandToDataHandler.rst"
typo3-version: "14.0"
typo3-major: 14
type: "feature"
issue: 107519
forge: "https://forge.typo3.org/issues/107519"
tags: ["PHP-API", "ext:core"]
rendered: "2026-09-18T17:00:34+00:00"
---

# Feature: #107519 - Add "discard" command to DataHandler {#feature-107519-1742215067}

See [forge#107519](https://forge.typo3.org/issues/107519)

## Description {#description}

The `\TYPO3\CMS\Core\DataHandling\DataHandler` PHP API has been
extended with a new `"discard"` command to simplify workspace management.

This new command provides a cleaner, more explicit way to discard workspace
records compared to the previous approach using version commands.

The new `"discard"` command can be used in the `$commandArray` parameter
when calling the DataHandler to remove versioned records from a workspace.

## Impact {#impact}

The `"discard"` command offers a more intuitive API for workspace operations:

-   Instead of using complex version commands with actions such as `"clearWSID"`
    or `"flush"`, you can now use the straightforward `"discard"` command.
-   The command name clearly indicates its purpose.
-   The command handles all aspects of discarding workspace records, including
    any related child records.

## Usage {#usage}

When using the `discard` command, it is crucial to use the UID of the
versioned record (workspace version), not the UID of the live record.

**Discarding a workspace record using DataHandler**

```php
use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Utility\GeneralUtility;

// Example: Discard a versioned page record
$versionedPageUid = 123; // This must be the UID of the workspace version!

$commandArray = [
    'pages' => [
        $versionedPageUid => [
            'discard' => true,
        ],
    ],
];

$dataHandler = GeneralUtility::makeInstance(DataHandler::class);
$dataHandler->start([], $commandArray);
$dataHandler->process_cmdmap();
```

**Discarding multiple records of different types**

```php
$commandArray = [
    'pages' => [
        456 => ['discard' => true], // Versioned page UID
    ],
    'tt_content' => [
        789 => ['discard' => true], // Versioned content element UID
        790 => ['discard' => true], // Another versioned content element UID
    ],
];

$dataHandler = GeneralUtility::makeInstance(DataHandler::class);
$dataHandler->start([], $commandArray);
$dataHandler->process_cmdmap();
```

> [!IMPORTANT]
> Always ensure that you are using the UID of the versioned record when
> discarding workspace records. Using the live record's UID will not work as
> expected. You can identify versioned records by checking that
> `t3ver_wsid` \> 0 and `t3ver_oid` points to the live record.

## Migration from legacy commands {#migration-from-legacy-commands}

The new `discard` command replaces the previous version-based approach,
which was not widely known:

**Legacy approach (still supported but discouraged)**

```php
// Old way - will be removed in future versions
$commandArray = [
    'pages' => [
        $versionedUid => [
            'version' => [
                'action' => 'clearWSID',
            ],
        ],
    ],
];
```

**New recommended approach**

```php
// New way - cleaner and more explicit
$commandArray = [
    'pages' => [
        $versionedUid => [
            'discard' => true,
        ],
    ],
];
```

The previous `clearWSID` and `flush` actions are still supported for
backward compatibility but are considered deprecated and will be removed in
future versions.