#111018Feature-110625 changelog names internal methods as extension API
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
-
Lina Wolf changed category <span data-processor="relativetime" data-value="2026-10-11T13:05:45+00:00" > 10/11/26, 13:05 </span>
-
Oliver Bartsch commented <span data-processor="relativetime" data-value="2026-10-19T18:17:23+00:00" > 10/19/26, 18:17 </span>
-
Gerrit Code Review pushed patch set 1 for main to change 96879 status
NewUnder Review <span data-processor="relativetime" data-value="2026-10-19T18:17:37+00:00" > 10/19/26, 18:17 </span> -
Oliver Bartsch commented and changed status
Under ReviewResolved done0 %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.
Hey,
thanks for spotting this. You’re right: the changelog of #110625 promises an extension API that the code doesn’t provide.
RecordHistoryis marked as an implementation detail of the history controller, andCorrelationIdhas beeninternal 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()andCorrelationId::scopePrefix(), and the extension sentence in the Impact section. I’ll also drop thePHP-APIindex 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