1Dot Access Data
2===============
3
4[![Latest Version](https://img.shields.io/packagist/v/dflydev/dot-access-data.svg?style=flat-square)](https://packagist.org/packages/dflydev/dot-access-data)
5[![Total Downloads](https://img.shields.io/packagist/dt/dflydev/dot-access-data.svg?style=flat-square)](https://packagist.org/packages/dflydev/dot-access-data)
6[![Software License](https://img.shields.io/badge/License-MIT-brightgreen.svg?style=flat-square)](LICENSE)
7[![Build Status](https://img.shields.io/github/workflow/status/dflydev/dflydev-dot-access-data/Tests/main.svg?style=flat-square)](https://github.com/dflydev/dflydev-dot-access-data/actions?query=workflow%3ATests+branch%3Amain)
8[![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/dflydev/dflydev-dot-access-data.svg?style=flat-square)](https://scrutinizer-ci.com/g/dflydev/dflydev-dot-access-data/code-structure/)
9[![Quality Score](https://img.shields.io/scrutinizer/g/dflydev/dflydev-dot-access-data.svg?style=flat-square)](https://scrutinizer-ci.com/g/dflydev/dflydev-dot-access-data)
10
11Given a deep data structure, access data by dot notation.
12
13
14Requirements
15------------
16
17 * PHP (7.1+)
18
19> For PHP (5.3+) please refer to version `1.0`.
20
21
22Usage
23-----
24
25Abstract example:
26
27```php
28use Dflydev\DotAccessData\Data;
29
30$data = new Data;
31
32$data->set('a.b.c', 'C');
33$data->set('a.b.d', 'D1');
34$data->append('a.b.d', 'D2');
35$data->set('a.b.e', ['E0', 'E1', 'E2']);
36
37// C
38$data->get('a.b.c');
39
40// ['D1', 'D2']
41$data->get('a.b.d');
42
43// ['E0', 'E1', 'E2']
44$data->get('a.b.e');
45
46// true
47$data->has('a.b.c');
48
49// false
50$data->has('a.b.d.j');
51
52
53// 'some-default-value'
54$data->get('some.path.that.does.not.exist', 'some-default-value');
55
56// throws a MissingPathException because no default was given
57$data->get('some.path.that.does.not.exist');
58```
59
60A more concrete example:
61
62```php
63use Dflydev\DotAccessData\Data;
64
65$data = new Data([
66    'hosts' => [
67        'hewey' => [
68            'username' => 'hman',
69            'password' => 'HPASS',
70            'roles'    => ['web'],
71        ],
72        'dewey' => [
73            'username' => 'dman',
74            'password' => 'D---S',
75            'roles'    => ['web', 'db'],
76            'nick'     => 'dewey dman',
77        ],
78        'lewey' => [
79            'username' => 'lman',
80            'password' => 'LP@$$',
81            'roles'    => ['db'],
82        ],
83    ],
84]);
85
86// hman
87$username = $data->get('hosts.hewey.username');
88// HPASS
89$password = $data->get('hosts.hewey.password');
90// ['web']
91$roles = $data->get('hosts.hewey.roles');
92// dewey dman
93$nick = $data->get('hosts.dewey.nick');
94// Unknown
95$nick = $data->get('hosts.lewey.nick', 'Unknown');
96
97// DataInterface instance
98$dewey = $data->getData('hosts.dewey');
99// dman
100$username = $dewey->get('username');
101// D---S
102$password = $dewey->get('password');
103// ['web', 'db']
104$roles = $dewey->get('roles');
105
106// No more lewey
107$data->remove('hosts.lewey');
108
109// Add DB to hewey's roles
110$data->append('hosts.hewey.roles', 'db');
111
112$data->set('hosts.april', [
113    'username' => 'aman',
114    'password' => '@---S',
115    'roles'    => ['web'],
116]);
117
118// Check if a key exists (true to this case)
119$hasKey = $data->has('hosts.dewey.username');
120```
121
122`Data` may be used as an array, since it implements `ArrayAccess` interface:
123
124```php
125// Get
126$data->get('name') === $data['name']; // true
127
128$data['name'] = 'Dewey';
129// is equivalent to
130$data->set($name, 'Dewey');
131
132isset($data['name']) === $data->has('name');
133
134// Remove key
135unset($data['name']);
136```
137
138`/` can also be used as a path delimiter:
139
140```php
141$data->set('a/b/c', 'd');
142echo $data->get('a/b/c'); // "d"
143
144$data->get('a/b/c') === $data->get('a.b.c'); // true
145```
146
147License
148-------
149
150This library is licensed under the MIT License - see the LICENSE file
151for details.
152
153
154Community
155---------
156
157If you have questions or want to help out, join us in the
158[#dflydev](irc://irc.freenode.net/#dflydev) channel on irc.freenode.net.
159