From 09217b2e4a50980196b8da3612e033ae0134cd9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Chris=20M=C3=BCller?= <typo3@krue.ml>
Date: Tue, 15 Aug 2023 19:25:52 +0200
Subject: [PATCH] [DOCS] Fix code examples for tagging event listeners with PHP
 attribute
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 <stefan@buerk.tech>
Reviewed-by: Stefan B�rk <stefan@buerk.tech>
Tested-by: core-ci <typo3@b13.com>
Tested-by: Benjamin Franzke <ben@bnf.dev>
Reviewed-by: Benjamin Franzke <ben@bnf.dev>
---
 ...AttributeToAutoconfigureEventListeners.rst | 59 ++++++++++++-------
 1 file changed, 39 insertions(+), 20 deletions(-)

diff --git a/Documentation/Changelog/13.0/Feature-101544-IntroducePHPAttributeToAutoconfigureEventListeners.rst b/Documentation/Changelog/13.0/Feature-101544-IntroducePHPAttributeToAutoconfigureEventListeners.rst
index 2668f7b60a..b91d93721a 100644
--- a/Documentation/Changelog/13.0/Feature-101544-IntroducePHPAttributeToAutoconfigureEventListeners.rst
+++ b/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,10 +123,11 @@ 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;
@@ -123,8 +135,14 @@ Method level example
 
     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