Skip to content

Commit 9947a7a

Browse files
michalsnmichalsn
committed
add docs
1 parent c422d73 commit 9947a7a

6 files changed

Lines changed: 213 additions & 0 deletions

File tree

‎user_guide_src/source/helpers/array_helper.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,77 @@ The following functions are available:
5656
.. note:: Prior to v4.2.0, ``dot_array_search('foo.bar.baz', ['foo' => ['bar' => 23]])`` returned ``23``
5757
due to a bug. v4.2.0 and later returns ``null``.
5858

59+
.. php:function:: dot_array_has(string $search, array $values): bool
60+
61+
:param string $search: The dot-notation string describing how to search the array
62+
:param array $values: The array to check
63+
:returns: ``true`` if the key exists, otherwise ``false``
64+
:rtype: bool
65+
66+
Checks if an array key exists using dot syntax.
67+
This method supports wildcard ``*`` in the same way as ``dot_array_search()``.
68+
69+
.. literalinclude:: array_helper/015.php
70+
:lines: 2-
71+
72+
.. php:function:: dot_array_set(array &$array, string $search, mixed $value): void
73+
74+
:param array $array: The array to modify (passed by reference)
75+
:param string $search: The dot-notation string describing where to set the value
76+
:param mixed $value: The value to set
77+
:rtype: void
78+
79+
Sets an array value using dot syntax. Missing path segments are created automatically.
80+
Wildcard ``*`` is supported with the same rule as ``dot_array_has()``:
81+
you must specify a key right after ``*``.
82+
83+
.. literalinclude:: array_helper/016.php
84+
:lines: 2-
85+
86+
.. php:function:: dot_array_unset(array &$array, string $search): bool
87+
88+
:param array $array: The array to modify (passed by reference)
89+
:param string $search: The dot-notation string describing which key to remove
90+
:returns: ``true`` if a key was removed, otherwise ``false``
91+
:rtype: bool
92+
93+
Removes array values using dot syntax.
94+
Wildcard ``*`` is supported.
95+
You can target specific keys like ``users.*.id`` or clear all keys under a path with ``user.*``.
96+
97+
.. literalinclude:: array_helper/017.php
98+
:lines: 2-
99+
100+
.. php:function:: dot_array_only(array $array, array|string $indexes): array
101+
102+
:param array $array: The source array
103+
:param array|string $indexes: One key or a list of keys using dot notation
104+
:returns: Nested array containing only the requested keys
105+
:rtype: array
106+
107+
Gets only the specified keys using dot syntax while preserving nested structure.
108+
109+
Wildcard ``*`` is supported. Unlike ``dot_array_set()`` and ``dot_array_unset()``,
110+
this method also allows wildcard at the end (for example ``user.*``).
111+
112+
.. literalinclude:: array_helper/018.php
113+
:lines: 2-
114+
115+
.. php:function:: dot_array_except(array $array, array|string $indexes): array
116+
117+
:param array $array: The source array
118+
:param array|string $indexes: One key or a list of keys using dot notation
119+
:returns: Nested array with the specified keys removed
120+
:rtype: array
121+
122+
Gets all keys except the specified ones using dot syntax.
123+
124+
Wildcard ``*`` is supported. Unlike ``dot_array_set()`` and ``dot_array_unset()``,
125+
this method also allows wildcard at the end (for example ``user.*``).
126+
127+
.. literalinclude:: array_helper/019.php
128+
:lines: 2-
129+
59130
.. php:function:: array_deep_search($key, array $array)
60131
61132
:param mixed $key: The target key

‎user_guide_src/source/helpers/array_helper/015.php‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?php
2+
3+
$data = [
4+
'users' => [
5+
['id' => 1, 'name' => 'Jane'],
6+
['id' => 2, 'name' => 'John'],
7+
],
8+
];
9+
10+
// Returns: true (all matched users have an "id" key)
11+
$hasIds = dot_array_has('users.*.id', $data);
12+
13+
// If any user is missing "id", this would return false.
14+
15+
// Returns: false
16+
$hasEmails = dot_array_has('users.*.email', $data);

‎user_guide_src/source/helpers/array_helper/016.php‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<?php
2+
3+
$data = [];
4+
5+
dot_array_set($data, 'user.profile.id', 123);
6+
dot_array_set($data, 'user.profile.name', 'John');
7+
8+
$users = [
9+
['name' => 'Jane'],
10+
['name' => 'John'],
11+
];
12+
13+
dot_array_set($users, '*.active', true);
14+
15+
/*
16+
$data is now:
17+
[
18+
'user' => [
19+
'profile' => [
20+
'id' => 123,
21+
'name' => 'John',
22+
],
23+
],
24+
]
25+
*/
26+
27+
/*
28+
$users is now:
29+
[
30+
['name' => 'Jane', 'active' => true],
31+
['name' => 'John', 'active' => true],
32+
]
33+
*/

‎user_guide_src/source/helpers/array_helper/017.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
$data = [
4+
'user' => [
5+
'profile' => [
6+
'id' => 123,
7+
'name' => 'John',
8+
],
9+
],
10+
];
11+
12+
// Returns: true
13+
$removed = dot_array_unset($data, 'user.profile.id');
14+
15+
// Returns: false (path does not exist)
16+
$removedAgain = dot_array_unset($data, 'user.profile.id');
17+
18+
$users = [
19+
['id' => 1, 'name' => 'Jane'],
20+
['id' => 2, 'name' => 'John'],
21+
];
22+
23+
// Returns: true (removes "id" from all user rows)
24+
$removedIds = dot_array_unset($users, '*.id');
25+
26+
// Returns: true (clears all keys under "user")
27+
$clearedUser = dot_array_unset($data, 'user.*');

‎user_guide_src/source/helpers/array_helper/018.php‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<?php
2+
3+
$data = [
4+
'user' => [
5+
'id' => 123,
6+
'name' => 'John',
7+
'email' => '[email protected]',
8+
],
9+
'meta' => [
10+
'request_id' => 'abc',
11+
],
12+
];
13+
14+
$only = dot_array_only($data, ['user.id', 'meta.request_id']);
15+
/*
16+
$only:
17+
[
18+
'user' => ['id' => 123],
19+
'meta' => ['request_id' => 'abc'],
20+
]
21+
*/
22+
23+
$userOnly = dot_array_only($data, 'user.*');
24+
/*
25+
$userOnly:
26+
[
27+
'user' => [
28+
'id' => 123,
29+
'name' => 'John',
30+
'email' => '[email protected]',
31+
],
32+
]
33+
*/

‎user_guide_src/source/helpers/array_helper/019.php‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<?php
2+
3+
$data = [
4+
'user' => [
5+
'id' => 123,
6+
'name' => 'John',
7+
'email' => '[email protected]',
8+
],
9+
'meta' => [
10+
'request_id' => 'abc',
11+
],
12+
];
13+
14+
$except = dot_array_except($data, ['user.email', 'meta.request_id']);
15+
/*
16+
$except:
17+
[
18+
'user' => [
19+
'id' => 123,
20+
'name' => 'John',
21+
],
22+
'meta' => [],
23+
]
24+
*/
25+
26+
$clearUser = dot_array_except($data, 'user.*');
27+
/*
28+
$clearUser:
29+
[
30+
'user' => [],
31+
'meta' => ['request_id' => 'abc'],
32+
]
33+
*/

0 commit comments

Comments
 (0)