Feature: #107519 - Add "discard" command to DataHandler 

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 

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 

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.

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();

$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();

Migration from legacy commands 

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

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

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