TYPO3 DataHandler: Why Direct SQL in Extensions is a Risk

<?php
declare(strict_types=1);

namespace Vendor\Extension\Service;

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

final class ContentService
{
    public function createOrUpdate(array $data, array $cmd = []): array
    {
        $dataHandler = GeneralUtility::makeInstance(DataHandler::class);
        $dataHandler->start($data, $cmd);

        if ($data !== []) {
            $dataHandler->process_datamap();
        }

        if ($cmd !== []) {
            $dataHandler->process_cmdmap();
        }

        if ($dataHandler->errorLog !== []) {
            throw new \RuntimeException(
                'DataHandler error: ' . implode(', ', $dataHandler->errorLog),
                1700000001
            );
        }

        return $dataHandler->substNEWwithIDs;
    }
}

<?php
declare(strict_types=1);

namespace Vendor\Extension\Service;

use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Utility\GeneralUtility;

final class TransactionalService
{
    public function __construct(
        private readonly ConnectionPool $connectionPool,
    ) {}

    public function batchOperation(array $data, array $cmd = []): array
    {
        $dataHandler = GeneralUtility::makeInstance(DataHandler::class);
        $dataHandler->start($data, $cmd);

        $connection = $this->connectionPool->getConnectionForTable('tt_content');
        $connection->beginTransaction();

        try {
            if ($data !== []) {
                $dataHandler->process_datamap();
            }
            if ($cmd !== []) {
                $dataHandler->process_cmdmap();
            }

            if ($dataHandler->errorLog !== []) {
                throw new \RuntimeException(
                    'DataHandler error: ' . implode(', ', $dataHandler->errorLog),
                    1700000002
                );
            }

            $connection->commit();
            return $dataHandler->substNEWwithIDs;
        } catch (\Throwable $e) {
            $connection->rollBack();
            throw $e;
        }
    }
}

<?php
declare(strict_types=1);

namespace Vendor\Extension\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use TYPO3\CMS\Core\Core\Bootstrap;
use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Utility\GeneralUtility;

#[AsCommand(
    name: 'myext:import',
    description: 'Imports data via the DataHandler',
)]
final class ImportCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        Bootstrap::initializeBackendAuthentication();

        $data = [
            'pages' => [
                'NEW_import' => [
                    'pid' => 1,
                    'title' => 'Imported page',
                ],
            ],
        ];

        $dataHandler = GeneralUtility::makeInstance(DataHandler::class);
        $dataHandler->start($data, []);
        $dataHandler->process_datamap();

        if ($dataHandler->errorLog !== []) {
            $output->writeln('<error>Error: ' . implode(', ', $dataHandler->errorLog) . '</error>');
            return Command::FAILURE;
        }

        $newUid = $dataHandler->substNEWwithIDs['NEW_import'];
        $output->writeln("<info>Page created with UID: {$newUid}</info>");

        return Command::SUCCESS;
    }
}

<?php
declare(strict_types=1);

// ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][]
    = \Vendor\Extension\Hooks\DataHandlerHook::class;

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processCmdmapClass'][]
    = \Vendor\Extension\Hooks\DataHandlerHook::class;

<?php
declare(strict_types=1);

namespace Vendor\Extension\Hooks;

use Psr\Log\LoggerInterface;
use TYPO3\CMS\Core\DataHandling\DataHandler;

final class DataHandlerHook
{
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}

    public function processDatamap_afterDatabaseOperations(
        string $status,
        string $table,
        string|int $id,
        array $fieldArray,
        DataHandler $dataHandler
    ): void {
        if ($table !== 'tx_myext_domain_model_item') {
            return;
        }

        if ($status === 'new') {
            $newUid = $dataHandler->substNEWwithIDs[$id] ?? $id;
            $this->logger->info('New record created', [
                'table' => $table,
                'uid' => $newUid,
                'fields' => $fieldArray,
            ]);
        }

        if ($status === 'update') {
            $this->logger->info('Record updated', [
                'table' => $table,
                'uid' => $id,
                'changedFields' => array_keys($fieldArray),
            ]);
        }
    }
}

# Check and update Reference Index
vendor/bin/typo3 referenceindex:update

<?php
declare(strict_types=1);

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

$dataHandler->clear_cacheCmd(42);      // Cache for page 42
$dataHandler->clear_cacheCmd('pages'); // All page caches
$dataHandler->clear_cacheCmd('all');   // All cache groups (admins only)

<?php
declare(strict_types=1);

$workspaceId = $GLOBALS['BE_USER']->workspace;

if ($workspaceId > 0) {
    // In the workspace: DataHandler creates versioned records
    // For read access: use Workspace Overlay
}

// For operations that should explicitly run in the Live Workspace:
$previousWorkspace = $GLOBALS['BE_USER']->workspace;
$GLOBALS['BE_USER']->setWorkspace(0);

// ... DataHandler operations ...

$GLOBALS['BE_USER']->setWorkspace($previousWorkspace);

<?php
declare(strict_types=1);

// v13: Copy behaviour via DataHandler properties
$dataHandler->neverHideAtCopy = true;
$dataHandler->copyTree = 2;

// v14: Read values from the backend user object
$dataHandler->BE_USER->uc['neverHideAtCopy'] = true;
$dataHandler->BE_USER->uc['copyLevels'] = 2;