double-opt-in / src / EventSystem / Event.php

Event.php in Double Opt-In for Contact Form 7 – Secure, GDPR-Compliant Email Verification 5.5.0, at src/EventSystem/Event.php

133 lines 2.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Base Event Class
4	*
5	* @package Forge12\DoubleOptIn\EventSystem
6	* @since 4.0.0
7	*/
8
9	namespace Forge12\DoubleOptIn\EventSystem;
10
11	if ( ! defined( 'ABSPATH' ) ) {
12	exit;
13	}
14
15	/**
16	* Class Event
17	*
18	* @api
19	*
20	* Base class for all domain events. Provides propagation control and metadata.
21	* Addon authors subclass this when dispatching their own custom events.
22	* Covered by the Addon API semver policy as of Core API 4.3.0.
23	*/
24	abstract class Event implements StoppableEventInterface {
25
26	/**
27	* Whether propagation has been stopped.
28	*
29	* @var bool
30	*/
31	private bool $propagationStopped = false;
32
33	/**
34	* When the event occurred.
35	*
36	* @var \DateTimeImmutable
37	*/
38	private \DateTimeImmutable $occurredAt;
39
40	/**
41	* Source that triggered this event.
42	*
43	* @var string\|null
44	*/
45	private ?string $triggeredBy = null;
46
47	/**
48	* Constructor.
49	*/
50	public function __construct() {
51	$this->occurredAt = new \DateTimeImmutable();
52	}
53
54	/**
55	* Stop event propagation.
56	*
57	* After calling this method, no further listeners will be invoked.
58	*
59	* @return void
60	*/
61	public function stopPropagation(): void {
62	$this->propagationStopped = true;
63	}
64
65	/**
66	* {@inheritdoc}
67	*/
68	public function isPropagationStopped(): bool {
69	return $this->propagationStopped;
70	}
71
72	/**
73	* Get when the event occurred.
74	*
75	* @return \DateTimeImmutable
76	*/
77	public function getOccurredAt(): \DateTimeImmutable {
78	return $this->occurredAt;
79	}
80
81	/**
82	* Get the source that triggered this event.
83	*
84	* @return string\|null
85	*/
86	public function getTriggeredBy(): ?string {
87	return $this->triggeredBy;
88	}
89
90	/**
91	* Set the source that triggered this event.
92	*
93	* @param string $source The source identifier.
94	*
95	* @return self
96	*/
97	public function setTriggeredBy( string $source ): self {
98	$this->triggeredBy = $source;
99	return $this;
100	}
101
102	/**
103	* Whether the EventDispatcher should bridge this event to a WordPress do_action() call.
104	*
105	* Override and return false when the WordPress hook is already fired manually
106	* (e.g. with legacy-compatible parameters) to prevent double-firing.
107	*
108	* @return bool
109	*/
110	public function shouldBridgeToWordPress(): bool {
111	return true;
112	}
113
114	/**
115	* Get the WordPress hook name for backward compatibility.
116	*
117	* This method must return the legacy WordPress action/filter name
118	* so that existing hooks continue to work.
119	*
120	* @return string The WordPress hook name.
121	*/
122	abstract public static function getWordPressHookName(): string;
123
124	/**
125	* Get the event name (class name by default).
126	*
127	* @return string
128	*/
129	public static function getEventName(): string {
130	return static::class;
131	}
132	}
133