Breaking: #92791 - "New Placeholder" records removed in Workspaces

See forge#92791

Description

When creating a new record in a workspace, TYPO3 created two database entries: A "new placeholder" which served as a pseudo-live pendant with no content but only the target PID value to be added, and a "versioned record" which – until TYPO3 v10 – had the PID value "-1". On publishing the contents of both records were exchanged (except the PID) and the versioned record was removed.

Since TYPO3 v10 the "new placeholder" had little information to be kept alive. Only on publishing, the behaviour was simple, as the publishing process as described above worked the same way as for other "versioned records" like modifying a live record, or moving records.

Apart from having two database records created where only one contained user input, there were some conceptual drawbacks with having a placeholder record: Sorting, and type fields had to be configured via a special $TCA[$table][ctrl][shadowColumnsForNewPlaceholders] TCA option, which wasn't kept in sync when modifying the versioned record.

Both record types were identified in the database as the following:

New Placeholder Record

  • t3ver_state => 1 - identifying as "new placeholder"

  • t3ver_wsid => the ID of the workspace it was created

  • t3ver_oid => 0 - as it should behave as the "online version"

  • pid => the PID where the record should be published in (same with "sorting", when set)

New Versioned Record

  • t3ver_state => -1 - identifying as "new record created in workspace"

  • t3ver_wsid => the ID of the workspace it was created

  • t3ver_oid => ID of the New Placeholder Record

  • pid => the PID where the record should be published in (same with "sorting", when set)

The placeholder record was queried when reading the database while in a workspace with other live records. It was then overlaid by the versioned record.

TYPO3 v11 does not create placeholder records anymore, but instead creates one record containing all information. When fetching records from the database, the new versioned records are added directly, so no overlays need to happen anymore, which speeds up performance when querying the database via the TYPO3 Database via API classes such as PageRepository or BackendUtility.

Impact

No records with t3ver_state=-1 are found in the TYPO3 installation anymore.

When using the Doctrine DBAL API with Workspace Restrictions within a workspace, the new versions are included in the SQL query result.

DataHandler will not create placeholders anymore, making the TCA option $TCA[$table][ctrl][shadowColumnsForNewPlaceholders] obsolete.

Using methods like getWorkspaceVersionOfRecord on a new versioned record will return the same record again, as there is no "workspace version" of this record anymore.

The CLI command cleanup:versions is adapted as the option --action=unused_placeholders is removed.

In addition, records overlaid via the TYPO3 API classes that have been newly created in a workspace do not carry the ORIG_uid information anymore which keeps the UID of the versioned record.

Affected Installations

TYPO3 installations using Workspaces with newly created records that haven't been published yet, or with third-party extensions directly querying, resolving or writing based on t3ver_state database fields, which is very uncommon.

Migration

An upgrade wizard is used to migrate possibly left-over "placeholder" records within the the database. This is only needed when workspaces are in use and there are records in the database that are newly created and have not been published.

A TCA migration will automatically remove and log any usages of the TCA option $TCA[$table][ctrl][shadowColumnsForNewPlaceholders].

It is highly recommend to use the TYPO3 API methods within Extbase, PageRepository and BackendUtility to ensure records are resolved properly.

At any times, it is recommended to use the WorkspaceRestriction of TYPO3's implementation of Doctrine DBAL in conjunction with Workspace overlays.