Issue Bug Resolved

#111018Feature-110625 changelog names internal methods as extension API

Lina Wolf 10/11/26, 13:05 updated 10/19/26, 19:30

Description

The changelog entry https://docs.typo3.org/permalink/changelog:feature-110625-1788531965
(15.0) says in its Description section (line 31): “The lookup behind it
is available to extensions as well”. It names these methods as that API:

  • \TYPO3\CMS\Backend\History\RecordHistory->getScopeOfEvent()
  • \TYPO3\CMS\Backend\History\RecordHistory->findEventsForScope()
  • \TYPO3\CMS\Core\DataHandling\Model\CorrelationId::scopePrefix()

The Impact section (line 61) repeats this: “Extensions can resolve all
changes belonging to one operation, which is the basis for reverting a
whole operation instead of one record at a time.”

On main, both classes are marked internal:

  • RecordHistory, class docblock, line 37: “@internal This class is an
    implementation detail of the backend record history controller and is
    not considered part of the public TYPO3 API.”
  • CorrelationId, class docblock, line 26: “@internal”

RecordHistoryStore, which writes the history entries, is internal too
(line 28: “@internal should only be used by the TYPO3 Core”).

Because of this, the documentation team cannot document the lookup as
extension API (Changelog-To-Doc issue
https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1856).
Until this is decided, TYPO3 Explained documents only the concept: the
DataHandler writes sys_history, all entries of one run share a
correlation ID scope, and the module groups and undoes entries by
operation.

Which way does the Core team want to go?

1. Make the lookup public API: remove @internal from these methods, or
add a dedicated public service around them.
2. Correct the changelog: remove the paragraph about the lookup and the
sentence in the Impact section.

Checked on main at e4f361cbd44.

Reviews 1

History 34

  1. Oliver Bartsch commented <span data-processor="relativetime" data-value="2026-10-19T18:17:23+00:00" > 10/19/26, 18:17 </span>

    Hey,

    thanks for spotting this. You’re right: the changelog of #110625 promises an extension API that the code doesn’t provide. RecordHistory is marked as an implementation detail of the history controller, and CorrelationId has been internal since it was introduced. Both are correct as they are. In its current shape, RecordHistory@ isn’t something we want to support as public API: it is stateful and built for one element, it isn’t a service, and its permission checks depend on the global backend user.

    So we’ll go with option 2. I’ll push a patch that removes the “available to extensions” paragraph with its code example, the paragraphs on findEventsForScope(), getScopeOfEvent() and CorrelationId::scopePrefix(), and the extension sentence in the Impact section. I’ll also drop the PHP-API index tag. The classes stay @internal. Documenting only the concept in TYPO3 Explained, as you already do, is exactly right.

    If there is real demand for resolving whole operations from extensions, that should be its own feature with a dedicated public service, not the internal controller helper.

    Cheers, Oli

  2. Oliver Bartsch commented and changed status Under Review Resolved done 0 % 100 % <span data-processor="relativetime" data-value="2026-10-19T19:30:13+00:00" > 10/19/26, 19:30 </span>

    Applied in changeset commit:4f48119a13e84845d022ecf759bc480a8e6db551.