1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* Fast Forward Development Tools for PHP projects.
7	*
8	* This file is part of fast-forward/dev-tools project.
9	*
10	* @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
11	* @license  https://opensource.org/licenses/MIT MIT License
12	*
13	* @see      https://github.com/php-fast-forward/
14	* @see      https://github.com/php-fast-forward/dev-tools
15	* @see      https://github.com/php-fast-forward/dev-tools/issues
16	* @see      https://php-fast-forward.github.io/dev-tools/
17	* @see      https://datatracker.ietf.org/doc/html/rfc2119
18	*/
19
20	namespace FastForward\DevTools\Process;
21
22	use Symfony\Component\Console\Output\OutputInterface;
23	use Symfony\Component\Process\Process;
24
25	/**
26	* Defines a queue responsible for collecting and executing process instances.
27	*
28	* Implementations MUST preserve the execution contract defined by this interface
29	* and SHALL provide deterministic behavior for adding queued processes and
30	* running them.
31	*
32	* Queued processes MAY be configured to run detached from the main blocking
33	* flow and MAY also be configured to not affect the final execution result.
34	* These behaviors are independent and MUST be interpreted according to the
35	* method contract declared below.
36	*/
37	interface ProcessQueueInterface
38	{
39	/**
40	* Exit code indicating successful queue execution.
41	*
42	* This constant SHALL be returned when all queued processes that affect the
43	* final result complete successfully. Processes configured to ignore
44	* failures MUST NOT prevent this value from being returned.
45	*
46	* @var int
47	*/
48	public const SUCCESS = 0;
49
50	/**
51	* Exit code indicating a queue failure.
52	*
53	* This constant SHALL be returned when at least one queued process that
54	* affects the final result fails during startup or execution. Processes
55	* configured to ignore failures MUST NOT cause this value to be returned.
56	*
57	* @var int
58	*/
59	public const FAILURE = 1;
60
61	/**
62	* Adds a process to the queue.
63	*
64	* The provided process MUST be accepted for later execution by the queue.
65	*
66	* When $ignoreFailure is set to true, a failure of the process MUST NOT
67	* affect the final status code returned by run(). Implementations SHOULD
68	* still report or record such a failure when that information is useful
69	* for diagnostics.
70	*
71	* When $detached is set to true, the process SHALL be started without
72	* blocking the execution of subsequent queue entries. A detached process
73	* MAY continue running after the queue advances to the next entry.
74	*
75	* Implementations MUST NOT mutate the semantic intent of the supplied
76	* process in a way that would make its execution meaningfully different
77	* from what the caller configured before enqueueing it.
78	*
79	* @param Process $process the process instance that SHALL be added to the queue
80	* @param bool $ignoreFailure indicates whether a failure of this process MUST NOT affect the final queue result
81	* @param bool $detached indicates whether this process SHALL be started without blocking the next queued process
82	* @param ?string $label an optional label that MAY be used to present the process output as a grouped block
83	*/
84	public function add(
85	Process $process,
86	bool $ignoreFailure = false,
87	bool $detached = false,
88	?string $label = null
89	): void;
90
91	/**
92	* Runs the queued processes and returns the resulting status code.
93	*
94	* Implementations MUST return an integer exit status representing the
95	* overall execution result of the queue.
96	*
97	* Failures from processes added with $ignoreFailure set to true MUST NOT be
98	* reflected in the final returned status code.
99	*
100	* The returned status code SHOULD represent the aggregated outcome of all
101	* queued processes whose failures are not configured to be ignored.
102	*
103	* @param ?OutputInterface $output the output interface to which process output and diagnostics MAY be written
104	*
105	* @return int the final exit status code produced by the queue execution
106	*/
107	public function run(?OutputInterface $output = null): int;
108
109	/**
110	* Waits for all detached processes to finish execution.
111	*
112	* Implementations MUST block the execution thread until all previously
113	* started detached processes complete. This ensures the main process
114	* does not exit prematurely, preventing detached children from being
115	* abruptly terminated.
116	*
117	* @param ?OutputInterface $output the output interface to which process output and diagnostics MAY be written
118	*/
119	public function wait(?OutputInterface $output = null): void;
120	}