1<?php
2
3declare(strict_types=1);
4
5/*
6 * This file is a part of dflydev/dot-access-data.
7 *
8 * (c) Dragonfly Development Inc.
9 *
10 * For the full copyright and license information, please view the LICENSE
11 * file that was distributed with this source code.
12 */
13
14namespace Dflydev\DotAccessData;
15
16use Dflydev\DotAccessData\Exception\DataException;
17use Dflydev\DotAccessData\Exception\InvalidPathException;
18
19interface DataInterface
20{
21    public const PRESERVE = 0;
22    public const REPLACE = 1;
23    public const MERGE = 2;
24
25    /**
26     * Append a value to a key (assumes key refers to an array value)
27     *
28     * If the key does not yet exist it will be created.
29     * If the key references a non-array it's existing contents will be added into a new array before appending the new value.
30     *
31     * @param string $key
32     * @param mixed  $value
33     *
34     * @throws InvalidPathException if the given key is empty
35     */
36    public function append(string $key, $value = null): void;
37
38    /**
39     * Set a value for a key
40     *
41     * If the key does not yet exist it will be created.
42     *
43     * @param string $key
44     * @param mixed  $value
45     *
46     * @throws InvalidPathException if the given key is empty
47     * @throws DataException if the given key does not target an array
48     */
49    public function set(string $key, $value = null): void;
50
51    /**
52     * Remove a key
53     *
54     * No exception will be thrown if the key does not exist
55     *
56     * @param string $key
57     *
58     * @throws InvalidPathException if the given key is empty
59     */
60    public function remove(string $key): void;
61
62    /**
63     * Get the raw value for a key
64     *
65     * If the key does not exist, an optional default value can be returned instead.
66     * If no default is provided then an exception will be thrown instead.
67     *
68     * @param string $key
69     * @param mixed $default
70     *
71     * @return mixed
72     *
73     * @throws InvalidPathException if the given key is empty
74     * @throws InvalidPathException if the given key does not exist and no default value was given
75     *
76     * @psalm-mutation-free
77     */
78    public function get(string $key, $default = null);
79
80    /**
81     * Check if the key exists
82     *
83     * @param string $key
84     *
85     * @return bool
86     *
87     * @throws InvalidPathException if the given key is empty
88     *
89     * @psalm-mutation-free
90     */
91    public function has(string $key): bool;
92
93    /**
94     * Get a data instance for a key
95     *
96     * @param string $key
97     *
98     * @return DataInterface
99     *
100     * @throws InvalidPathException if the given key is empty
101     * @throws DataException if the given key does not reference an array
102     *
103     * @psalm-mutation-free
104     */
105    public function getData(string $key): DataInterface;
106
107    /**
108     * Import data into existing data
109     *
110     * @param array<string, mixed>                     $data
111     * @param self::PRESERVE|self::REPLACE|self::MERGE $mode
112     */
113    public function import(array $data, int $mode = self::REPLACE): void;
114
115    /**
116     * Import data from an external data into existing data
117     *
118     * @param DataInterface                            $data
119     * @param self::PRESERVE|self::REPLACE|self::MERGE $mode
120     */
121    public function importData(DataInterface $data, int $mode = self::REPLACE): void;
122
123    /**
124     * Export data as raw data
125     *
126     * @return array<string, mixed>
127     *
128     * @psalm-mutation-free
129     */
130    public function export(): array;
131}
132