[DOCS] Fix code examples for tagging event listeners with PHP attribute

The "event" value in the PHP attribute has to be the FQCN of the event
class. Additionally, a caption is added to the PHP examples and some
wording has been adjusted.

Resolves: #101693
Related: #101544
Releases: main
Change-Id: I9f1a302a73484509a61a3ff93711f2e20b14aaa5
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/80558
Tested-by: Stefan B�rk <[email protected]>
Reviewed-by: Stefan B�rk <[email protected]>
Tested-by: core-ci <[email protected]>
Tested-by: Benjamin Franzke <[email protected]>
Reviewed-by: Benjamin Franzke <[email protected]>

typo3/sysext/core/Documentation/Changelog/13.0/Feature-101544-IntroducePHPAttributeToAutoconfigureEventListeners.rst

@@ -12,20 +12,22 @@ Description
 ===========
 
 A new custom PHP attribute :php:`\TYPO3\CMS\Core\Attribute\AsEventListener`
-has been added in order to autoconfigure a class as an event listener.
+has been added in order to autoconfigure a class as a PSR-14 event listener.
 
 The attribute supports the following properties, which are all optional,
 as if you would register the listener by manually tagging it in the
 :file:`Services.yaml` or :file:`Services.php` file:
 
-* `identifier` - Event listener identifier (unique) - uses the service name if not provided
-* `event` - FQN of the PSR-14 Event to listen to
-* `method` - Method to be called - if omitted, `__invoke` is called by the listener provider.
-* `before` - List of listener identifiers
-* `after` - List of listener identifiers
+*   `identifier` - Event listener identifier (unique) - uses the service name,
+    if not provided
+*   `event` - Fully-qualified class name of the PSR-14 event to listen to
+*   `method` - Method to be called - if omitted, :php:`__invoke()` is called by
+    the listener provider.
+*   `before` - List of listener identifiers
+*   `after` - List of listener identifiers
 
 The attribute can be used on class and method level. Additionally, the new
-attributes is repeatable, which allows to register the same class to listen
+attribute is repeatable, which allows to register the same class to listen
 for different events.
 
 Migration example
@@ -36,16 +38,17 @@ Before:
 ..  code-block:: yaml
     :caption: EXT:my_extension/Configuration/Services.yaml
 
-    MyCompany\MyExtension\EventListener\NullMailer:
+    MyVendor\MyExtension\EventListener\NullMailer:
       tags:
         - name: event.listener
           identifier: 'my-extension/null-mailer'
 
 ..  code-block:: php
+    :caption: EXT:my_extension/Classes/EventListener/NullMailer.php
 
     <?php
 
-    namespace MyCompany\MyExtension\EventListener;
+    namespace MyVendor\MyExtension\EventListener;
 
     use TYPO3\CMS\Core\Mail\Event\AfterMailerInitializationEvent;
 
@@ -59,14 +62,15 @@ Before:
 
 After:
 
-The configuration is removed from the :file:`Service.yaml` and the attribute is
-assigned to the class instead:
+The configuration is removed from the :file:`Services.yaml` file and the
+attribute is assigned to the class instead:
 
 ..  code-block:: php
+    :caption: EXT:my_extension/Classes/EventListener/NullMailer.php
 
     <?php
 
-    namespace MyCompany\MyExtension\EventListener;
+    namespace MyVendor\MyExtension\EventListener;
 
     use TYPO3\CMS\Core\Attribute\AsEventListener;
     use TYPO3\CMS\Core\Mail\Event\AfterMailerInitializationEvent;
@@ -87,17 +91,24 @@ Repeatable example
 ==================
 
 ..  code-block:: php
+    :caption: EXT:my_extension/Classes/EventListener/NullMailer.php
 
     <?php
 
-    namespace MyCompany\MyExtension\EventListener;
+    namespace MyVendor\MyExtension\EventListener;
 
     use TYPO3\CMS\Core\Attribute\AsEventListener;
     use TYPO3\CMS\Core\Mail\Event\AfterMailerInitializationEvent;
     use TYPO3\CMS\Core\Mail\Event\BeforeMailerSentMessageEvent;
 
-    #[AsEventListener(identifier: 'my-extension/null-mailer-initialization', event: 'AfterMailerInitializationEvent')]
-    #[AsEventListener(identifier: 'my-extension/null-mailer-sent-message', event: 'BeforeMailerSentMessageEvent')]
+    #[AsEventListener(
+        identifier: 'my-extension/null-mailer-initialization',
+        event: AfterMailerInitializationEvent::class
+    )]
+    #[AsEventListener(
+        identifier: 'my-extension/null-mailer-sent-message',
+        event: BeforeMailerSentMessageEvent::class
+    )]
     final class NullMailer
     {
         public function __invoke(
@@ -112,19 +123,26 @@ Method level example
 ====================
 
 ..  code-block:: php
+    :caption: EXT:my_extension/Classes/EventListener/NullMailer.php
 
     <?php
 
-    namespace MyCompany\MyExtension\EventListener;
+    namespace MyVendor\MyExtension\EventListener;
 
     use TYPO3\CMS\Core\Attribute\AsEventListener;
     use TYPO3\CMS\Core\Mail\Event\AfterMailerInitializationEvent;
     use TYPO3\CMS\Core\Mail\Event\BeforeMailerSentMessageEvent;
 
     final class NullMailer
     {
-        #[AsEventListener(identifier: 'my-extension/null-mailer-initialization', event: AfterMailerInitializationEvent::class)]
-        #[AsEventListener(identifier: 'my-extension/null-mailer-sent-message', event: 'BeforeMailerSentMessageEvent')]
+        #[AsEventListener(
+            identifier: 'my-extension/null-mailer-initialization',
+            event: AfterMailerInitializationEvent::class
+        )]
+        #[AsEventListener(
+            identifier: 'my-extension/null-mailer-sent-message',
+            event: BeforeMailerSentMessageEvent::class
+        )]
         public function __invoke(
             AfterMailerInitializationEvent | BeforeMailerSentMessageEvent $event
         ): void {
@@ -137,7 +155,8 @@ Impact
 
 Using the PHP attribute :php:`\TYPO3\CMS\Core\Attribute\AsEventListener`, it is
 now possible to tag any PHP class as an event listener. By adding the attribute
-the class is automatically tagged as `event.listener` and is therefore auto
-configured by the :php:`ListenerProviderPass`.
+the class is automatically tagged as `event.listener` and is therefore
+autoconfigured by the
+:php:`\TYPO3\CMS\Core\DependencyInjection\ListenerProviderPass`.
 
 .. index:: Backend, Frontend, PHP-API, ext:core