121 lines
3.6 KiB
ReStructuredText
121 lines
3.6 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
|
|
|
.. _feature-107519-1742215067:
|
|
|
|
=======================================================
|
|
Feature: #107519 - Add "discard" command to DataHandler
|
|
=======================================================
|
|
|
|
See :issue:`107519`
|
|
|
|
Description
|
|
===========
|
|
|
|
The :php:`\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 :php:`$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.
|
|
|
|
.. code-block:: php
|
|
:caption: Discarding a workspace record using DataHandler
|
|
|
|
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();
|
|
|
|
.. code-block:: php
|
|
:caption: Discarding multiple records of different types
|
|
|
|
$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
|
|
:sql:`t3ver_wsid` > 0 and :sql:`t3ver_oid` points to the live record.
|
|
|
|
Migration from legacy commands
|
|
==============================
|
|
|
|
The new `discard` command replaces the previous version-based approach,
|
|
which was not widely known:
|
|
|
|
.. code-block:: php
|
|
:caption: Legacy approach (still supported but discouraged)
|
|
|
|
// Old way - will be removed in future versions
|
|
$commandArray = [
|
|
'pages' => [
|
|
$versionedUid => [
|
|
'version' => [
|
|
'action' => 'clearWSID',
|
|
],
|
|
],
|
|
],
|
|
];
|
|
|
|
.. code-block:: php
|
|
:caption: New recommended approach
|
|
|
|
// 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.
|
|
|
|
.. index:: PHP-API, ext:core
|