1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* This file is part of fast-forward/dev-tools.
7	*
8	* This source file is subject to the license bundled
9	* with this source code in the file LICENSE.
10	*
11	* @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12	* @license   https://opensource.org/licenses/MIT MIT License
13	*
14	* @see       https://github.com/php-fast-forward/dev-tools
15	* @see       https://github.com/php-fast-forward
16	* @see       https://datatracker.ietf.org/doc/html/rfc2119
17	*/
18
19	namespace FastForward\DevTools\PhpUnit\Event;
20
21	use PHPUnit\Event\Event;
22	use PHPUnit\Event\Tracer\Tracer;
23
24	/**
25	* Collects PHPUnit events grouped by their concrete event class.
26	*
27	* This tracer MUST store every received event instance under its fully
28	* qualified class name so tests MAY later inspect which events were emitted
29	* and how many times each event type occurred during execution.
30	*
31	* The collected events SHALL remain available in memory for the lifetime of
32	* this tracer instance. Consumers SHOULD treat the stored event collection as
33	* test-support state and SHOULD NOT rely on it for production behavior.
34	*
35	* @codeCoverageIgnore
36	*/
37	class EventTracer implements Tracer
38	{
39	/**
40	* Stores traced events grouped by their concrete event class name.
41	*
42	* Each key MUST be a fully qualified event class name and each value MUST
43	* contain the list of event instances received for that class.
44	*
45	* @var array<class-string<Event>, list<Event>>
46	*/
47	private array $events = [];
48
49	/**
50	* Records a PHPUnit event in the internal event registry.
51	*
52	* This method MUST group the event by its concrete runtime class and SHALL
53	* append the received instance to the corresponding event list without
54	* discarding previously traced events of the same type.
55	*
56	* @param Event $event the PHPUnit event instance to record
57	*
58	* @return void
59	*/
60	public function trace(Event $event): void
61	{
62	if (! \array_key_exists($event::class, $this->events)) {
63	$this->events[$event::class] = [];
64	}
65
66	$this->events[$event::class][] = $event;
67	}
68
69	/**
70	* Returns the number of traced events for the given event class.
71	*
72	* This method MUST return the exact number of stored events matching the
73	* provided fully qualified event class name. When no events were recorded
74	* for the given class, the method SHALL return 0.
75	*
76	* @param class-string<Event> $eventClass the fully qualified PHPUnit event
77	*                                        class name to count
78	*
79	* @return int the number of recorded events for the specified class
80	*/
81	public function count(string $eventClass): int
82	{
83	return \array_key_exists($eventClass, $this->events)
84	? \count($this->events[$eventClass])
85	: 0;
86	}
87	}