Merge "EventSubscriberBase: rename to EventIngressBase"

9 files changed, 57 insertions, 51 deletions

diff --git a/autoload.php b/autoload.php
index a7ded50c0585..7203830a63e6 100644
--- a/autoload.php
+++ b/autoload.php
@@ -1258,7 +1258,8 @@ $wgAutoloadLocalClasses = [
 	'MediaWiki\\DomainEvent\\DomainEventSource' => __DIR__ . '/includes/DomainEvent/DomainEventSource.php',
 	'MediaWiki\\DomainEvent\\DomainEventSubscriber' => __DIR__ . '/includes/DomainEvent/DomainEventSubscriber.php',
 	'MediaWiki\\DomainEvent\\EventDispatchEngine' => __DIR__ . '/includes/DomainEvent/EventDispatchEngine.php',
-	'MediaWiki\\DomainEvent\\EventSubscriberBase' => __DIR__ . '/includes/DomainEvent/EventSubscriberBase.php',
+	'MediaWiki\\DomainEvent\\EventIngressBase' => __DIR__ . '/includes/DomainEvent/EventIngressBase.php',
+	'MediaWiki\\DomainEvent\\EventSubscriberBase' => __DIR__ . '/includes/DomainEvent/EventIngressBase.php',
 	'MediaWiki\\DomainEvent\\InitializableDomainEventSubscriber' => __DIR__ . '/includes/DomainEvent/InitializableDomainEventSubscriber.php',
 	'MediaWiki\\EditPage\\Constraint\\AccidentalRecreationConstraint' => __DIR__ . '/includes/editpage/Constraint/AccidentalRecreationConstraint.php',
 	'MediaWiki\\EditPage\\Constraint\\BrokenRedirectConstraint' => __DIR__ . '/includes/editpage/Constraint/BrokenRedirectConstraint.php',
diff --git a/includes/DomainEvent/EventSubscriberBase.php b/includes/DomainEvent/EventIngressBase.php
index 5f49a8c7975b..effbca05d4a5 100644
--- a/includes/DomainEvent/EventSubscriberBase.php
+++ b/includes/DomainEvent/EventIngressBase.php
@@ -6,22 +6,40 @@ use InvalidArgumentException;
 use LogicException;
 
 /**
- * Base class for classes that implement DomainEventSubscriber.
+ * Base class for event ingress objects.
+ *
+ * Event ingress objects implements listener methods for events that a
+ * component or extension is interested in. It is responsible for determining
+ * which event should trigger which logic in the component and for mapping from
+ * the model used by the emitter of the event to the component's own model.
+ *
+ * EventIngressBase implements InitializableDomainEventSubscriber so it can be
+ * registered with and initialized by a DomainEventSource. Registration is
+ * typically done in the form of an object spec for lazy instantiation. For
+ * extensions' ingress objects that object spec can be provided in the
+ * DomainEventSubscribers section of extension.json.
+ *
+ * After instantiating a subscriber (typically a subclass of EventIngressBase),
+ * the event source will call initSubscriber() to initialize the subscriber and
+ * then registerListeners() to allow the subscriber to register listeners for
+ * the events it is interested in.
  *
  * This class provides a default implementation of registerListeners() that will
- * attempt to find listener methods for the events defined in the constructor.
- * Listener methods must have a name based on the event type, following the
- * pattern "handle{$eventType}Event".
+ * attempt to find listener methods for the events the ingress object is
+ * interested in. Listener methods must have a name based on the event type,
+ * following the pattern "handle{$eventType}Event".
  *
- * Subclasses can either override registerListeners() and register listeners
- * directly with the given DomainEventSource, or they can rely on the default
- * implementation of registerListeners() which will automatically register
- * method for each event passed to the constructor based on a naming convention.
+ * The set of events the ingress objects is interested in must be provided as
+ * part of the $options array passed to initSubscriber() when it is called by
+ * the event source. This array is simply the same as the object spec used to
+ * register the ingress object with the event source. That means that for
+ * extensions, the list of events is given as part of the ingress object's spec
+ * in extension.json.
  *
  * @since 1.44
  * @unstable until 1.45, should become stable to extend
  */
-abstract class EventSubscriberBase implements InitializableDomainEventSubscriber {
+abstract class EventIngressBase implements InitializableDomainEventSubscriber {
 
 	/**
 	 * @var string[]
@@ -29,19 +47,15 @@ abstract class EventSubscriberBase implements InitializableDomainEventSubscriber
 	private array $eventTypes = [];
 
 	/**
-	 * May be called from the constructor of subclasses that want to
-	 * directly specify the list of events.
-	 *
-	 * @param string[] $events
-	 */
-	protected function initEvents( array $events ): void {
-		$this->initSubscriber( [ 'events' => $events ] );
-	}
-
-	/**
 	 * Called by DomainEventDispatcher to provide access to the list of events to
 	 * subscribe to and any other relevant information from the extension.json.
 	 *
+	 * Known keys used in $options:
+	 * - 'events': a list of events the ingress object should register listeners
+	 *   for (required). The object must implement a listener method for each
+	 *   of the events listed here, using the following pattern:
+	 *   public function handleSomeEventEvent( SomeEvent $event ).
+	 *
 	 * @param array $options the object spec describing the subscriber, typically
 	 *        from extension.json.
 	 */
@@ -139,7 +153,7 @@ abstract class EventSubscriberBase implements InitializableDomainEventSubscriber
 
 		if ( !$this->eventTypes ) {
 			throw new LogicException(
-				'Subclassed of EventSubscriberBase must either override ' .
+				'Subclassed of EventIngressBase must either override ' .
 				'registerListeners or provide a list of event types via ' .
 				'initSubscriber() or initEvents().'
 			);
@@ -151,3 +165,6 @@ abstract class EventSubscriberBase implements InitializableDomainEventSubscriber
 	}
 
 }
+
+/** @deprecated temporary alias, remove before 1.44 release (T389033) */
+class_alias( EventIngressBase::class, 'MediaWiki\DomainEvent\EventSubscriberBase' );
diff --git a/includes/ResourceLoader/ResourceLoaderEventIngress.php b/includes/ResourceLoader/ResourceLoaderEventIngress.php
index 44c5d1bb0bf3..7ac31b869fda 100644
--- a/includes/ResourceLoader/ResourceLoaderEventIngress.php
+++ b/includes/ResourceLoader/ResourceLoaderEventIngress.php
@@ -2,7 +2,7 @@
 
 namespace MediaWiki\ResourceLoader;
 
-use MediaWiki\DomainEvent\EventSubscriberBase;
+use MediaWiki\DomainEvent\EventIngressBase;
 use MediaWiki\Page\Event\PageDeletedEvent;
 use MediaWiki\Page\Event\PageRevisionUpdatedEvent;
 use MediaWiki\Storage\PageUpdateCauses;
@@ -15,7 +15,7 @@ use Wikimedia\Rdbms\LBFactory;
  *
  * @internal
  */
-class ResourceLoaderEventIngress extends EventSubscriberBase {
+class ResourceLoaderEventIngress extends EventIngressBase {
 
 	/** Object spec intended for use with {@link DomainEventSource::registerSubscriber()} */
 	public const OBJECT_SPEC = [
diff --git a/includes/language/LanguageEventIngress.php b/includes/language/LanguageEventIngress.php
index d39ae1942358..0d2faf40a7e9 100644
--- a/includes/language/LanguageEventIngress.php
+++ b/includes/language/LanguageEventIngress.php
@@ -2,7 +2,7 @@
 
 namespace MediaWiki\Languages;
 
-use MediaWiki\DomainEvent\EventSubscriberBase;
+use MediaWiki\DomainEvent\EventIngressBase;
 use MediaWiki\Page\Event\PageDeletedEvent;
 use MediaWiki\Page\Event\PageRevisionUpdatedEvent;
 use MediaWiki\Revision\SlotRecord;
@@ -14,7 +14,7 @@ use MessageCache;
  *
  * @internal
  */
-class LanguageEventIngress extends EventSubscriberBase {
+class LanguageEventIngress extends EventIngressBase {
 
 	private MessageCache $messageCache;
 
diff --git a/includes/page/Event/PageRevisionUpdatedEvent.php b/includes/page/Event/PageRevisionUpdatedEvent.php
index bd62e2472b36..e9c323466f30 100644
--- a/includes/page/Event/PageRevisionUpdatedEvent.php
+++ b/includes/page/Event/PageRevisionUpdatedEvent.php
@@ -47,11 +47,11 @@ use Wikimedia\Assert\Assert;
  *
  * Extensions that want to subscribe to this event should list
  * "PageRevisionUpdated" as a subscribed event type.
- * Subscribers based on EventSubscriberBase should implement the
+ * Subscribers based on EventIngressBase should implement the
  * handlePageRevisionUpdatedEvent() listener method to be informed when
  * a page update has been committed to the database.
  *
- * See the documentation of EventSubscriberBase and DomainEventSource for
+ * See the documentation of EventIngressBase and DomainEventSource for
  * more options and details.
  *
  * @unstable until 1.45
diff --git a/includes/recentchanges/ChangeTrackingEventIngress.php b/includes/recentchanges/ChangeTrackingEventIngress.php
index c865b463581f..0d54f1bc1b62 100644
--- a/includes/recentchanges/ChangeTrackingEventIngress.php
+++ b/includes/recentchanges/ChangeTrackingEventIngress.php
@@ -3,7 +3,7 @@
 namespace MediaWiki\RecentChanges;
 
 use MediaWiki\ChangeTags\ChangeTagsStore;
-use MediaWiki\DomainEvent\EventSubscriberBase;
+use MediaWiki\DomainEvent\EventIngressBase;
 use MediaWiki\HookContainer\HookContainer;
 use MediaWiki\HookContainer\HookRunner;
 use MediaWiki\Page\Event\PageRevisionUpdatedEvent;
@@ -24,15 +24,7 @@ use RecentChange;
  *
  * @internal
  */
-class ChangeTrackingEventIngress extends EventSubscriberBase {
-
-	/**
-	 * The events handled by this ingress subscriber.
-	 * @see registerListeners()
-	 */
-	public const EVENTS = [
-		PageRevisionUpdatedEvent::TYPE
-	];
+class ChangeTrackingEventIngress extends EventIngressBase {
 
 	/**
 	 * Object spec used for lazy instantiation.
diff --git a/includes/search/SearchEventIngress.php b/includes/search/SearchEventIngress.php
index bc5f89791e5e..47d24493e767 100644
--- a/includes/search/SearchEventIngress.php
+++ b/includes/search/SearchEventIngress.php
@@ -2,7 +2,7 @@
 
 namespace MediaWiki\Search;
 
-use MediaWiki\DomainEvent\EventSubscriberBase;
+use MediaWiki\DomainEvent\EventIngressBase;
 use MediaWiki\Page\Event\PageDeletedEvent;
 use MediaWiki\Page\Event\PageRevisionUpdatedEvent;
 use MediaWiki\Revision\RevisionRecord;
@@ -14,7 +14,7 @@ use MediaWiki\Revision\SlotRecord;
  *
  * @internal
  */
-class SearchEventIngress extends EventSubscriberBase {
+class SearchEventIngress extends EventIngressBase {
 
 	/** Object spec intended for use with {@link DomainEventSource::registerSubscriber()} */
 	public const OBJECT_SPEC = [
diff --git a/tests/phpunit/unit/includes/DomainEvent/EventDispatchEngineTest.php b/tests/phpunit/unit/includes/DomainEvent/EventDispatchEngineTest.php
index c442ee465f4c..6893059dfea9 100644
--- a/tests/phpunit/unit/includes/DomainEvent/EventDispatchEngineTest.php
+++ b/tests/phpunit/unit/includes/DomainEvent/EventDispatchEngineTest.php
@@ -7,7 +7,7 @@ use MediaWiki\DomainEvent\DomainEvent;
 use MediaWiki\DomainEvent\DomainEventSource;
 use MediaWiki\DomainEvent\DomainEventSubscriber;
 use MediaWiki\DomainEvent\EventDispatchEngine;
-use MediaWiki\DomainEvent\EventSubscriberBase;
+use MediaWiki\DomainEvent\EventIngressBase;
 use MediaWiki\Tests\MockDatabase;
 use MediaWikiUnitTestCase;
 use Wikimedia\ObjectFactory\ObjectFactory;
@@ -274,7 +274,7 @@ class EventDispatchEngineTest extends MediaWikiUnitTestCase {
 
 		$trace = [];
 
-		$subscriber = new class ( $trace ) extends EventSubscriberBase {
+		$subscriber = new class ( $trace ) extends EventIngressBase {
 			private $trace;
 
 			public function __construct( &$trace ) {
diff --git a/tests/phpunit/unit/includes/DomainEvent/EventSubscriberBaseTest.php b/tests/phpunit/unit/includes/DomainEvent/EventIngressBaseTest.php
index 491e571f9e84..7bc57d4d8a60 100644
--- a/tests/phpunit/unit/includes/DomainEvent/EventSubscriberBaseTest.php
+++ b/tests/phpunit/unit/includes/DomainEvent/EventIngressBaseTest.php
@@ -4,15 +4,15 @@ namespace MediaWiki\Tests\DomainEvent;
 
 use MediaWiki\DomainEvent\DomainEventSource;
 use MediaWiki\DomainEvent\EventDispatchEngine;
-use MediaWiki\DomainEvent\EventSubscriberBase;
+use MediaWiki\DomainEvent\EventIngressBase;
 use MediaWikiUnitTestCase;
 use Wikimedia\ObjectFactory\ObjectFactory;
 use Wikimedia\Services\ServiceContainer;
 
 /**
- * @covers \MediaWiki\DomainEvent\EventSubscriberBase
+ * @covers \MediaWiki\DomainEvent\EventIngressBase
  */
-class EventSubscriberBaseTest extends MediaWikiUnitTestCase {
+class EventIngressBaseTest extends MediaWikiUnitTestCase {
 
 	private function newSpyEventSource( &$trace ): DomainEventSource {
 		$objectFactory = new ObjectFactory(
@@ -36,13 +36,8 @@ class EventSubscriberBaseTest extends MediaWikiUnitTestCase {
 		$trace = [];
 		$source = $this->newSpyEventSource( $trace );
 
-		$events = [ 'Foo', 'Bar' ];
-
 		// Pass the list of events as a constructor parameter
-		$subscriber = new class ( $events ) extends EventSubscriberBase {
-			public function __construct( $events ) {
-				$this->initEvents( $events );
-			}
+		$subscriber = new class extends EventIngressBase {
 
 			public function handleFooEvent() {
 				// no-op
@@ -58,6 +53,7 @@ class EventSubscriberBaseTest extends MediaWikiUnitTestCase {
 			}
 		};
 
+		$subscriber->initSubscriber( [ 'events' => [ 'Foo', 'Bar' ] ] );
 		$subscriber->registerListeners( $source );
 
 		$this->assertSame(
@@ -76,7 +72,7 @@ class EventSubscriberBaseTest extends MediaWikiUnitTestCase {
 		$events = [ 'Foo', 'Bar' ];
 
 		// Pass nothing to the constructor, rely on initSubscriber()
-		$subscriber = new class () extends EventSubscriberBase {
+		$subscriber = new class () extends EventIngressBase {
 			public function handleFooEvent() {
 				// no-op
 			}