1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* This file is part of php-fast-forward/config.
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) 2025-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/config
15	* @see       https://github.com/php-fast-forward
16	* @see       https://datatracker.ietf.org/doc/html/rfc2119
17	*/
18
19	namespace FastForward\Config;
20
21	use IteratorAggregate;
22	use ArrayAccess;
23
24	/**
25	* Interface ConfigInterface.
26	*
27	* Defines the contract for configuration storage and access.
28	* Implementing classes MUST support key-based configuration retrieval,
29	* nested data export, and mutation in a standardized format.
30	*
31	* This interface SHALL extend the IteratorAggregate interface to allow iteration.
32	*
33	* Keys MAY use dot notation to access nested structures, e.g., `my.next.key`
34	* corresponds to ['my' => ['next' => ['key' => $value]]].
35	*/
36	interface ConfigInterface extends IteratorAggregate, ArrayAccess
37	{
38	/**
39	* Determines if the specified key exists in the configuration.
40	*
41	* Dot notation MAY be used to check nested keys.
42	*
43	* @param string $key the configuration key to check
44	*
45	* @return bool TRUE if the key exists, FALSE otherwise
46	*/
47	public function has(string $key): bool;
48
49	/**
50	* Retrieves a value from the configuration by key.
51	*
52	* Dot notation MAY be used to access nested keys.
53	* If the key does not exist, the provided default value MUST be returned.
54	* Implementations MAY return complex nested structures or objects.
55	*
56	* @param string $key the configuration key to retrieve
57	* @param mixed $default the default value if the key is not present
58	*
59	* @return mixed the value associated with the key or the default
60	*/
61	public function get(string $key, mixed $default = null): mixed;
62
63	/**
64	* Sets a configuration value or merges an array or ConfigInterface.
65	*
66	* Dot notation MAY be used to set values into nested structures.
67	* The method MUST support:
68	* - Setting a single key/value pair.
69	* - Merging an entire associative array.
70	* - Merging another ConfigInterface instance.
71	*
72	* @param array|self|string $key a configuration key, an array, or another ConfigInterface
73	* @param mixed|null $value the value to assign, if a key is provided
74	*
75	* @return void
76	*/
77	public function set(array|self|string $key, mixed $value = null): void;
78
79	/**
80	* Removes a configuration key and its associated value.
81	*
82	* Dot notation MAY be used to specify nested keys.
83	* If the key does not exist, this method MUST do nothing.
84	*
85	* @param string $key the configuration key to remove
86	*
87	* @return void
88	*/
89	public function remove(string $key): void;
90
91	/**
92	* Exports the configuration as a nested associative array.
93	*
94	* Implementations MUST return a deep array representation of all configuration data.
95	*
96	* @return array the full configuration array
97	*/
98	public function toArray(): array;
99	}