Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
16 / 16
100.00%
7 / 7
 CRAP
100.00%
1 / 1
LazyLoadConfigTrait
100.00%
16 / 16
100.00%
7 / 7
 8
100.00%
1 / 1
 __invoke
n/a
0 / 0
n/a
0 / 0
 0
 get
100.00%
2 / 2
100.00%
1 / 1
 1
 has
100.00%
2 / 2
100.00%
1 / 1
 1
 set
100.00%
2 / 2
100.00%
1 / 1
 1
 remove
100.00%
2 / 2
100.00%
1 / 1
 1
 toArray
100.00%
2 / 2
100.00%
1 / 1
 1
 getIterator
100.00%
2 / 2
100.00%
1 / 1
 1
 getConfig
100.00%
4 / 4
100.00%
1 / 1
 2
1<?php
2
3declare(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
19namespace FastForward\Config;
20
21use Traversable;
22
23/**
24 * Trait LazyLoadConfigTrait.
25 *
26 * Implements lazy-loading behavior for configuration access.
27 * This trait MUST be used in classes implementing ConfigInterface to defer configuration instantiation
28 * until first usage. It SHALL invoke the implementing class as a callable to obtain the actual config instance.
29 */
30trait LazyLoadConfigTrait
31{
32    use ArrayAccessConfigTrait;
33
34    /**
35     * @var ConfigInterface|null holds the loaded configuration instance
36     */
37    private ?ConfigInterface $config = null;
38
39    /**
40     * Implementing class MUST define the __invoke() method to return a ConfigInterface instance.
41     *
42     * @return ConfigInterface the actual configuration instance
43     */
44    abstract public function __invoke(): ConfigInterface;
45
46    /**
47     * Retrieves a configuration value by key.
48     *
49     * @param string $key the configuration key to retrieve
50     * @param mixed|null $default the default value if the key is not found
51     *
52     * @return mixed the value of the configuration key or the default
53     */
54    public function get(string $key, mixed $default = null): mixed
55    {
56        return $this->getConfig()
57            ->get($key, $default);
58    }
59
60    /**
61     * Checks for existence of a configuration key.
62     *
63     * @param string $key the configuration key to check
64     *
65     * @return bool TRUE if the key exists, FALSE otherwise
66     */
67    public function has(string $key): bool
68    {
69        return $this->getConfig()
70            ->has($key);
71    }
72
73    /**
74     * Sets configuration data.
75     *
76     * @param array|ConfigInterface|string $key the key or set of keys/values to set
77     * @param mixed|null $value the value to set if a single key is provided
78     *
79     * @return void
80     */
81    public function set(array|ConfigInterface|string $key, mixed $value = null): void
82    {
83        $this->getConfig()
84            ->set($key, $value);
85    }
86
87    /**
88     * Removes a configuration key.
89     *
90     * @param string $key the configuration key to remove
91     *
92     * @return void
93     */
94    public function remove(string $key): void
95    {
96        $this->getConfig()
97            ->remove($key);
98    }
99
100    /**
101     * Exports the entire configuration to an array.
102     *
103     * @return array the configuration as an associative array
104     */
105    public function toArray(): array
106    {
107        return $this->getConfig()
108            ->toArray();
109    }
110
111    /**
112     * Retrieves an iterator for traversing the configuration data.
113     *
114     * @return Traversable an iterator over the configuration
115     */
116    public function getIterator(): Traversable
117    {
118        return $this->getConfig()
119            ->getIterator();
120    }
121
122    /**
123     * Retrieves or initializes the configuration instance.
124     *
125     * @return ConfigInterface the lazily-loaded configuration object
126     */
127    private function getConfig(): ConfigInterface
128    {
129        if ($this->config) {
130            return $this->config;
131        }
132
133        $this->config = \call_user_func($this);
134
135        return $this->config;
136    }
137}