[FEATURE] Add PSR-14 for record retrieval in DatabaseRecordLinkBuilder (#6277)

* [FEATURE] Add PSR-14 for record retrieval in DatabaseRecordLinkBuilder

Resolves: TYPO3-Documentation/Changelog-To-Doc#1405
Releases: main

* [TASK] Incorporate review

Releases: main

Author: sarahmccarthy123

Documentation/ApiOverview/Events/Events/Frontend/BeforeDatabaseRecordLinkResolvedEvent.rst

@@ -0,0 +1,50 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; BeforeDatabaseRecordLinkResolvedEvent
+..  _BeforeDatabaseRecordLinkResolvedEvent:
+
+=====================================
+BeforeDatabaseRecordLinkResolvedEvent
+=====================================
+
+..  versionadded:: 14.0
+    The event :php-short:`TYPO3\CMS\Frontend\Event\BeforeDatabaseRecordLinkResolvedEvent`
+    has been introduced to retrieve records via custom code in
+    :php:`TYPO3\CMS\Frontend\Typolink\DatabaseRecordLinkBuilder`.
+
+The PSR-14 event :php:`TYPO3\CMS\Frontend\Event\BeforeDatabaseRecordLinkResolvedEvent`
+is dispatched immediately before database record lookup is done
+for a link by the DatabaseRecordLinkBuilder and therefore allows
+custom functionality to be attached to record retrieval. The event is stoppable,
+which means that as soon as a listener returns a record, no further listener
+gets called and the core does no further lookup.
+
+The event is dispatched with :php:`$record` set to :php:`null`. If an event
+listener retrieves a record from the database, it should set the :php:`$record`
+property to the record as an array. This will stop the event propagation and
+cause the default record retrieval logic in
+:php:`TYPO3\CMS\Frontend\Typolink\DatabaseRecordLinkBuilder` to be skipped.
+
+..  important::
+
+    The event is stoppable: Setting the :php:`$record` property to a non-null
+    value stops event propagation and skips the default record retrieval logic.
+
+Note that the custom code needs to take care - if relevant - of all aspects
+normally handled by :php:`TYPO3\CMS\Frontend\Typolink\DatabaseRecordLinkBuilder`,
+such as record visibility, language overlay or version overlay.
+
+..  _BeforeDatabaseRecordLinkResolvedEvent-example:
+
+Example
+=======
+
+..  literalinclude:: _BeforeDatabaseRecordLinkResolvedEvent/_MyEventListener.php
+    :language: php
+    :caption: EXT:my_extension/Classes/Frontend/EventListener/MyEventListener.php
+
+..  _BeforeDatabaseRecordLinkResolvedEvent-api:
+
+API
+===
+
+..  include:: /CodeSnippets/Events/Frontend/BeforeDatabaseRecordLinkResolvedEvent.rst.txt

Documentation/ApiOverview/Events/Events/Frontend/_BeforeDatabaseRecordLinkResolvedEvent/_MyEventListener.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Frontend\EventListener;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Frontend\Event\BeforeDatabaseRecordLinkResolvedEvent;
+
+final readonly class MyEventListener
+{
+    #[AsEventListener(
+        identifier: 'my-extension/before-database-record-link-resolved',
+    )]
+    public function __invoke(BeforeDatabaseRecordLinkResolvedEvent $event): void
+    {
+        // Retrieve the record from the database as an array (just an example -
+        // replace the code in the first line below with your code)
+        $result = getADatabaseRecord();
+        if ($result !== false) {
+            // Setting the record stops event propagation and
+            // skips the default record retrieval logic
+            $event->record = $result;
+        }
+    }
+}

Documentation/CodeSnippets/Events/Frontend/BeforeDatabaseRecordLinkResolvedEvent.rst.txt

@@ -0,0 +1,46 @@
+..  Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+..  php:namespace::  TYPO3\CMS\Frontend\Event
+
+..  php:class:: BeforeDatabaseRecordLinkResolvedEvent
+
+    A PSR-14 event fired in the frontend process before database record
+    lookup is done for a link.
+
+    This event makes it possible to implement custom logic, for example,
+    for specific frontend access when retrieving a linked record in a typolink.
+
+    ..  php:attr:: linkDetails
+        :readonly:
+        :public:
+
+        Information about the link being processed
+
+    ..  php:attr:: databaseTable
+        :readonly:
+        :public:
+
+        The name of the database the record belongs to
+
+    ..  php:attr:: typoscriptConfiguration
+        :readonly:
+        :public:
+
+        The full TypoScript link handler configuration
+
+    ..  php:attr:: tsConfig
+        :readonly:
+        :public:
+
+        The full TSconfig link handler configuration
+
+    ..  php:attr:: request
+        :readonly:
+        :public:
+
+        The current request object
+
+    ..  php:attr:: record
+        :readonly:
+        :public:
+
+        The database record as an array (initially :php:`null`)