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\Composer\Json;
21
22	use DateTimeImmutable;
23	use FastForward\DevTools\Composer\Json\Schema\AuthorInterface;
24	use FastForward\DevTools\Composer\Json\Schema\SupportInterface;
25
26	/**
27	* Defines the contract for reading and exposing normalized metadata from a
28	* Composer `composer.json` file.
29	*
30	* This interface provides convenient accessors for commonly used package
31	* metadata, including identification, descriptive attributes, licensing,
32	* authorship, support channels, funding declarations, autoload mappings,
33	* configuration entries, scripts, and additional package-specific sections.
34	*
35	* Implementations of this interface MUST read data from a Composer-compatible
36	* source and SHALL expose that data through stable, predictable, typed accessors.
37	* When a given field is optional in Composer metadata and not declared by the
38	* package, implementations SHOULD return an appropriate empty value, nullable
39	* value, or default representation as described by each method contract.
40	*
41	* Returned values SHOULD preserve the semantic meaning of the underlying
42	* `composer.json` document. Implementations MAY normalize values for
43	* interoperability and developer convenience, provided that such normalization
44	* does not materially alter the intended meaning of the original metadata.
45	*
46	* The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
47	* "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
48	* interface are to be interpreted as described in RFC 2119.
49	*/
50	interface ComposerJsonInterface
51	{
52	/**
53	* Returns the package name declared in the Composer file.
54	*
55	* The package name SHOULD follow the conventional Composer vendor/package
56	* notation when defined. Implementations MAY return an empty string when
57	* the name field is absent or cannot be resolved.
58	*
59	* @return string the package name, or an empty string when undefined
60	*/
61	public function getName(): string;
62
63	/**
64	* Returns the package description declared in the Composer file.
65	*
66	* Implementations SHOULD return a human-readable summary of the package
67	* purpose. When the description field is not defined, an empty string
68	* SHOULD be returned.
69	*
70	* @return string the package description, or an empty string when undefined
71	*/
72	public function getDescription(): string;
73
74	/**
75	* Returns the package version declared in the Composer file.
76	*
77	* Implementations SHOULD return the version string exactly as declared or
78	* as normalized by the underlying Composer metadata source. When no version
79	* is explicitly declared, implementations MAY return an empty string.
80	*
81	* @return string the package version, or an empty string when undefined
82	*/
83	public function getVersion(): string;
84
85	/**
86	* Returns the package type declared in the Composer file.
87	*
88	* This value typically identifies how Composer or consuming tools SHOULD
89	* interpret the package, such as `library`, `project`, or another valid
90	* Composer package type. Implementations MAY return an empty string when
91	* the type field is absent.
92	*
93	* @return string the package type, or an empty string when undefined
94	*/
95	public function getType(): string;
96
97	/**
98	* Returns the package keywords declared in the Composer file.
99	*
100	* Keywords SHOULD be returned in declaration order whenever practical.
101	* When the package does not define any keywords, implementations SHOULD
102	* return an empty array.
103	*
104	* @return array<int, string> the package keywords, or an empty array when undefined
105	*/
106	public function getKeywords(): array;
107
108	/**
109	* Returns the package homepage URL declared in the Composer file.
110	*
111	* Implementations SHOULD return a fully qualified URL when one is available.
112	* When the homepage field is not defined, an empty string SHOULD be returned.
113	*
114	* @return string the homepage URL, or an empty string when undefined
115	*/
116	public function getHomepage(): string;
117
118	/**
119	* Returns the readme path or readme reference declared in the Composer file.
120	*
121	* Implementations SHOULD return the value exactly as represented by the
122	* underlying metadata source whenever possible. When the readme field is
123	* absent, an empty string SHOULD be returned.
124	*
125	* @return string the readme value, or an empty string when undefined
126	*/
127	public function getReadme(): string;
128
129	/**
130	* Returns the package time metadata as an immutable date-time instance.
131	*
132	* This value SHOULD represent the package release or metadata timestamp
133	* associated with the Composer file. Implementations MUST return a
134	* DateTimeImmutable instance.
135	*
136	* @return DateTimeImmutable|null the package time metadata as an immutable date-time value
137	*/
138	public function getTime(): ?DateTimeImmutable;
139
140	/**
141	* Returns the package license when it can be resolved to a single value.
142	*
143	* If the underlying Composer metadata contains a single license identifier,
144	* this method SHOULD return that identifier. If the metadata contains no
145	* license or multiple license values that cannot be reduced to a single
146	* unambiguous result, this method MUST return null.
147	*
148	* @return string|null the resolved license identifier, or null when no
149	*                     single license value can be determined
150	*/
151	public function getLicense(): ?string;
152
153	/**
154	* Returns the package authors declared in the Composer file.
155	*
156	* Implementations SHOULD preserve declaration order whenever practical.
157	*
158	* When `$onlyFirstAuthor` is set to `true`, this method MUST return the first
159	* declared author. If no author is declared, the implementation SHOULD handle
160	* that condition consistently with its contract and MUST NOT silently return an
161	* invalid author representation.
162	*
163	* When `$onlyFirstAuthor` is set to `false`, this method MUST return all
164	* declared authors as an iterable. If the Composer file does not declare any
165	* authors, an empty iterable MUST be returned.
166	*
167	* @param bool $onlyFirstAuthor determines whether only the first declared
168	*                              author SHALL be returned instead of the full
169	*                              author list
170	*
171	* @return AuthorInterface|iterable<int, AuthorInterface> the first declared
172	*                                                        author when
173	*                                                        `$onlyFirstAuthor`
174	*                                                        is `true`, or the full
175	*                                                        authors list when
176	*                                                        `$onlyFirstAuthor`
177	*                                                        is `false`
178	*/
179	public function getAuthors(bool $onlyFirstAuthor = false): AuthorInterface|iterable;
180
181	/**
182	* Returns the support metadata declared in the Composer file.
183	*
184	* Implementations MUST return an object implementing SupportInterface.
185	* When the support section is absent, the returned object SHOULD represent
186	* an empty support definition rather than causing failure.
187	*
188	* @return SupportInterface the support metadata object
189	*/
190	public function getSupport(): SupportInterface;
191
192	/**
193	* Returns the funding entries declared in the Composer file.
194	*
195	* Each returned element SHOULD represent a single funding definition from
196	* the optional Composer `funding` section. When no funding entries are
197	* declared, implementations SHOULD return an empty array.
198	*
199	* @return array<int, mixed> the funding entries, or an empty array when undefined
200	*/
201	public function getFunding(): array;
202
203	/**
204	* Returns the autoload configuration for the requested autoload type.
205	*
206	* The requested type typically refers to an autoload mapping section such as
207	* `psr-4`, `psr-0`, `classmap`, or `files`. When no type is provided,
208	* implementations SHOULD use the default Composer autoload type expected by
209	* the implementation, which is commonly `psr-4`.
210	*
211	* If the requested autoload type does not exist, implementations SHOULD
212	* return an empty array.
213	*
214	* @param string|null $type The autoload mapping type to retrieve. This
215	*                          defaults to `psr-4` when null.
216	*
217	* @return array<string, mixed> the autoload configuration for the requested
218	*                              type, or an empty array when unavailable
219	*/
220	public function getAutoload(?string $type = null): array;
221
222	/**
223	* Returns the development autoload configuration for the requested type.
224	*
225	* The requested type typically refers to an autoload-dev mapping section
226	* such as `psr-4`, `psr-0`, `classmap`, or `files`. When no type is
227	* provided, implementations SHOULD use the default autoload-dev type
228	* expected by the implementation, which is commonly `psr-4`.
229	*
230	* If the requested development autoload type does not exist,
231	* implementations SHOULD return an empty array.
232	*
233	* @param string|null $type The development autoload mapping type to
234	*                          retrieve. This defaults to `psr-4` when null.
235	*
236	* @return array<string, mixed> the autoload-dev configuration for the
237	*                              requested type, or an empty array when unavailable
238	*/
239	public function getAutoloadDev(?string $type = null): array;
240
241	/**
242	* Returns the minimum stability declared in the Composer file.
243	*
244	* Implementations SHOULD return the configured Composer minimum stability
245	* value, such as `stable`, `RC`, `beta`, `alpha`, or `dev`. When the field
246	* is not explicitly defined, implementations MAY return an empty string or
247	* a normalized default value according to implementation policy.
248	*
249	* @return string the minimum stability value
250	*/
251	public function getMinimumStability(): string;
252
253	/**
254	* Returns configuration data from the Composer `config` section.
255	*
256	* When a specific configuration key is provided, implementations SHOULD
257	* resolve and return the matching configuration value whenever possible.
258	* When the key is null, implementations MAY return the complete
259	* configuration structure. The returned value MAY therefore be either an
260	* array or a scalar string according to the accessed configuration entry.
261	*
262	* @param string|null $config the configuration key to retrieve, or null to
263	*                            retrieve the complete config section
264	*
265	* @return array<string, mixed>|string the requested config value or the full
266	*                                     config structure, depending on the
267	*                                     requested key
268	*/
269	public function getConfig(?string $config): array|string;
270
271	/**
272	* Returns the scripts declared in the Composer file.
273	*
274	* Implementations SHOULD return the Composer `scripts` section as a
275	* structured array. When no scripts are declared, an empty array SHOULD
276	* be returned.
277	*
278	* @return array<string, mixed> the Composer scripts configuration
279	*/
280	public function getScripts(): array;
281
282	/**
283	* Returns the extra configuration section declared in the Composer file.
284	*
285	* When a specific extra key is provided, implementations SHOULD return the
286	* matching extra configuration subset when available. When the key is null,
287	* implementations SHOULD return the complete extra section. If the section
288	* or requested key is not defined, an empty array SHOULD be returned.
289	*
290	* @param string|null $extra the extra configuration key to retrieve, or
291	*                           null to retrieve the complete extra section
292	*
293	* @return array<string, mixed> the extra configuration data, or an empty
294	*                              array when undefined
295	*/
296	public function getExtra(?string $extra = null): array;
297
298	/**
299	* Returns the executable binary declarations from the Composer file.
300	*
301	* Composer `bin` entries MAY be declared as a single string or as a list of
302	* strings. Implementations MUST therefore return either a string or an
303	* array, preserving the semantic shape expected by the consumer.
304	*
305	* @return string|array<int, string> the declared binary path or paths
306	*/
307	public function getBin(): string|array;
308
309	/**
310	* Returns the package suggestions declared in the Composer file.
311	*
312	* The returned array SHOULD represent the Composer `suggest` section, where
313	* keys typically correspond to package names and values describe why the
314	* suggested package may be useful. When no suggestions are declared,
315	* implementations SHOULD return an empty array.
316	*
317	* @return array<string, string> the package suggestion map
318	*/
319	public function getSuggest(): array;
320
321	/**
322	* Returns comment metadata associated with the Composer file.
323	*
324	* This method SHOULD expose any parsed or implementation-specific comment
325	* data that is associated with the source Composer document. When no such
326	* comments are available, implementations SHOULD return an empty array.
327	*
328	* @return array<int|string, mixed> the comment metadata, or an empty array when unavailable
329	*/
330	public function getComments(): array;
331	}