54 lines
2.4 KiB
PHP
54 lines
2.4 KiB
PHP
<?php
|
|
|
|
namespace Leantime\Core\Events\Contracts;
|
|
|
|
/**
|
|
* Contract for class-based domain events.
|
|
*
|
|
* Event classes live in app/Domain/{Domain}/Events/ (or app/Core/{Module}/Events/ for
|
|
* core modules), are named {Entity}{Verb} with the verb taken from the central
|
|
* {@see \Leantime\Core\Events\EventVerb} vocabulary, and carry their typed payload as
|
|
* public (constructor-promoted) properties.
|
|
*
|
|
* Listeners subscribe to the class itself:
|
|
*
|
|
* EventDispatcher::add_event_listener(TicketUpdated::class, MyListener::class);
|
|
*
|
|
* and receive the bare event object — `MyListener::handle(TicketUpdated $event)`.
|
|
*
|
|
* MIGRATION WINDOW: legacyHooks() returns the exact historical string name(s) the
|
|
* CURRENT emit site fired under (the auto-generated
|
|
* leantime.domain.{...}.{method}.{rawHook} strings). The dispatcher dual-emits to those
|
|
* names so existing string/wildcard listeners — plugins in particular — keep firing
|
|
* with today's array payload, without coordinated releases.
|
|
*
|
|
* IMPORTANT: never statically list ALL historical emit sites — that would fire every
|
|
* site's name on every dispatch (exact subscribers fire under the wrong conditions,
|
|
* wildcard subscribers fire once per name instead of once per event). When the same
|
|
* raw hook historically fired from several methods, take a constructor discriminator
|
|
* and have each call site pass its own method name — `legacyHook: __FUNCTION__` — so
|
|
* each dispatch rebuilds the single name that site produced (see the Tickets pilot
|
|
* events for the pattern).
|
|
*
|
|
* Remove the entries (and eventually the mechanism) once all consumers have migrated
|
|
* to the FQCN. Mirrors the client-side
|
|
* {@see \Leantime\Core\Events\Htmx\HtmxEvents} LEGACY_ALIASES window.
|
|
*
|
|
* Use the {@see \Leantime\Core\Events\Concerns\InteractsWithEvents} trait for the
|
|
* static dispatch() ergonomic and the default empty legacyHooks().
|
|
*/
|
|
interface LeantimeEvent
|
|
{
|
|
/**
|
|
* The exact historical dotted string name(s) the CURRENT emit site fired under —
|
|
* at most one name per dispatch in practice. When several methods historically
|
|
* emitted the same raw hook, rebuild the right name from a
|
|
* `legacyHook: __FUNCTION__` constructor discriminator; never statically list all
|
|
* sites (see class docblock). Empty for events introduced after the class-based
|
|
* system.
|
|
*
|
|
* @return array<int, string>
|
|
*/
|
|
public function legacyHooks(): array;
|
|
}
|