Merge pull request #434 from WoltLab/event-organization

Document overhaul of the event organization

docs/migration/wsc60/deprecations_removals.md

@@ -11,6 +11,22 @@ With version 6.1, we have deprecated certain components and removed several othe
 - `wcf\system\exception\ValidateActionException`
 - `wcf\system\bbcode\HtmlBBCodeParser` ([WoltLab/WCF#5874](https://github.com/WoltLab/WCF/pull/5874/))
 - `wcf\action\AbstractOauth2Action` ([WoltLab/WCF#5891](https://github.com/WoltLab/WCF/pull/5891/))
+- `wcf\data\user\menu\item\event\UserMenuItemIconResolving` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\cache\event\CacheCleared` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\event\IEvent` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\event\IInterruptableEvent` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\event\TInterruptableEvent` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\language\event\LanguageContentCopying` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\language\event\LanguageImported` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\language\event\PhraseChanged` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\language\event\PreloadPhrasesCollecting` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\moderation\queue\event\UserAssigned` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\package\event\PackageInstallationPluginSynced` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\package\event\PackageListChanged` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\package\event\PackageUpdateListChanged` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\user\authentication\event\UserLoggedIn` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\user\event\UsernameValidating` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
+- `wcf\system\worker\event\RebuildWorkerCollecting` ([WoltLab/WCF#5912](https://github.com/WoltLab/WCF/pull/5912/))
 
 #### Methods
 

docs/migration/wsc60/php.md

@@ -88,3 +88,11 @@ Example:
     ['pageIdentifier']
 ))();
 ```
+
+## PSR-14 Events
+
+The old practice of placing events where they are used is somewhat inconsistent and worst of all highly intransparent for discovery purposes. WoltLab Suite 6.1 therefore introduces a unified directory structure grouped by the app namespace.
+
+All PSR-14 events now use the new `event` namespace (located under `lib/event`). See the [PSR-14 event documentation](../../php/api/events.md) for details.
+
+The changes are backwards compatible, the old namespaces can still be used.

docs/package/acp-menu-items.md

@@ -2,7 +2,7 @@
 
 The API for the ACP menu items allows you to add your own menu items in the admin panel for your package.
 
-Since WoltLab Suite 6.1 you can attach an event listener to the `wcf\system\menu\acp\event\AcpMenuCollecting` event inside a bootstrap script to lazily register your ACP menu items.
+Since WoltLab Suite 6.1 you can attach an event listener to the `wcf\event\acp\menu\item\ItemCollecting` event inside a bootstrap script to lazily register your ACP menu items.
 
 The `register` method of the event expects an object of the type `wcf\system\menu\acp\AcpMenuItem` as a parameter. An `AcpMenuItem` object consists of the following parameters:
 
@@ -21,12 +21,12 @@ Example:
 
 use wcf\system\event\EventHandler;
 use wcf\system\menu\acp\AcpMenuItem;
-use wcf\system\menu\acp\event\AcpMenuCollecting;
+use wcf\event\acp\menu\item\ItemCollecting;
 use wcf\system\request\LinkHandler;
 use wcf\system\style\FontAwesomeIcon;
 
 return static function (): void {
-    EventHandler::getInstance()->register(AcpMenuCollecting::class, static function (AcpMenuCollecting $event) {
+    EventHandler::getInstance()->register(ItemCollecting::class, static function (ItemCollecting $event) {
         $event->register(new AcpMenuItem(
             "com.woltlab.foor.bar",
             'Example Title',

docs/php/api/acp_dashboard_boxes.md

@@ -13,9 +13,6 @@ Example:
 <?php
 namespace wcf\system\acp\dashboard\box;
 
-use wcf\system\event\EventHandler;
-use wcf\system\acp\dashboard\event\AcpDashboardCollecting;
-
 final class FooBox extends AbstractAcpDashboardBox {
     public function getTitle(): string
     {
@@ -36,19 +33,19 @@ final class FooBox extends AbstractAcpDashboardBox {
 
 ## Register a Custom Box
 
-You can attach an event listener to the `wcf\system\acp\dashboard\event\AcpDashboardCollecting` event inside a bootstrap script to lazily register custom boxes.
+You can attach an event listener to the `wcf\event\acp\dashboard\box\BoxCollecting` event inside a bootstrap script to lazily register custom boxes.
 The class name of the box is registered using the event’s `register()` method:
 
 ```php title="files/lib/bootstrap/com.example.bar.php"
 <?php
 
 use wcf\system\event\EventHandler;
-use wcf\system\acp\dashboard\event\AcpDashboardCollecting;
+use wcf\event\acp\dashboard\box\BoxCollecting;
 
 return static function (): void {
     $eventHandler = EventHandler::getInstance();
 
-    $eventHandler->register(AcpDashboardCollecting::class, static function (AcpDashboardCollecting $event) {
+    $eventHandler->register(BoxCollecting::class, static function (BoxCollecting $event) {
         $event->register(\wcf\system\acp\dashboard\box\FooBox::class);
     });
 };

docs/php/api/events.md

@@ -158,3 +158,127 @@ Lastly, the following XML file has to be used to register the event listeners (y
   language="xml",
   filepath="php/api/events/eventListener.xml",
 ) }}
+
+
+## PSR-14 Events
+
+WoltLab Suite 5.5 introduces the concept of dedicated, reusable event classes.
+Any newly introduced event will receive a dedicated class, implementing the `wcf\event\IPsr14Event` interface.
+These event classes may be fired from multiple locations, making them reusable to convey that a conceptual action happened, instead of a specific class doing something.
+An example for using the new event system could be a user logging in:
+Instead of listening on a the login form being submitted and the Facebook login action successfully running, an event `UserLoggedIn` might be fired whenever a user logs in, no matter how the login is performed.
+
+Additionally, these dedicated event classes will benefit from full IDE support.
+All the relevant values may be stored as real properties on the event object.
+
+Event classes should not have an `Event` suffix and should be stored in an `event` namespace in a matching location.
+Thus, the `UserLoggedIn` example might have a FQCN of `\wcf\event\user\authentication\UserLoggedIn`.
+
+Event listeners for events implementing `IPsr14Event` need to follow [PSR-14](https://www.php-fig.org/psr/psr-14/), i.e. they need to be callable.
+In practice, this means that the event listener class needs to implement `__invoke()`.
+No interface has to be implemented in this case.
+
+Previously:
+
+```php
+$parameters = [
+    'value' => \random_int(1, 1024),
+];
+
+EventHandler::getInstance()->fireAction($this, 'valueAvailable', $parameters);
+```
+
+```php title="lib/system/event/listener/ValueDumpListener.class.php"
+<?php
+
+namespace wcf\system\event\listener;
+
+use wcf\form\ValueForm;
+
+final class ValueDumpListener implements IParameterizedEventListener
+{
+    /**
+     * @inheritDoc
+     * @param ValueForm $eventObj
+     */
+    public function execute($eventObj, $className, $eventName, array &$parameters)
+    {
+        var_dump($parameters['value']);
+    }
+}
+```
+
+Now:
+
+```php
+EventHandler::getInstance()->fire(new ValueAvailable(\random_int(1, 1024)));
+```
+
+```php title="lib/event/foo/ValueAvailable.class.php"
+<?php
+
+namespace wcf\event\foo;
+
+use wcf\event\IPsr14Event;
+
+final class ValueAvailable implements IPsr14Event
+{
+    /**
+     * @var int
+     */
+    private $value;
+
+    public function __construct(int $value)
+    {
+        $this->value = $value;
+    }
+
+    public function getValue(): int
+    {
+        return $this->value;
+    }
+}
+```
+
+```php title="lib/system/event/listener/ValueDumpListener.class.php"
+<?php
+
+namespace wcf\system\event\listener;
+
+use wcf\event\foo\ValueAvailable;
+
+final class ValueDumpListener
+{
+    public function __invoke(ValueAvailable $event): void
+    {
+        \var_dump($event->getValue());
+    }
+}
+```
+
+### Available PSR-14 Events
+
+| Class | Description |
+|-------|-------------|
+| `wcf\event\user\UsernameValidating` | Indicates that a username is currently validated. If this event is interrupted, the username is considered to be invalid. |
+| `wcf\event\acp\dashboard\box\BoxCollecting` | Requests the collection of boxes for the acp dashboard. |
+| `wcf\event\acp\dashboard\box\PHPExtensionCollecting` | Requests the collection of PHP extensions for the system info ACP dashboard box. |
+| `wcf\event\acp\dashboard\box\StatusMessageCollecting` | Requests the collection of status messages for the status message dashboard box. |
+| `wcf\event\acp\menu\item\ItemCollecting` | Requests the collection of acp menu items. |
+| `wcf\event\cache\CacheCleared` | Indicates that a full cache clear was performed. |
+| `wcf\event\endpoint\ControllerCollecting` | Collects the list of API controllers. |
+| `wcf\event\language\LanguageContentCopying` | Indicates that the contents of a language should be copied to another one. |
+| `wcf\event\language\LanguageImported` | Indicates that a language was created or updated through a manual import. |
+| `wcf\event\language\PhraseChanged` | Indicates that a phrase has been modified by the user. |
+| `wcf\event\language\PreloadPhrasesCollecting` | Requests the collection of phrases that should be included in the preload cache. |
+| `wcf\event\moderation\queue\UserAssigned` | Indicates that a user was assigned or reassigned to a moderation queue entry. |
+| `wcf\event\package\PackageInstallationPluginSynced` | Indicates that the a package installation plugin was executed through the developer tools. |
+| `wcf\event\package\PackageListChanged` | Indicates that the there have been changes to the package list. These changes include the installation, removal or update of existing packages. |
+| `wcf\event\package\PackageUpdateListChanged` | Indicates that the there have been changes to the package update list. |
+| `wcf\event\request\ActivePageResolving` | Indicates that the `RequestHandler` could not determine the active page. |
+| `wcf\event\session\PreserveVariablesCollecting` | This event allows the configuration of session variables that are to be preserved when the user changes. |
+| `wcf\event\spider\SpiderCollecting` | Requests the collection of spiders. |
+| `wcf\event\user\authentication\UserLoggedIn` | Indicates that the user actively logged in, i.e. that a user change happened in response to a user's request based off proper authentication. |
+| `wcf\event\user\authentication\configuration\ConfigurationLoading` | Indicates the loading of the user auth configuration. |
+| `wcf\event\user\menu\item\IconResolving` | Resolves the icon of a user menu item. |
+| `wcf\event\worker\RebuildWorkerCollecting` | Requests the collection of workers that should be included in the list of rebuild workers. |