97 lines
2.6 KiB
PHP
97 lines
2.6 KiB
PHP
|
<?php
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Core PHP Framework
|
||
|
|
*
|
||
|
|
* Licensed under the European Union Public Licence (EUPL) v1.2.
|
||
|
|
* See LICENSE file for details.
|
||
|
|
*/
|
||
|
|
|
||
|
|
declare(strict_types=1);
|
||
|
|
|
||
|
|
namespace Core\Events\Concerns;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Trait for module Boot classes to declare event version compatibility.
|
||
|
|
*
|
||
|
|
* Use this trait in your Boot class to declare which event versions your
|
||
|
|
* handlers support. This enables graceful handling of event API changes.
|
||
|
|
*
|
||
|
|
* ## Usage
|
||
|
|
*
|
||
|
|
* ```php
|
||
|
|
* class Boot
|
||
|
|
* {
|
||
|
|
* use HasEventVersion;
|
||
|
|
*
|
||
|
|
* public static array $listens = [
|
||
|
|
* WebRoutesRegistering::class => 'onWebRoutes',
|
||
|
|
* ];
|
||
|
|
*
|
||
|
|
* // Declare minimum event versions this module requires
|
||
|
|
* protected static array $eventVersions = [
|
||
|
|
* WebRoutesRegistering::class => 1,
|
||
|
|
* ];
|
||
|
|
*
|
||
|
|
* public function onWebRoutes(WebRoutesRegistering $event): void
|
||
|
|
* {
|
||
|
|
* // Handle event
|
||
|
|
* }
|
||
|
|
* }
|
||
|
|
* ```
|
||
|
|
*
|
||
|
|
* ## Version Checking
|
||
|
|
*
|
||
|
|
* During bootstrap, the framework checks version compatibility:
|
||
|
|
* - If a handler requires a version higher than available, a warning is logged
|
||
|
|
* - If a handler uses a deprecated version, a deprecation notice is raised
|
||
|
|
*/
|
||
|
|
trait HasEventVersion
|
||
|
|
{
|
||
|
|
/**
|
||
|
|
* Get the required event version for a given event class.
|
||
|
|
*
|
||
|
|
* Returns the version number from $eventVersions if defined,
|
||
|
|
* or 1 (the baseline version) if not specified.
|
||
|
|
*
|
||
|
|
* @param string $eventClass The event class name
|
||
|
|
* @return int The required version number
|
||
|
|
*/
|
||
|
|
public static function getRequiredEventVersion(string $eventClass): int
|
||
|
|
{
|
||
|
|
if (property_exists(static::class, 'eventVersions')) {
|
||
|
|
return static::$eventVersions[$eventClass] ?? 1;
|
||
|
|
}
|
||
|
|
|
||
|
|
return 1;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Check if this module is compatible with an event version.
|
||
|
|
*
|
||
|
|
* @param string $eventClass The event class name
|
||
|
|
* @param int $availableVersion The available event API version
|
||
|
|
* @return bool True if the module can handle this event version
|
||
|
|
*/
|
||
|
|
public static function isCompatibleWithEventVersion(string $eventClass, int $availableVersion): bool
|
||
|
|
{
|
||
|
|
$required = static::getRequiredEventVersion($eventClass);
|
||
|
|
|
||
|
|
return $availableVersion >= $required;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Get all declared event version requirements.
|
||
|
|
*
|
||
|
|
* @return array<class-string, int> Map of event class to required version
|
||
|
|
*/
|
||
|
|
public static function getEventVersionRequirements(): array
|
||
|
|
{
|
||
|
|
if (property_exists(static::class, 'eventVersions')) {
|
||
|
|
return static::$eventVersions;
|
||
|
|
}
|
||
|
|
|
||
|
|
return [];
|
||
|
|
}
|
||
|
|
}
|