1 | <?php |
||||||
2 | |||||||
3 | /** |
||||||
4 | * This file is part of Cycle ORM package. |
||||||
5 | * |
||||||
6 | * For the full copyright and license information, please view the LICENSE |
||||||
7 | * file that was distributed with this source code. |
||||||
8 | */ |
||||||
9 | |||||||
10 | declare(strict_types=1); |
||||||
11 | |||||||
12 | namespace Cycle\Database\Query\Traits; |
||||||
13 | |||||||
14 | use Cycle\Database\Exception\BuilderException; |
||||||
15 | |||||||
16 | trait WhereJsonTrait |
||||||
17 | { |
||||||
18 | /** |
||||||
19 | * Select records where the JSON value at the specified path is equal to the passed value. |
||||||
20 | * |
||||||
21 | * Example: |
||||||
22 | * $select->whereJson('options->notifications->type', 'sms') |
||||||
23 | * |
||||||
24 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
Documentation
Bug
introduced
by
![]() |
|||||||
25 | */ |
||||||
26 | public function whereJson(string $path, mixed $value): static |
||||||
27 | { |
||||||
28 | $this->registerWhereJsonToken('AND', $path, $value, __FUNCTION__); |
||||||
29 | return $this; |
||||||
30 | } |
||||||
31 | |||||||
32 | /** |
||||||
33 | * Similar to the whereJson method, but uses the OR operator to combine with other conditions. |
||||||
34 | * |
||||||
35 | * Example: |
||||||
36 | * $select->orWhereJson('options->notifications->type', 'sms') |
||||||
37 | * |
||||||
38 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
39 | */ |
||||||
40 | public function orWhereJson(string $path, mixed $value): static |
||||||
41 | { |
||||||
42 | $this->registerWhereJsonToken('OR', $path, $value, __FUNCTION__); |
||||||
43 | return $this; |
||||||
44 | } |
||||||
45 | |||||||
46 | /** |
||||||
47 | * Select records where the JSON array contains the passed value. |
||||||
48 | * The passed value can be an array, which will be encoded into JSON. |
||||||
49 | * |
||||||
50 | * Example: |
||||||
51 | * $select->whereJsonContains('settings->languages', 'en') |
||||||
52 | * |
||||||
53 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
54 | * @param bool $encode Encode the value into JSON. |
||||||
55 | * @param bool $validate Check that $value is a valid JSON string if the $encode parameter is false. |
||||||
56 | */ |
||||||
57 | public function whereJsonContains(string $path, mixed $value, bool $encode = true, bool $validate = true): static |
||||||
58 | { |
||||||
59 | $this->registerWhereJsonToken('AND', $path, $value, __FUNCTION__, [ |
||||||
60 | 'encode' => $encode, |
||||||
61 | 'validate' => $validate, |
||||||
62 | ]); |
||||||
63 | return $this; |
||||||
64 | } |
||||||
65 | |||||||
66 | /** |
||||||
67 | * Similar to the whereJsonContains method, but uses the OR operator to combine with other conditions. |
||||||
68 | * |
||||||
69 | * Example: |
||||||
70 | * $select->orWhereJsonContains('settings->languages', 'en') |
||||||
71 | * |
||||||
72 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
73 | * @param bool $encode Encode the value into JSON. |
||||||
74 | * @param bool $validate Check that $value is a valid JSON string if the $encode parameter is false. |
||||||
75 | */ |
||||||
76 | public function orWhereJsonContains(string $path, mixed $value, bool $encode = true, bool $validate = true): static |
||||||
77 | { |
||||||
78 | $this->registerWhereJsonToken('OR', $path, $value, __FUNCTION__, [ |
||||||
79 | 'encode' => $encode, |
||||||
80 | 'validate' => $validate, |
||||||
81 | ]); |
||||||
82 | return $this; |
||||||
83 | } |
||||||
84 | |||||||
85 | /** |
||||||
86 | * Select records where the JSON array doesn't contain the passed value. |
||||||
87 | * The passed value can be an array, which will be encoded into JSON. |
||||||
88 | * |
||||||
89 | * Example: |
||||||
90 | * $select->whereJsonDoesntContain('settings->languages', 'en') |
||||||
91 | * |
||||||
92 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
93 | * @param bool $encode Encode the value into JSON. |
||||||
94 | * @param bool $validate Check that $value is a valid JSON string if the $encode parameter is false. |
||||||
95 | */ |
||||||
96 | public function whereJsonDoesntContain(string $path, mixed $value, bool $encode = true, bool $validate = true): static |
||||||
97 | { |
||||||
98 | $this->registerWhereJsonToken('AND', $path, $value, __FUNCTION__, [ |
||||||
99 | 'encode' => $encode, |
||||||
100 | 'validate' => $validate, |
||||||
101 | ]); |
||||||
102 | return $this; |
||||||
103 | } |
||||||
104 | |||||||
105 | /** |
||||||
106 | * Similar to the whereJsonDoesntContain method, but uses the OR operator to combine with other conditions. |
||||||
107 | * |
||||||
108 | * Example: |
||||||
109 | * $select->orWhereJsonDoesntContain('settings->languages', 'en') |
||||||
110 | * |
||||||
111 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
112 | * @param bool $encode Encode the value into JSON. Encode the value into JSON. |
||||||
113 | * @param bool $validate Check that $value is a valid JSON string if the $encode parameter is false. Check that $value is a valid JSON string if the $encode parameter is false. |
||||||
114 | */ |
||||||
115 | public function orWhereJsonDoesntContain(string $path, mixed $value, bool $encode = true, bool $validate = true): static |
||||||
116 | { |
||||||
117 | $this->registerWhereJsonToken('OR', $path, $value, __FUNCTION__, [ |
||||||
118 | 'encode' => $encode, |
||||||
119 | 'validate' => $validate, |
||||||
120 | ]); |
||||||
121 | return $this; |
||||||
122 | } |
||||||
123 | |||||||
124 | /** |
||||||
125 | * Select records where the JSON contains the passed path. |
||||||
126 | * |
||||||
127 | * Example: |
||||||
128 | * $select->whereJsonContainsKey('options->languages->de') |
||||||
129 | * |
||||||
130 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
131 | */ |
||||||
132 | public function whereJsonContainsKey(string $path): static |
||||||
133 | { |
||||||
134 | $this->registerWhereJsonToken('AND', $path, null, __FUNCTION__); |
||||||
135 | return $this; |
||||||
136 | } |
||||||
137 | |||||||
138 | /** |
||||||
139 | * Similar to the whereJsonContainsKey method, but uses the OR operator to combine with other conditions. |
||||||
140 | * |
||||||
141 | * Example: |
||||||
142 | * $select->orWhereJsonContainsKey('options->languages->de') |
||||||
143 | * |
||||||
144 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
145 | */ |
||||||
146 | public function orWhereJsonContainsKey(string $path): static |
||||||
147 | { |
||||||
148 | $this->registerWhereJsonToken('OR', $path, null, __FUNCTION__); |
||||||
149 | return $this; |
||||||
150 | } |
||||||
151 | |||||||
152 | /** |
||||||
153 | * Select records where the JSON doesn't contain the passed path. |
||||||
154 | * |
||||||
155 | * Example: |
||||||
156 | * $select->whereJsonDoesntContainKey('options->languages->de') |
||||||
157 | * |
||||||
158 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
159 | */ |
||||||
160 | public function whereJsonDoesntContainKey(string $path): static |
||||||
161 | { |
||||||
162 | $this->registerWhereJsonToken('AND', $path, null, __FUNCTION__); |
||||||
163 | return $this; |
||||||
164 | } |
||||||
165 | |||||||
166 | /** |
||||||
167 | * Similar to the whereJsonDoesntContainKey method, but uses the OR operator to combine with other conditions. |
||||||
168 | * |
||||||
169 | * Example: |
||||||
170 | * $select->orWhereJsonDoesntContainKey('options->languages->de') |
||||||
171 | * |
||||||
172 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
173 | */ |
||||||
174 | public function orWhereJsonDoesntContainKey(string $path): static |
||||||
175 | { |
||||||
176 | $this->registerWhereJsonToken('OR', $path, null, __FUNCTION__); |
||||||
177 | return $this; |
||||||
178 | } |
||||||
179 | |||||||
180 | /** |
||||||
181 | * Select JSON arrays by their length. |
||||||
182 | * |
||||||
183 | * Example: |
||||||
184 | * $select->whereJsonLength('journal->errors', 1, '>=') |
||||||
185 | * |
||||||
186 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
187 | * @param "<"|"<="|"="|">"|">=" $operator Comparison operator. |
||||||
188 | */ |
||||||
189 | public function whereJsonLength(string $path, int $length, string $operator = '='): static |
||||||
190 | { |
||||||
191 | $this->registerWhereJsonToken('AND', $path, $length, __FUNCTION__, ['operator' => $operator]); |
||||||
192 | return $this; |
||||||
193 | } |
||||||
194 | |||||||
195 | /** |
||||||
196 | * Similar to the whereJsonLength method, but uses the OR operator to combine with other conditions. |
||||||
197 | * |
||||||
198 | * Example: |
||||||
199 | * $select->orWhereJsonLength('journal->errors', 1, '>=') |
||||||
200 | * |
||||||
201 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
202 | * @param "<"|"<="|"="|">"|">=" $operator Comparison operator. |
||||||
203 | */ |
||||||
204 | public function orWhereJsonLength(string $path, int $length, string $operator = '='): static |
||||||
205 | { |
||||||
206 | $this->registerWhereJsonToken('OR', $path, $length, __FUNCTION__, ['operator' => $operator]); |
||||||
207 | return $this; |
||||||
208 | } |
||||||
209 | |||||||
210 | /** |
||||||
211 | * @param non-empty-string $path |
||||||
0 ignored issues
–
show
|
|||||||
212 | * @param non-empty-string $method |
||||||
213 | * @param array<non-empty-string, mixed> $params |
||||||
214 | */ |
||||||
215 | protected function buildJsonInjection( |
||||||
216 | string $path, |
||||||
0 ignored issues
–
show
The parameter
$path is not used and could be removed.
(
Ignorable by Annotation
)
If this is a false-positive, you can also ignore this issue in your code via the
This check looks for parameters that have been defined for a function or method, but which are not used in the method body. ![]() |
|||||||
217 | mixed $value, |
||||||
0 ignored issues
–
show
The parameter
$value is not used and could be removed.
(
Ignorable by Annotation
)
If this is a false-positive, you can also ignore this issue in your code via the
This check looks for parameters that have been defined for a function or method, but which are not used in the method body. ![]() |
|||||||
218 | string $method, |
||||||
219 | array $params, |
||||||
0 ignored issues
–
show
The parameter
$params is not used and could be removed.
(
Ignorable by Annotation
)
If this is a false-positive, you can also ignore this issue in your code via the
This check looks for parameters that have been defined for a function or method, but which are not used in the method body. ![]() |
|||||||
220 | ): array { |
||||||
221 | throw new BuilderException("This database engine can't handle the `$method` method."); |
||||||
222 | } |
||||||
223 | |||||||
224 | /** |
||||||
225 | * Convert various amount of where function arguments into valid where token. |
||||||
226 | * |
||||||
227 | * @param non-empty-string $boolean Boolean joiner (AND | OR). |
||||||
0 ignored issues
–
show
|
|||||||
228 | * @param array $params Set of parameters collected from where functions. |
||||||
229 | * @param array $tokens Array to aggregate compiled tokens. Reference. |
||||||
230 | * @param callable $wrapper Callback or closure used to wrap/collect every potential parameter. |
||||||
231 | * |
||||||
232 | * @throws BuilderException |
||||||
233 | */ |
||||||
234 | abstract protected function registerToken( |
||||||
235 | string $boolean, |
||||||
236 | array $params, |
||||||
237 | array &$tokens, |
||||||
238 | callable $wrapper, |
||||||
239 | ): void; |
||||||
240 | |||||||
241 | /** |
||||||
242 | * @param "AND"|"OR" $operator Boolean joiner (AND | OR). |
||||||
0 ignored issues
–
show
|
|||||||
243 | * @param non-empty-string $path |
||||||
244 | * @param non-empty-string $method |
||||||
245 | */ |
||||||
246 | private function registerWhereJsonToken( |
||||||
247 | string $operator, |
||||||
248 | string $path, |
||||||
249 | mixed $value, |
||||||
250 | string $method, |
||||||
251 | array $params = [], |
||||||
252 | ): void { |
||||||
253 | $this->registerToken( |
||||||
254 | $operator, |
||||||
255 | $this->buildJsonInjection($path, $value, $method, $params), |
||||||
256 | $this->whereTokens, |
||||||
257 | $this->whereWrapper(), |
||||||
0 ignored issues
–
show
It seems like
whereWrapper() must be provided by classes using this trait. How about adding it as abstract method to this trait?
(
Ignorable by Annotation
)
If this is a false-positive, you can also ignore this issue in your code via the
![]() |
|||||||
258 | ); |
||||||
259 | } |
||||||
260 | } |
||||||
261 |