typo3-workspaces

What this skill does

# TYPO3 Workspaces

> Source: https://github.com/dirnbauer/webconsulting-skills

> **Compatibility:** TYPO3 v14.x
> All code examples in this skill are designed to work on TYPO3 v14.

> **TYPO3 API First:** Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in TYPO3 v14 by checking the official TYPO3 documentation.

## Sources

This skill is based on 17 authoritative sources:

1. [TYPO3 Workspaces Extension Docs](https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/Index.html)
2. [Versioning (Workspaces Extension)](https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/Administration/Versioning/Index.html)
3. [Creating a Custom Workspace](https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/Administration/CustomWorkspace/Index.html)
4. [Configuration Options (Workspaces)](https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/Administration/Configuration/Index.html)
5. [PSR-14 Events (Workspaces)](https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/Events/Index.html)
6. [Versioning & Workspaces (TYPO3 Explained / Core API)](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Workspaces/Index.html)
7. [TCA versioningWS Reference](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/Ctrl/Index.html#confval-ctrl-versioningws)
8. [Restriction Builder (TYPO3 Explained / Doctrine DBAL)](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Database/DoctrineDbal/RestrictionBuilder/Index.html)
9. [b13 Blog: The Elegant Efficiency of TYPO3 Overlays (Benni Mack)](https://b13.com/blog/mastering-localization-and-content-staging)
10. [Scheduler Tasks (Workspaces)](https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/Administration/Scheduler/Index.html)
11. [Users Guide (Workspaces)](https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/UsersGuide/Index.html)
12. [TYPO3-CORE-SA-2025-022: Information Disclosure in Workspaces Module](https://typo3.org/security/advisory/typo3-core-sa-2025-022)
13. [Localized Content Guide](https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/LocalizedContent/Index.html)
14. [File Collections (TYPO3 Explained)](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Fal/Collections/Index.html)
15. [FAL Database Architecture](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Fal/Architecture/Database.html)
16. [Forge Bug #60343: sys_file_metadata does not recognize workspace](https://forge.typo3.org/issues/60343)
17. [Forge Feature #97923: Combined folder_identifier field for sys_file_collection](https://forge.typo3.org/issues/97923)

## 1. Core Concepts

### What Are Workspaces?

Workspaces allow editors to prepare content changes **without affecting the live website**. Changes go through a configurable review process before publication.

There are two types:

- **LIVE workspace** (ID=0): The default state. Every change is immediately visible. Access must be **explicitly granted** to backend users/groups.
- **Custom workspaces** (ID>0): Safe editing environments. Changes are versioned, previewable, and go through stages before going live.

### How Versioning Works (Database Level)

Offline (workspace) versions live in the **same database table** as live records. They are identified by:

| Field | Purpose |
|-------|---------|
| `t3ver_oid` | Points to the live record's `uid` (0 for live records and workspace-new records) |
| `t3ver_wsid` | Workspace ID this version belongs to (0 for live) |
| `t3ver_state` | Special state flags (see below) |
| `t3ver_stage` | Workflow stage (0=editing, -10=ready to publish) |
| `pid` | Real page ID (same as the live record's pid) |

> **Note:** Before TYPO3 v11, offline versions had `pid = -1`. Since v11 (Breaking #92497), workspace records store their **real pid**. If you encounter `pid = -1` in legacy code or documentation, it is outdated.

**t3ver_state values (TYPO3 v14):**

| Value | Meaning |
|-------|---------|
| `0` | Default: workspace modification of existing live record |
| `1` | New record created exclusively in workspace (no live counterpart) |
| `2` | Delete placeholder (record marked for deletion upon publish) |
| `4` | Move pointer (record to be moved upon publish, stores new pid/sorting) |

> **Removed in v11:** `t3ver_state = -1` (old "new version" pendant), `t3ver_state = 3` (old "move placeholder"), and the `t3ver_move_id` field. If you see these values in legacy code, they are not used on TYPO3 v14.

### The Overlay Mechanism

TYPO3 **always fetches live records first**, then overlays workspace versions on top. For translations with workspaces, the chain is:

1. Fetch default language, live record (language=0, workspace=0)
2. Overlay workspace version (search for `t3ver_oid=<uid>` AND `t3ver_wsid=<current_ws>`)
3. Overlay language translation (search for `l10n_parent=<uid>` in target language)
4. Overlay workspace version of translation

The `uid` of the live record is **always preserved** during overlay -- this keeps all references and links intact.

### Publishing Workflow

- **Publish**: Draft content replaces live content through the workspace publish process.
- TYPO3 v14 still accepts DataHandler `version` commands with **`action => 'publish'`** (preferred) or **`action => 'swap'`** (alias handled the same as publish in `DataHandlerHook`). The parameter key for the workspace version UID remains **`swapWith`**, not `uid`.
- Do not rely on historic **bidirectional workspace “swap modes”** on `sys_workspace` (removed in v11, #92206) — that is separate from the `swap` **keyword** in cmdmaps.

## 2. CRITICAL: File/FAL Limitation

> **Files (FAL) are NOT versioned.** This is the single most important limitation of TYPO3 Workspaces.
> See also Section 2a below for the additional **file collection** limitation (folder-based collections).

### What This Means

- Files in `fileadmin/` live exclusively in the **LIVE workspace**
- If you **overwrite** a file, the change affects **ALL workspaces immediately**
- `sys_file_reference` records are workspace-versioned; physical files and `sys_file` records are not versioned like content overlays
- Replacing files inside existing references can still have edge cases in workspace previews; test on your exact TYPO3 minor and prefer new filenames over in-place replacement when possible.

### The Predictable Filename Security Problem

**Scenario:** An editor creates a workspace version of a page replacing `geschaeftsbericht2024.pdf` with `geschaeftsbericht2025.pdf`. The workspace is NOT published yet. However:

1. The new PDF is uploaded to `fileadmin/` immediately (files are live!)
2. An external person guesses the URL by incrementing the year
3. `geschaeftsbericht2025.pdf` is accessible before the content element referencing it is published

This is a **real security/confidentiality risk**.

### Workarounds

**1. Use non-guessable filenames:**

```
# Instead of:
fileadmin/reports/geschaeftsbericht2025.pdf

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

**2. Store confidential files outside the web root:**

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

**3. Use EXT:secure_downloads (leuchtfeuer/secure-downloads):**

Files are delivered through a PHP script that checks access permissions. No direct file URL access.

**4. Server-level protection for sensitive directories:**

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

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

**5. Use separate file references per workspace version:**

Upload the new file with a different name. Do NOT overwrite the existing file. The wor