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