# Instead of:
fileadmin/reports/geschaeftsbericht2025.pdf

# Use hashed/random names:
fileadmin/reports/gb-a8f3e2b1c9d4.pdf

// config/system/settings.php
// Use a private storage that is NOT publicly accessible
// Deliver files programmatically via a controller

# Apache (.htaccess in a subdirectory)
<IfModule mod_authz_core.c>
    Require all denied
</IfModule>

# NGINX
location /fileadmin/confidential/ {
    deny all;
    return 403;
}

# Composer (v13/v14)
composer require typo3/cms-workspaces

# Non-Composer: activate in Admin Tools > Extensions

<?php

declare(strict_types=1);

namespace MyVendor\MySitepackage\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;
use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Utility\GeneralUtility;

/**
 * CLI command to create a workspace with base configuration.
 *
 * Register in Configuration/Services.yaml:
 *   console.command.tag: 'console.command'
 *   command: 'workspace:setup'
 */
final class SetupWorkspaceCommand extends Command
{
    protected function configure(): void
    {
        $this->setDescription('Create a workspace with backend group and base configuration');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);

        // Step 1: Create backend user group for workspace editors
        $data = [];
        $data['be_groups']['NEW_ws_group'] = [
            'pid' => 0,
            'title' => 'Workspace Editors',
            'description' => 'Backend group for workspace editing access',
            // Grant access to common tables
            'tables_modify' => 'pages,tt_content,sys_file_reference',
            'tables_select' => 'pages,tt_content,sys_file_reference,sys_file',
            // Grant LIVE workspace access
            'workspace_perms' => 1,
            // Page types allowed
            'pagetypes_select' => '1,3,4,6,7,199,254',
            // Explicitly allow content types
            'explicit_allowdeny' => '',
        ];

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

        if (!empty($dataHandler->errorLog)) {
            $io->error('Failed to create backend group: ' . implode(', ', $dataHandler->errorLog));
            return Command::FAILURE;
        }

        $groupUid = $dataHandler->substNEWwithIDs['NEW_ws_group'] ?? 0;
        $io->success('Created backend group "Workspace Editors" (uid=' . $groupUid . ')');

        // Step 2: Create the custom workspace
        $data = [];
        $data['sys_workspace']['NEW_workspace'] = [
            'pid' => 0,
            'title' => 'Staging Workspace',
            'description' => 'Content staging workspace for preview and review before publishing',
            'adminusers' => 'be_groups_' . $groupUid,
            'members' => 'be_groups_' . $groupUid,
            // Stages: default stages (Editing, Ready to publish) are always available
            // Publish access: 0 = no restriction, 1 = only publish-stage content, 2 = only owners can publish
            'publish_access' => 0,
            // Allow editing of non-versionable records (live edit)
            'edit_allow_notificaton_settings' => 0,
        ];

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

        if (!empty($dataHandler->errorLog)) {
            $io->error('Failed to create workspace: ' . implode(', ', $dataHandler->errorLog));
            return Command::FAILURE;
        }

        $wsUid = $dataHandler->substNEWwithIDs['NEW_workspace'] ?? 0;
        $io->success('Created workspace "Staging Workspace" (uid=' . $wsUid . ')');

        $io->section('Next Steps');
        $io->listing([
            'Assign backend users to the "Workspace Editors" group',
            'Configure DB mounts and file mounts on the group',
            'Set up Scheduler tasks: "Workspaces auto-publication" + "Workspaces cleanup preview links"',
            'Configure TSconfig: options.workspaces.previewLinkTTLHours = 48',
            'Test: switch to the workspace in the backend top bar and edit a page',
        ]);

        return Command::SUCCESS;
    }
}

services:
  MyVendor\MySitepackage\Command\SetupWorkspaceCommand:
    tags:
      - name: 'console.command'
        command: 'workspace:setup'
        description: 'Create workspace with base configuration'

# DDEV
ddev exec bin/typo3 workspace:setup

# Non-DDEV
bin/typo3 workspace:setup

-- ============================================================
-- LOCAL DDEV ONLY - Workspace base configuration
-- Save this block as setup-workspace.sql, then run: ddev mysql < setup-workspace.sql
-- ============================================================

-- 1. Create backend user group for workspace editors
INSERT INTO be_groups (pid, title, description, workspace_perms, tables_modify, tables_select, pagetypes_select, tstamp, crdate)
VALUES (
    0,
    'Workspace Editors',
    'Backend group for workspace editing access',
    1,  -- 1 = access to LIVE workspace
    'pages,tt_content,sys_file_reference',
    'pages,tt_content,sys_file_reference,sys_file',
    '1,3,4,6,7,199,254',
    UNIX_TIMESTAMP(),
    UNIX_TIMESTAMP()
);

SET @group_uid = LAST_INSERT_ID();

-- 2. Create custom workspace
INSERT INTO sys_workspace (pid, title, description, adminusers, members, publish_access, tstamp, crdate)
VALUES (
    0,
    'Staging Workspace',
    'Content staging workspace for preview and review before publishing',
    CONCAT('be_groups_', @group_uid),
    CONCAT('be_groups_', @group_uid),
    0,  -- 0 = no publish restriction
    UNIX_TIMESTAMP(),
    UNIX_TIMESTAMP()
);

SET @ws_uid = LAST_INSERT_ID();

-- 3. Verify
SELECT 'Backend Group' AS type, @group_uid AS uid, 'Workspace Editors' AS title
UNION ALL
SELECT 'Workspace' AS type, @ws_uid AS uid, 'Staging Workspace' AS title;

-- 4. Check existing workspace-enabled tables
SELECT TABLE_NAME
FROM information_schema.COLUMNS
WHERE COLUMN_NAME = 't3ver_oid'
  AND TABLE_SCHEMA = DATABASE()
ORDER BY TABLE_NAME;

# Run in DDEV:
ddev mysql < setup-workspace.sql

<?php
// EXT:my_extension/Configuration/TCA/tx_myextension_domain_model_item.php

return [
    'ctrl' => [
        'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_db.xlf:tx_myextension_domain_model_item',
        'label' => 'title',
        'tstamp' => 'tstamp',
        'crdate' => 'crdate',
        'delete' => 'deleted',
        'sortby' => 'sorting',
        // Enable workspace versioning
        'versioningWS' => true,
        // Language support
        'languageField' => 'sys_language_uid',
        'transOrigPointerField' => 'l10n_parent',
        'transOrigDiffSourceField' => 'l10n_diffsource',
        'translationSource' => 'l10n_source',
        'enablecolumns' => [
            'disabled' => 'hidden',
            'starttime' => 'starttime',
            'endtime' => 'endtime',
        ],
        'iconfile' => 'EXT:my_extension/Resources/Public/Icons/item.svg',
    ],
    // ... columns, types, palettes
];

bin/typo3 database:updateschema

<?php
// EXT:my_extension/Configuration/TCA/Overrides/tx_myextension_log.php

$GLOBALS['TCA']['tx_myextension_log']['ctrl']['versioningWS'] = false;

<?php
// EXT:my_extension/Configuration/TCA/Overrides/tx_myextension_settings.php

// Records of this table are edited live even when a workspace is active
$GLOBALS['TCA']['tx_myextension_settings']['ctrl']['versioningWS_alwaysAllowLiveEdit'] = true;

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use TYPO3\CMS\Backend\Utility\BackendUtility;
use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\ConnectionPool;

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

    /**
     * Fetch a single record with workspace overlay.
     */
    public function getItem(int $uid): ?array
    {
        // Option A: One-liner (recommended)
        $row = BackendUtility::getRecordWSOL('tx_myextension_domain_model_item', $uid);

        // Option B: Manual (equivalent to A)
        // $row = BackendUtility::getRecord('tx_myextension_domain_model_item', $uid);
        // BackendUtility::workspaceOL('tx_myextension_domain_model_item', $row);

        return is_array($row) ? $row : null;
    }

    /**
     * Fetch multiple records with workspace overlay.
     */
    public function getItemsByPage(int $pageId): array
    {
        $queryBuilder = $this->connectionPool
            ->getQueryBuilderForTable('tx_myextension_domain_model_item');

        $result = $queryBuilder
            ->select('*')
            ->from('tx_myextension_domain_model_item')
            ->where(
                $queryBuilder->expr()->eq(
                    'pid',
                    $queryBuilder->createNamedParameter($pageId, Connection::PARAM_INT)
                )
            )
            ->executeQuery();

        $items = [];
        while ($row = $result->fetchAssociative()) {
            // CRITICAL: Apply workspace overlay to each row
            BackendUtility::workspaceOL('tx_myextension_domain_model_item', $row);
            if (is_array($row)) {
                $items[] = $row;
            }
        }

        return $items;
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Domain\Repository\PageRepository;

final class ItemService
{
    public function __construct(
        private readonly ConnectionPool $connectionPool,
        private readonly PageRepository $pageRepository,
    ) {}

    /**
     * Fetch items with workspace + language overlay for frontend rendering.
     */
    public function findByPage(int $pageId): array
    {
        $queryBuilder = $this->connectionPool
            ->getQueryBuilderForTable('tx_myextension_domain_model_item');

        $result = $queryBuilder
            ->select('*')
            ->from('tx_myextension_domain_model_item')
            ->where(
                $queryBuilder->expr()->eq(
                    'pid',
                    $queryBuilder->createNamedParameter($pageId, Connection::PARAM_INT)
                )
            )
            ->executeQuery();

        $items = [];
        while ($row = $result->fetchAssociative()) {
            // Apply workspace overlay (MUST be called before language overlay)
            $this->pageRepository->versionOL('tx_myextension_domain_model_item', $row);
            if (!is_array($row)) {
                continue;
            }
            // Apply language overlay
            $row = $this->pageRepository->getLanguageOverlay(
                'tx_myextension_domain_model_item',
                $row
            );
            if (is_array($row)) {
                $items[] = $row;
            }
        }

        return $items;
    }
}

<?php
// EXT:my_extension/Configuration/Backend/Modules.php

return [
    'my_module' => [
        'parent' => 'web',
        'position' => ['after' => 'web_info'],
        'access' => 'user',
        // Control workspace availability:
        // '*'       = available in all workspaces (default)
        // 'live'    = only available in live workspace
        // 'offline' = only available in custom workspaces
        'workspaces' => '*',
        'iconIdentifier' => 'my-module-icon',
        'labels' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_mod.xlf',
        'routes' => [
            '_default' => [
                'target' => \MyVendor\MyExtension\Controller\MyModuleController::class . '::handleRequest',
            ],
        ],
    ],
];

<?php
// WRONG: Does not respect workspaces
$queryBuilder = $this->connectionPool->getQueryBuilderForTable('tt_content');
$rows = $queryBuilder
    ->select('*')
    ->from('tt_content')
    ->where(
        $queryBuilder->expr()->eq('pid', $queryBuilder->createNamedParameter($pageId, Connection::PARAM_INT))
    )
    ->executeQuery()
    ->fetchAllAssociative();

// Rows may include workspace placeholders and miss workspace versions!

<?php

use TYPO3\CMS\Backend\Utility\BackendUtility;
use TYPO3\CMS\Core\Database\Connection;

$queryBuilder = $this->connectionPool->getQueryBuilderForTable('tt_content');
$result = $queryBuilder
    ->select('*')
    ->from('tt_content')
    ->where(
        $queryBuilder->expr()->eq('pid', $queryBuilder->createNamedParameter($pageId, Connection::PARAM_INT))
    )
    ->executeQuery();

$rows = [];
while ($row = $result->fetchAssociative()) {
    // Apply workspace overlay
    BackendUtility::workspaceOL('tt_content', $row);
    if (is_array($row)) {
        $rows[] = $row;
    }
}

<?php
// WRONG for frontend: Missing WorkspaceRestriction
$queryBuilder = $this->connectionPool->getQueryBuilderForTable('tx_news_domain_model_news');
$queryBuilder->getRestrictions()->removeAll()->add(
    GeneralUtility::makeInstance(DeletedRestriction::class)
);

<?php

use TYPO3\CMS\Core\Database\Query\Restriction\FrontendRestrictionContainer;

// FrontendRestrictionContainer includes:
// - DeletedRestriction
// - HiddenRestriction
// - StartTimeRestriction
// - EndTimeRestriction
// - WorkspaceRestriction  <-- automatically included!
// - FrontendGroupRestriction
$queryBuilder = $this->connectionPool->getQueryBuilderForTable('tx_news_domain_model_news');
$queryBuilder->setRestrictions(
    GeneralUtility::makeInstance(FrontendRestrictionContainer::class)
);

<?php

use TYPO3\CMS\Core\Database\Query\Restriction\DeletedRestriction;
use TYPO3\CMS\Core\Database\Query\Restriction\WorkspaceRestriction;
use TYPO3\CMS\Core\Context\Context;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$workspaceId = GeneralUtility::makeInstance(Context::class)
    ->getPropertyFromAspect('workspace', 'id', 0);

$queryBuilder = $this->connectionPool->getQueryBuilderForTable('tx_myext_item');
$queryBuilder->getRestrictions()
    ->removeAll()
    ->add(GeneralUtility::makeInstance(DeletedRestriction::class))
    ->add(GeneralUtility::makeInstance(WorkspaceRestriction::class, $workspaceId));

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Domain\Repository;

use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Domain\Repository\PageRepository;
use TYPO3\CMS\Extbase\Persistence\Repository;

final class ItemRepository extends Repository
{
    public function __construct(
        private readonly ConnectionPool $connectionPool,
        private readonly PageRepository $pageRepository,
    ) {
        // parent constructor is called automatically via DI
    }

    /**
     * Custom query that needs manual workspace handling.
     */
    public function findItemsWithCustomQuery(int $categoryId): array
    {
        $queryBuilder = $this->connectionPool
            ->getQueryBuilderForTable('tx_myextension_domain_model_item');

        // Use FrontendRestrictionContainer for proper workspace filtering
        $queryBuilder->setRestrictions(
            \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
                \TYPO3\CMS\Core\Database\Query\Restriction\FrontendRestrictionContainer::class
            )
        );

        $result = $queryBuilder
            ->select('i.*')
            ->from('tx_myextension_domain_model_item', 'i')
            ->join(
                'i',
                'sys_category_record_mm',
                'mm',
                $queryBuilder->expr()->eq('mm.uid_foreign', $queryBuilder->quoteIdentifier('i.uid'))
            )
            ->where(
                $queryBuilder->expr()->eq(
                    'mm.uid_local',
                    $queryBuilder->createNamedParameter($categoryId, \TYPO3\CMS\Core\Database\Connection::PARAM_INT)
                )
            )
            ->executeQuery();

        $items = [];
        while ($row = $result->fetchAssociative()) {
            $this->pageRepository->versionOL('tx_myextension_domain_model_item', $row);
            if (is_array($row)) {
                $items[] = $row;
            }
        }

        return $items;
    }
}

<?php
// DEPRECATED: Do NOT use. Not available in v13/v14.
// $res = $GLOBALS['TYPO3_DB']->exec_SELECTquery('*', 'tt_content', 'pid=' . (int)$pageId);

<?php

use TYPO3\CMS\Backend\Utility\BackendUtility;
use TYPO3\CMS\Core\Database\Connection;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
    ->getQueryBuilderForTable('tt_content');

$result = $queryBuilder
    ->select('*')
    ->from('tt_content')
    ->where(
        $queryBuilder->expr()->eq(
            'pid',
            $queryBuilder->createNamedParameter($pageId, Connection::PARAM_INT)
        )
    )
    ->executeQuery();

while ($row = $result->fetchAssociative()) {
    BackendUtility::workspaceOL('tt_content', $row);
    if (is_array($row)) {
        // Process the workspace-overlaid record
    }
}

Live Record (lang=0, ws=0)
  └─► Workspace Overlay (lang=0, ws=1)     ← workspace version of default language
  └─► Language Overlay (lang=1, ws=0)       ← translation of live record
        └─► Workspace Overlay (lang=1, ws=1) ← workspace version of translation

# User TSconfig
# Allow only French (uid=1) and German (uid=2) in workspace 3
options.workspaces.allowed_languages.3 = 1,2

-- Check if workspace records exist
SELECT uid, title, adminusers, members, publish_access
FROM sys_workspace
WHERE deleted = 0;

-- Check versioned records for a specific page
SELECT uid, pid, t3ver_oid, t3ver_wsid, t3ver_state, t3ver_stage, header
FROM tt_content
WHERE t3ver_wsid > 0
  AND deleted = 0
ORDER BY t3ver_wsid, t3ver_oid;

-- Find orphaned workspace records (pointing to deleted live records)
SELECT ws.uid AS ws_uid, ws.t3ver_oid, ws.t3ver_wsid, ws.header
FROM tt_content ws
LEFT JOIN tt_content live ON ws.t3ver_oid = live.uid
WHERE ws.t3ver_wsid > 0
  AND ws.deleted = 0
  AND (live.uid IS NULL OR live.deleted = 1);

-- Check workspace-enabled tables
SELECT TABLE_NAME
FROM information_schema.COLUMNS
WHERE COLUMN_NAME = 't3ver_oid'
  AND TABLE_SCHEMA = DATABASE()
ORDER BY TABLE_NAME;

-- Inspect backend user's workspace permissions
SELECT
    bu.uid,
    bu.username,
    bu.workspace_perms,
    GROUP_CONCAT(bg.title SEPARATOR ', ') AS groups,
    GROUP_CONCAT(bg.workspace_perms SEPARATOR ', ') AS group_ws_perms
FROM be_users bu
LEFT JOIN be_users_be_groups_mm mm ON bu.uid = mm.uid_local
LEFT JOIN be_groups bg ON mm.uid_foreign = bg.uid
WHERE bu.deleted = 0
  AND bu.disable = 0
GROUP BY bu.uid, bu.username, bu.workspace_perms;

-- Check sys_log for workspace operations
SELECT
    FROM_UNIXTIME(tstamp) AS time,
    userid,
    action,
    details,
    tablename,
    recuid,
    workspace
FROM sys_log
WHERE workspace > 0
ORDER BY tstamp DESC
LIMIT 50;

<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Context\Context;
use TYPO3\CMS\Core\Utility\GeneralUtility;

// Get current workspace ID
$workspaceId = GeneralUtility::makeInstance(Context::class)
    ->getPropertyFromAspect('workspace', 'id', 0);

// Check if user can edit in current workspace
$cannotEdit = $GLOBALS['BE_USER']->workspaceCannotEditRecord('tt_content', $row);
if ($cannotEdit) {
    // $cannotEdit contains error message explaining why
    throw new \RuntimeException('Cannot edit: ' . $cannotEdit);
}

// Check if new records can be created on a page
$canCreate = $GLOBALS['BE_USER']->workspaceCreateNewRecord($pageId, 'tt_content');

// Check user's workspace access level
$workspaceAccess = $GLOBALS['BE_USER']->checkWorkspace($workspaceId);
// Returns: array with 'uid', '_ACCESS' key ('admin', 'owner', 'member', or false)

# DDEV
ddev composer require --dev typo3/testing-framework:"^9.0" phpunit/phpunit:"^11.0"

# Non-DDEV
composer require --dev typo3/testing-framework:"^9.0" phpunit/phpunit:"^11.0"

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/typo3/testing-framework/Resources/Core/Build/FunctionalTestsBootstrap.php"
         colors="true"
         cacheResult="false">
    <testsuites>
        <testsuite name="Functional">
            <directory>Tests/Functional</directory>
        </testsuite>
    </testsuites>
    <php>
        <!-- Functional tests need a database. DDEV provides one automatically. -->
        <!-- For non-DDEV: set typo3DatabaseHost, typo3DatabaseUsername, etc. -->
        <!-- Example for DDEV (auto-detected, usually no env vars needed): -->
        <!-- <env name="typo3DatabaseHost" value="db"/> -->
        <!-- <env name="typo3DatabaseUsername" value="db"/> -->
        <!-- <env name="typo3DatabasePassword" value="db"/> -->
        <!-- <env name="typo3DatabaseName" value="db"/> -->
    </php>
</phpunit>

mkdir -p Tests/Functional/Fixtures

your-extension/
├── Build/
│   └── phpunit-functional.xml       ← PHPUnit config
├── Classes/
│   └── ...
├── Configuration/
│   └── TCA/
├── Tests/
│   └── Functional/
│       ├── Fixtures/
│       │   └── WorkspaceTestData.csv ← Test data
│       └── WorkspaceAwareTest.php    ← Test class
├── composer.json
└── ext_emconf.php

{
    "autoload-dev": {
        "psr-4": {
            "MyVendor\\MyExtension\\Tests\\": "Tests/"
        }
    }
}

# DDEV
ddev composer dump-autoload

# Non-DDEV
composer dump-autoload

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Tests\Functional;

use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;
use TYPO3\CMS\Core\Context\Context;
use TYPO3\CMS\Core\Context\WorkspaceAspect;
use TYPO3\CMS\Core\Core\Bootstrap;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\TestingFramework\Core\Functional\FunctionalTestCase;

final class WorkspaceAwareTest extends FunctionalTestCase
{
    /**
     * Load the workspaces extension for all tests in this class.
     */
    protected array $coreExtensionsToLoad = [
        'workspaces',
    ];

    /**
     * Load your own extension.
     */
    protected array $testExtensionsToLoad = [
        'typo3conf/ext/my_extension',
    ];

    protected function setUp(): void
    {
        parent::setUp();

        // Import base data: pages, content, workspace record, backend user
        $this->importCSVDataSet(__DIR__ . '/Fixtures/WorkspaceTestData.csv');

        // Initialize backend user (uid=1 from fixture, must be admin for DataHandler)
        $this->setUpBackendUser(1);
        Bootstrap::initializeLanguageObject();
    }

    /**
     * Helper: set the current workspace context.
     */
    private function setWorkspaceId(int $workspaceId): void
    {
        $context = GeneralUtility::makeInstance(Context::class);
        $context->setAspect('workspace', new WorkspaceAspect($workspaceId));
        $GLOBALS['BE_USER']->setWorkspace($workspaceId);
    }

    /**
     * Test: Record created in workspace is NOT visible in live.
     */
    public function testRecordCreatedInWorkspaceNotVisibleInLive(): void
    {
        // Switch to workspace 1
        $this->setWorkspaceId(1);

        // Create a record in the workspace via DataHandler
        $data = [
            'tt_content' => [
                'NEW_1' => [
                    'pid' => 1,
                    'CType' => 'text',
                    'header' => 'Workspace Only Content',
                    'bodytext' => '<p>This should not be live</p>',
                ],
            ],
        ];

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

        self::assertEmpty($dataHandler->errorLog, 'DataHandler errors: ' . implode(', ', $dataHandler->errorLog));

        // Switch back to LIVE
        $this->setWorkspaceId(0);

        // Query live records -- the workspace record should NOT appear
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
            ->getQueryBuilderForTable('tt_content');

        $liveRecords = $queryBuilder
            ->select('uid', 'header')
            ->from('tt_content')
            ->where(
                $queryBuilder->expr()->eq('pid', 1),
                $queryBuilder->expr()->eq('t3ver_wsid', 0),
                $queryBuilder->expr()->neq('t3ver_state', 1) // exclude new placeholders
            )
            ->executeQuery()
            ->fetchAllAssociative();

        $headers = array_column($liveRecords, 'header');
        self::assertNotContains('Workspace Only Content', $headers);
    }

    /**
     * Test: Workspace overlay returns modified content.
     */
    public function testWorkspaceOverlayReturnsModifiedContent(): void
    {
        // Record uid=10 exists in fixture with header "Original Header"
        // Workspace version exists with header "Modified In Workspace"
        $this->setWorkspaceId(1);

        $row = \TYPO3\CMS\Backend\Utility\BackendUtility::getRecordWSOL('tt_content', 10);

        self::assertIsArray($row);
        self::assertSame('Modified In Workspace', $row['header']);
    }

    /**
     * Test: Workspace publish command makes staged content live for a record pair.
     *
     * DEPRECATED: The 'swap' action is no longer allowed in TYPO3 v14.
     * Use 'action' => 'publish' instead. The 'swapWith' key is replaced by 'uid' (workspace version uid).
     */
    public function testPublishWorkspaceRecordPairMakesContentLive(): void
    {
        $this->setWorkspaceId(1);

        // Publish workspace record for tt_content uid=10
        $cmd = [
            'tt_content' => [
                10 => [
                    'version' => [
                        'action' => 'publish',
                        'uid' => $this->getWorkspaceVersionUid('tt_content', 10, 1),
                    ],
                ],
            ],
        ];

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

        self::assertEmpty($dataHandler->errorLog);

        // Switch to LIVE and verify
        $this->setWorkspaceId(0);
        $row = \TYPO3\CMS\Backend\Utility\BackendUtility::getRecord('tt_content', 10);

        self::assertSame('Modified In Workspace', $row['header']);
    }

    /**
     * Helper: Get the uid of the workspace version of a record.
     */
    private function getWorkspaceVersionUid(string $table, int $liveUid, int $workspaceId): int
    {
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
            ->getQueryBuilderForTable($table);
        $queryBuilder->getRestrictions()->removeAll();

        $row = $queryBuilder
            ->select('uid')
            ->from($table)
            ->where(
                $queryBuilder->expr()->eq('t3ver_oid', $liveUid),
                $queryBuilder->expr()->eq('t3ver_wsid', $workspaceId),
                $queryBuilder->expr()->eq('deleted', 0)
            )
            ->executeQuery()
            ->fetchAssociative();

        return (int)($row['uid'] ?? 0);
    }
}

"be_users"
,"uid","pid","username","password","admin","workspace_perms"
,1,0,"admin","$2y$12$placeholder",1,1

"sys_workspace"
,"uid","pid","title","adminusers","members","deleted"
,1,0,"Test Workspace","1","1",0

"pages"
,"uid","pid","title","slug","deleted","t3ver_oid","t3ver_wsid","t3ver_state"
,1,0,"Test Page","/test-page",0,0,0,0

"tt_content"
,"uid","pid","header","CType","bodytext","deleted","t3ver_oid","t3ver_wsid","t3ver_state"
,10,1,"Original Header","text","<p>Original</p>",0,0,0,0
,11,-1,"Modified In Workspace","text","<p>Modified</p>",0,10,1,0

# Run all workspace functional tests
ddev exec bin/phpunit -c Build/phpunit-functional.xml \
  Tests/Functional/WorkspaceAwareTest.php

# Run a single test method
ddev exec bin/phpunit -c Build/phpunit-functional.xml \
  --filter testWorkspaceOverlayReturnsModifiedContent \
  Tests/Functional/WorkspaceAwareTest.php

# Verbose output (shows each test name)
ddev exec bin/phpunit -c Build/phpunit-functional.xml \
  -v Tests/Functional/WorkspaceAwareTest.php

# Set database credentials for the test runner
export typo3DatabaseHost="127.0.0.1"
export typo3DatabasePort="3306"
export typo3DatabaseUsername="root"
export typo3DatabasePassword="root"
export typo3DatabaseName="typo3_test"

bin/phpunit -c Build/phpunit-functional.xml \
  Tests/Functional/WorkspaceAwareTest.php

# Page TSconfig for news preview in workspace
options.workspaces.previewPageId.tx_news_domain_model_news = 42

# User TSconfig -- set preview link expiry
options.workspaces.previewLinkTTLHours = 72

# Cron job (runs every 15 minutes)
*/15 * * * * /path/to/bin/typo3 scheduler:run

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\EventListener;

use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Workspaces\Event\AfterRecordPublishedEvent;

#[AsEventListener]
final class AfterPublishListener
{
    public function __invoke(AfterRecordPublishedEvent $event): void
    {
        $table = $event->getTable();
        $liveId = $event->getRecordId();

        // Example: Clear external CDN cache after publishing
        if ($table === 'pages') {
            // Trigger CDN purge for the published page
        }

        // Example: Notify external system
        if ($table === 'tx_news_domain_model_news') {
            // Send webhook to newsletter system
        }
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\EventListener;

use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Workspaces\Event\SortVersionedDataEvent;

#[AsEventListener]
final class CustomWorkspaceSortListener
{
    public function __invoke(SortVersionedDataEvent $event): void
    {
        // Custom sorting logic for workspace module
        $data = $event->getData();
        // ... modify $data ...
        $event->setData($data);
    }
}