From b7d2e9dc10fcd15e17e4a793264a3ce079aa6267 Mon Sep 17 00:00:00 2001 From: Marcel Werk Date: Sun, 12 May 2024 13:42:26 +0200 Subject: [PATCH] Document overhaul of the event organization See https://github.com/WoltLab/WCF/pull/5912 --- docs/migration/wsc60/deprecations_removals.md | 16 +++ docs/migration/wsc60/php.md | 8 ++ docs/package/acp-menu-items.md | 6 +- docs/php/api/events.md | 124 ++++++++++++++++++ 4 files changed, 151 insertions(+), 3 deletions(-) diff --git a/docs/migration/wsc60/deprecations_removals.md b/docs/migration/wsc60/deprecations_removals.md index c0756884..94b5b6b7 100644 --- a/docs/migration/wsc60/deprecations_removals.md +++ b/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 diff --git a/docs/migration/wsc60/php.md b/docs/migration/wsc60/php.md index 82681419..8ddc0491 100644 --- a/docs/migration/wsc60/php.md +++ b/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. diff --git a/docs/package/acp-menu-items.md b/docs/package/acp-menu-items.md index 8fed856b..24e7e6ec 100644 --- a/docs/package/acp-menu-items.md +++ b/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', diff --git a/docs/php/api/events.md b/docs/php/api/events.md index edcd723d..c63e931c 100644 --- a/docs/php/api/events.md +++ b/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" +fire(new ValueAvailable(\random_int(1, 1024))); +``` + +```php title="lib/event/foo/ValueAvailable.class.php" +value = $value; + } + + public function getValue(): int + { + return $this->value; + } +} +``` + +```php title="lib/system/event/listener/ValueDumpListener.class.php" +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. | -- 2.20.1