Skip to content

Commit b3a3af6

Browse files
microThreadmicroThread
committed
[+]: Code improvements [+]: Added README.md
1 parent 501781d commit b3a3af6

File tree

3 files changed

+255
-11
lines changed

3 files changed

+255
-11
lines changed

‎README.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
# DotArray
2+
3+
Compatible with `PHP >=5.5`
4+
5+
Accessing PHP Arrays via DOT notation is easy as:
6+
7+
```php
8+
DotArray::create(['config' => ['some.dotted.key' => 'value']])->get('config.{some.dotted.key}')
9+
```
10+
[![Latest Stable Version](https://poser.pugx.org/binary-cube/dot-array/version)](https://packagist.org/packages/binary-cube/dot-array)
11+
[![Total Downloads](https://poser.pugx.org/binary-cube/dot-array/downloads)](https://packagist.org/packages/binary-cube/dot-array)
12+
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/003187f2016e4c4cb1b014ccc9bdb5c0)](https://www.codacy.com/app/microThread/dot-array?utm_source=github.com&utm_medium=referral&utm_content=binary-cube/dot-array&utm_campaign=Badge_Grade)
13+
[![Build Status](https://scrutinizer-ci.com/g/binary-cube/dot-array/badges/build.png?b=master)](https://scrutinizer-ci.com/g/binary-cube/dot-array/build-status/master)
14+
[![Code Coverage](https://scrutinizer-ci.com/g/binary-cube/dot-array/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/binary-cube/dot-array/?branch=master)
15+
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/binary-cube/dot-array/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/binary-cube/dot-array/?branch=master)
16+
[![License](https://poser.pugx.org/binary-cube/dot-array/license)](LICENSE)
17+
18+
-----
19+
20+
## Installing
21+
22+
- **via "composer require"**
23+
```shell
24+
composer require binary-cube/dot-array
25+
```
26+
27+
- **via composer (manually)**
28+
29+
If you're using Composer to manage dependencies, you can include the following
30+
in your `composer.json` file:
31+
32+
```json
33+
{
34+
"require": {
35+
"binary-cube/dot-array": "1.*"
36+
}
37+
}
38+
```
39+
40+
## Usage
41+
42+
43+
####### REMEMBER: YOU NEED TO KNOW YOUR DATA!
44+
####### DotArray::get() can return a new instance of DotArray in case the accessed path is an array or it will return the raw data value or the default given value.
45+
46+
- **instantiation**:
47+
- ```php
48+
new DotArray($array);
49+
DotArray::create($array);
50+
DotArray::createFromJson($jsonString);
51+
```
52+
53+
- **get**:
54+
- ```php
55+
// Because the key `sci-fi & fantasy` is array the returning value it will be a new instance of DotArray.
56+
$dot('books.{sci-fi & fantasy}');
57+
58+
// Because the price is not an array, the result will be raw data, float in this case.
59+
$dot('books.{sci-fi & fantasy}.0.price');
60+
61+
// Accessing the raw array.
62+
$dot('books.{sci-fi & fantasy}')->toArray();
63+
$dot->get('books.{sci-fi & fantasy}')->toArray();
64+
65+
// Accessing the last leaf and getting the raw data.
66+
$dot('books.{sci-fi & fantasy}.0.name');
67+
$dot->get('books.{sci-fi & fantasy}.0.name');
68+
69+
// Vanilla PHP.
70+
$dot('books.{sci-fi & fantasy}.0.name');
71+
$dot['books']['sci-fi & fantasy'][0]['name'];
72+
```
73+
74+
- **get :: more-complex**:
75+
- ```php
76+
// Using dotted key and accessing without getting confused.
77+
// Allowed tokens for keeping the names with dot(.) togethers are: '', "", [], (), {}
78+
$dot->get('config.{elastic-search}.\'v5.0\'.host')
79+
$dot->get('config.{elastic-search}."v5.0".host')
80+
$dot->get('config.{elastic-search}.[v5.0].host')
81+
$dot->get('config.{elastic-search}.(v5.0).host')
82+
$dot->get('config.{elastic-search}.{v5.0}.host')
83+
```
84+
85+
- **set**:
86+
- ```php
87+
$dot->set('books.{sci-fi & fantasy}.0.name', 'New Name');
88+
89+
// Vanilla PHP.
90+
$dot['books.{sci-fi & fantasy}.0.name'] = 'New Name';
91+
$dot['books']['sci-fi & fantasy'][0]['name'] = 'New Name';
92+
```
93+
94+
- **clear** *(empty array <=> [])*:
95+
- ```php
96+
$dot->clear('books.{sci-fi & fantasy}');
97+
$dot->clear('books.{sci-fi & fantasy}', null);
98+
$dot->clear('books.{sci-fi & fantasy}.0.name', null);
99+
100+
// Multiple keys.
101+
$dot->clear([
102+
'books.{sci-fi & fantasy}',
103+
'books.{childre\'s books}'
104+
]);
105+
106+
// Vanilla PHP.
107+
$dot['books.{sci-fi & fantasy}'] = [];
108+
```
109+
110+
- **delete** *(unset(...))*:
111+
- ```php
112+
$dot->delete('books.{sci-fi & fantasy}');
113+
$dot->delete('books.{sci-fi & fantasy}.0.name');
114+
$dot->delete(['books.{sci-fi & fantasy}.0', 'books.{childre\'s books}.0']);
115+
```
116+
117+
- **find**:
118+
- ```php
119+
/*
120+
Find the first item in an array that passes the truth test, otherwise return false
121+
The signature of the callable must be: `function ($value, $key)`.
122+
*/
123+
$book = $dot->get('books.{childre\'s books}')->find(function ($value, $key) {
124+
return $value['price'] > 0;
125+
});
126+
```
127+
128+
- **filter**:
129+
- ```php
130+
/*
131+
Use a callable function to filter through items.
132+
The signature of the callable must be: `function ($value, $key)`
133+
*/
134+
$books = $dot->get('books.{childre\'s books}')->filter(function ($value, $key) {
135+
return $value['name'] === 'Harry Potter and the Order of the Phoenix';
136+
});
137+
138+
$books->toArray();
139+
```
140+
141+
- **where**:
142+
- ```php
143+
/*
144+
Allowed Operations:
145+
=, == ===, !=, !==, <, >, <=, >=,
146+
in, not-in, between, not-between, eq, ne, lt, gt, lte, gte, contains, not-contains
147+
*/
148+
149+
// Example 1.
150+
$books = $dot->get('books.{childre\'s books}')->where(['between', 'price', 5, 12]);
151+
152+
$books->toArray();
153+
154+
// Example 2.
155+
$books = $dot->get('books.{childre\'s books}')->where(['>', 'price', 10]);
156+
157+
// Example 3.
158+
$books = $dot->get('books.{childre\'s books}')->where(['in', 'price', [8.5, 15.49]]);
159+
160+
// Example 4.
161+
$books = $dot->get('books.{childre\'s books}')->where(function ($value, $key) {
162+
return $value['name'] === 'Harry Potter and the Order of the Phoenix';
163+
});
164+
```
165+
166+
#### Data Sample:
167+
168+
```php
169+
$dummyArray = [
170+
'books' => [
171+
'sci-fi & fantasy' =>
172+
[
173+
[
174+
'name' => 'Chronicles of Narnia Box Set',
175+
'price' => 24.55,
176+
'currency' => '$',
177+
'authors' =>
178+
[
179+
[
180+
'name' => 'C.S. Lewis'
181+
],
182+
],
183+
],
184+
[
185+
'name' => 'A Game of Thrones / A Clash of Kings / A Storm of Swords / A Feast of Crows / A Dance with Dragons ',
186+
'price' => 37.97,
187+
'currency' => '$',
188+
'authors' =>
189+
[
190+
[
191+
'name' => 'George R. R. Martin'
192+
],
193+
],
194+
],
195+
],
196+
197+
'childre\'s books' =>
198+
[
199+
[
200+
'name' => 'Harry Potter and the Order of the Phoenix',
201+
'price' => 15.49,
202+
'currency' => '$',
203+
'authors' =>
204+
[
205+
[
206+
'name' => 'J. K. Rowling'
207+
],
208+
],
209+
],
210+
[
211+
'name' => 'Harry Potter and the Cursed Child',
212+
'price' => 8.5,
213+
'currency' => '$',
214+
'authors' =>
215+
[
216+
[
217+
'name' => 'J. K. Rowling',
218+
],
219+
[
220+
'name' => 'Jack Thorne'
221+
],
222+
],
223+
],
224+
],
225+
226+
],
227+
];
228+
```
229+
230+
## Authors
231+
232+
* **Banciu N. Cristian Mihai**
233+
234+
See also the list of [contributors](https://github.com/binary-cube/dot-array/graphs/contributors) who participated in this project.
235+
236+
## License
237+
238+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

‎src/DotArray.php‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -259,7 +259,7 @@ protected function segmentsToKey(array $segments)
259259
*
260260
* @return array
261261
*/
262-
protected function mergeRecursive($a, $b)
262+
protected static function mergeRecursive($a, $b)
263263
{
264264
$args = \func_get_args();
265265
$res = \array_shift($args);
@@ -448,7 +448,7 @@ public function isEmpty($key = null)
448448

449449
/**
450450
* @param null|string $key
451-
* @param null $default
451+
* @param null|mixed $default
452452
*
453453
* @return mixed|static
454454
*/
@@ -513,14 +513,10 @@ public function delete($keys)
513513
*/
514514
public function clear($keys = null, $value = [])
515515
{
516-
if (!isset($keys)) {
517-
$this->items = [];
518-
} else {
519-
$keys = (array) $keys;
516+
$keys = (array) (!isset($keys) ? [$keys] : $keys);
520517

521-
foreach ($keys as $key) {
522-
$this->write($key, $value);
523-
}
518+
foreach ($keys as $key) {
519+
$this->write($key, $value);
524520
}
525521

526522
return $this;
@@ -714,7 +710,7 @@ public function where($criteria)
714710
// Search for operation.
715711
if (\in_array($operation, $filter['tokens'])) {
716712
$closure = \Closure::fromCallable(
717-
function ($item, $key) use ($filter, $property, $value) {
713+
function ($item) use ($filter, $property, $value) {
718714
$item = (array) $item;
719715

720716
if (!array_key_exists($property, $item)) {
@@ -734,7 +730,7 @@ function ($item, $key) use ($filter, $property, $value) {
734730
// Dummy closure if nothing is provided.
735731
if (empty($closure)) {
736732
$closure = \Closure::fromCallable(
737-
function ($value, $key) {
733+
function () {
738734
return true;
739735
}
740736
);

‎tests/Integration/BasicArrayTest.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,9 +180,19 @@ public function testClear()
180180
$dot = DotArray::create($data);
181181

182182
$dot->clear('assoc_array.two');
183+
$dot->clear(['assoc_array.one', 'assoc_array.three']);
183184

185+
$users = $dot->get('mixed_array.users')->clear();
186+
187+
self::assertIsArray($dot->get('assoc_array.one')->toArray());
184188
self::assertIsArray($dot->get('assoc_array.two')->toArray());
189+
self::assertIsArray($dot->get('assoc_array.three')->toArray());
190+
self::assertIsArray($users->toArray());
191+
192+
self::assertEmpty($dot->get('assoc_array.one')->toArray());
185193
self::assertEmpty($dot->get('assoc_array.two')->toArray());
194+
self::assertEmpty($dot->get('assoc_array.three')->toArray());
195+
self::assertEmpty($users->toArray());
186196
}
187197

188198

0 commit comments

Comments
 (0)