[FEATURE] Add original file name to SanitizeFileNameEvent

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

Author: linawolf

Documentation/ApiOverview/Events/Events/Core/Resource/SanitizeFileNameEvent.rst

@@ -7,16 +7,28 @@ SanitizeFileNameEvent
 =====================
 
 The PSR-14 event :php:`\TYPO3\CMS\Core\Resource\Event\SanitizeFileNameEvent` is
-fired once an index was just added to the database (= indexed), so it is possible
-to modify the file name, and name the files according to naming conventions of a
-specific project.
+fired when a file name is sanitized. Event listeners can modify the sanitized
+file name in order to apply custom naming conventions (for example, replacing
+whitespace with hyphens for SEO-friendly file names).
 
-Example
-=======
+..  _SanitizeFileNameEvent-example:
 
-..  include:: /_includes/EventsContributeNote.rst.txt
+Example: Sanitize a file name with hyphens instead of underscores
+=================================================================
 
-API
-===
+The following listener uses the original (unsanitized) file name to replace
+whitespace with hyphens and assigns the result as sanitized file name.
+
+..  literalinclude:: _SanitizeFileNameEvent/_SeoFriendlyFileNameListener.php
+    :caption: EXT:my_extension/Classes/EventListener/SeoFriendlyFileNameListener.php
+
+..  _SanitizeFileNameEvent-api:
+
+SanitizeFileNameEvent API
+=========================
+
+..  versionchanged:: 14.0
+    The original (unsanitized) file name can now be retrieved using
+    :php:`SanitizeFileNameEvent::getOriginalFileName()`.
 
 ..  include:: /CodeSnippets/Events/Core/Resource/SanitizeFileNameEvent.rst.txt

Documentation/ApiOverview/Events/Events/Core/Resource/_SanitizeFileNameEvent/_SeoFriendlyFileNameListener.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\EventListener;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Core\Resource\Event\SanitizeFileNameEvent;
+
+#[AsEventListener(
+    identifier: 'my-extension/seo-friendly-filename',
+)]
+final readonly class SeoFriendlyFileNameListener
+{
+    public function __invoke(SanitizeFileNameEvent $event): void
+    {
+        $originalFileName = $event->getOriginalFileName();
+
+        if (!str_contains($originalFileName, ' ')) {
+            return;
+        }
+        // Apply custom logic based on the original file name
+        $customFileName = str_replace(' ', '-', $originalFileName);
+
+        $event->setFileName($customFileName);
+    }
+}