Skip to content

Commit 3e73447

Browse files
Greg0Greg0
committed
docs: Add PHPDoc for better API experience
1 parent fdd0190 commit 3e73447

File tree

2 files changed

+200
-5
lines changed

2 files changed

+200
-5
lines changed

‎src/DatafileReader.php‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
namespace Featurevisor;
44

5+
use Exception;
6+
use InvalidArgumentException;
7+
use JsonException;
58
use Psr\Log\LoggerInterface;
69
use Psr\Log\NullLogger;
710

@@ -29,6 +32,10 @@ public static function createEmpty(LoggerInterface $logger): self
2932
]);
3033
}
3134

35+
/**
36+
* @param string|array<string, mixed> $datafile
37+
* @throws JsonException
38+
*/
3239
public static function createFromMixed($datafile, LoggerInterface $logger): self
3340
{
3441
return is_string($datafile)
@@ -40,7 +47,7 @@ public static function createFromMixed($datafile, LoggerInterface $logger): self
4047
}
4148

4249
/**
43-
* @throws \JsonException
50+
* @throws JsonException
4451
*/
4552
public static function createFromJson(string $json, LoggerInterface $logger): self
4653
{
@@ -55,7 +62,7 @@ public static function createFromJson(string $json, LoggerInterface $logger): se
5562
public static function createFromOptions(array $data): self
5663
{
5764
if (array_key_exists('datafile', $data) === false ) {
58-
throw new \InvalidArgumentException('Missing datafile key in data array');
65+
throw new InvalidArgumentException('Missing datafile key in data array');
5966
}
6067

6168
return new self(
@@ -203,7 +210,7 @@ public function allConditionsAreMatched($conditions, array $context): bool
203210
if (isset($conditions['attribute'])) {
204211
try {
205212
return Conditions::conditionIsMatched($conditions, $context, $getRegex);
206-
} catch (\Exception $e) {
213+
} catch (Exception $e) {
207214
$this->logger->warning($e->getMessage(), [
208215
'exception' => $e,
209216
'condition' => $conditions,

‎src/Featurevisor.php‎

Lines changed: 190 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ class Featurevisor
1616

1717
/**
1818
* @param array{
19-
* datafile?: string|array,
19+
* datafile?: string|array<string, mixed>,
2020
* logger?: LoggerInterface,
2121
* context?: array<string, mixed>,
2222
* sticky?: array<string, mixed>,
@@ -65,6 +65,9 @@ public function __construct(
6565
$this->logger->info('Featurevisor SDK initialized');
6666
}
6767

68+
/**
69+
* @param string|array<string, mixed> $datafile
70+
*/
6871
public function setDatafile($datafile): void
6972
{
7073
try {
@@ -77,10 +80,13 @@ public function setDatafile($datafile): void
7780
$this->logger->info('datafile set', $details);
7881
$this->emitter->trigger('datafile_set', $details);
7982
} catch (\Exception $e) {
80-
$this->logger->error('could not parse datafile', ['error' => $e->getMessage(), 'exception' => $e]);;
83+
$this->logger->error('could not parse datafile', ['error' => $e->getMessage(), 'exception' => $e]);
8184
}
8285
}
8386

87+
/**
88+
* @param array<string, mixed> $sticky
89+
*/
8490
public function setSticky(array $sticky, bool $replace = false): void
8591
{
8692
$previousStickyFeatures = $this->sticky ?? [];
@@ -122,6 +128,9 @@ public function close(): void
122128
$this->emitter->clearAll();
123129
}
124130

131+
/**
132+
* @param array<string, mixed> $context
133+
*/
125134
public function setContext(array $context, bool $replace = false): void
126135
{
127136
if ($replace) {
@@ -141,11 +150,22 @@ public function setContext(array $context, bool $replace = false): void
141150
]);
142151
}
143152

153+
/**
154+
* @param array<string, mixed> $context
155+
* @return array<string, mixed>
156+
*/
144157
public function getContext(array $context = []): array
145158
{
146159
return !empty($context) ? array_merge($this->context, $context) : $this->context;
147160
}
148161

162+
/**
163+
* @param array<string, mixed> $context
164+
* @param array{
165+
* sticky?: array<string, mixed>
166+
* } $options
167+
* @return Child
168+
*/
149169
public function spawn(array $context = [], array $options = []): Child
150170
{
151171
return new Child([
@@ -155,6 +175,16 @@ public function spawn(array $context = [], array $options = []): Child
155175
]);
156176
}
157177

178+
/**
179+
* @param array<string, mixed> $context
180+
* @param array{
181+
* defaultVariationValue?: mixed,
182+
* defaultVariableValue?: mixed,
183+
* flagEvaluation?: array<string, mixed>,
184+
* sticky?: array<string, mixed>
185+
* } $options
186+
* @return array
187+
*/
158188
private function getEvaluationDependencies(array $context, array $options = []): array
159189
{
160190
$sticky = $this->sticky;
@@ -177,6 +207,24 @@ private function getEvaluationDependencies(array $context, array $options = []):
177207
]);
178208
}
179209

210+
/**
211+
* @param array<string, mixed> $context
212+
* @param array{
213+
* defaultVariationValue?: mixed,
214+
* defaultVariableValue?: mixed,
215+
* flagEvaluation?: array<string, mixed>,
216+
* sticky?: array<string, mixed>
217+
* } $options
218+
* @return array{
219+
* type: string,
220+
* featureKey: string,
221+
* reason: string,
222+
* bucketKey: string,
223+
* bucketValue: string,
224+
* enabled: bool,
225+
* error?: string,
226+
* }
227+
*/
180228
public function evaluateFlag(string $featureKey, array $context = [], array $options = []): array
181229
{
182230
$deps = $this->getEvaluationDependencies($context, $options);
@@ -187,13 +235,40 @@ public function evaluateFlag(string $featureKey, array $context = [], array $opt
187235
]));
188236
}
189237

238+
/**
239+
* @param array<string, mixed> $context
240+
* @param array{
241+
* defaultVariationValue?: mixed,
242+
* defaultVariableValue?: mixed,
243+
* flagEvaluation?: array<string, mixed>,
244+
* sticky?: array<string, mixed>
245+
* } $options
246+
*/
190247
public function isEnabled(string $featureKey, array $context = [], array $options = []): bool
191248
{
192249
$evaluation = $this->evaluateFlag($featureKey, $context, $options);
193250

194251
return $evaluation['enabled'] ?? false;
195252
}
196253

254+
/**
255+
* @param array<string, mixed> $context
256+
* @param array{
257+
* defaultVariationValue?: mixed,
258+
* defaultVariableValue?: mixed,
259+
* flagEvaluation?: array<string, mixed>,
260+
* sticky?: array<string, mixed>
261+
* } $options
262+
* @return array{
263+
* type: string,
264+
* featureKey: string,
265+
* reason: string,
266+
* bucketKey: string,
267+
* bucketValue: string,
268+
* enabled: bool,
269+
* error?: string,
270+
* }
271+
*/
197272
public function evaluateVariation(string $featureKey, array $context = [], array $options = []): array
198273
{
199274
$deps = $this->getEvaluationDependencies($context, $options);
@@ -204,6 +279,16 @@ public function evaluateVariation(string $featureKey, array $context = [], array
204279
]));
205280
}
206281

282+
/**
283+
* @param array<string, mixed> $context
284+
* @param array{
285+
* defaultVariationValue?: mixed,
286+
* defaultVariableValue?: mixed,
287+
* flagEvaluation?: array<string, mixed>,
288+
* sticky?: array<string, mixed>
289+
* } $options
290+
* @return mixed|null
291+
*/
207292
public function getVariation(string $featureKey, array $context = [], array $options = [])
208293
{
209294
try {
@@ -229,6 +314,24 @@ public function getVariation(string $featureKey, array $context = [], array $opt
229314
}
230315
}
231316

317+
/**
318+
* @param array<string, mixed> $context
319+
* @param array{
320+
* defaultVariationValue?: mixed,
321+
* defaultVariableValue?: mixed,
322+
* flagEvaluation?: array<string, mixed>,
323+
* sticky?: array<string, mixed>
324+
* } $options
325+
* @return array{
326+
* type: string,
327+
* featureKey: string,
328+
* reason: string,
329+
* bucketKey: string,
330+
* bucketValue: string,
331+
* enabled: bool,
332+
* error?: string,
333+
* }
334+
*/
232335
public function evaluateVariable(string $featureKey, string $variableKey, array $context = [], array $options = []): array
233336
{
234337
$deps = $this->getEvaluationDependencies($context, $options);
@@ -240,6 +343,16 @@ public function evaluateVariable(string $featureKey, string $variableKey, array
240343
]));
241344
}
242345

346+
/**
347+
* @param array<string, mixed> $context
348+
* @param array{
349+
* defaultVariationValue?: mixed,
350+
* defaultVariableValue?: mixed,
351+
* flagEvaluation?: array<string, mixed>,
352+
* sticky?: array<string, mixed>
353+
* } $options
354+
* @return mixed|null
355+
*/
243356
public function getVariable(string $featureKey, string $variableKey, array $context = [], array $options = [])
244357
{
245358
try {
@@ -271,6 +384,15 @@ public function getVariable(string $featureKey, string $variableKey, array $cont
271384
}
272385
}
273386

387+
/**
388+
* @param array<string, mixed> $context
389+
* @param array{
390+
* defaultVariationValue?: mixed,
391+
* defaultVariableValue?: mixed,
392+
* flagEvaluation?: array<string, mixed>,
393+
* sticky?: array<string, mixed>
394+
* } $options
395+
*/
274396
public function getVariableBoolean(string $featureKey, string $variableKey, array $context = [], array $options = []): ?bool
275397
{
276398
$value = $this->getVariable($featureKey, $variableKey, $context, $options);
@@ -282,6 +404,15 @@ public function getVariableBoolean(string $featureKey, string $variableKey, arra
282404
return (bool) $value;
283405
}
284406

407+
/**
408+
* @param array<string, mixed> $context
409+
* @param array{
410+
* defaultVariationValue?: mixed,
411+
* defaultVariableValue?: mixed,
412+
* flagEvaluation?: array<string, mixed>,
413+
* sticky?: array<string, mixed>
414+
* } $options
415+
*/
285416
public function getVariableString(string $featureKey, string $variableKey, array $context = [], array $options = []): ?string
286417
{
287418
$value = $this->getVariable($featureKey, $variableKey, $context, $options);
@@ -293,6 +424,15 @@ public function getVariableString(string $featureKey, string $variableKey, array
293424
return (string) $value;
294425
}
295426

427+
/**
428+
* @param array<string, mixed> $context
429+
* @param array{
430+
* defaultVariationValue?: mixed,
431+
* defaultVariableValue?: mixed,
432+
* flagEvaluation?: array<string, mixed>,
433+
* sticky?: array<string, mixed>
434+
* } $options
435+
*/
296436
public function getVariableInteger(string $featureKey, string $variableKey, array $context = [], array $options = []): ?int
297437
{
298438
$value = $this->getVariable($featureKey, $variableKey, $context, $options);
@@ -304,6 +444,15 @@ public function getVariableInteger(string $featureKey, string $variableKey, arra
304444
return (int) $value;
305445
}
306446

447+
/**
448+
* @param array<string, mixed> $context
449+
* @param array{
450+
* defaultVariationValue?: mixed,
451+
* defaultVariableValue?: mixed,
452+
* flagEvaluation?: array<string, mixed>,
453+
* sticky?: array<string, mixed>
454+
* } $options
455+
*/
307456
public function getVariableDouble(string $featureKey, string $variableKey, array $context = [], array $options = []): ?float
308457
{
309458
$value = $this->getVariable($featureKey, $variableKey, $context, $options);
@@ -315,6 +464,15 @@ public function getVariableDouble(string $featureKey, string $variableKey, array
315464
return (float) $value;
316465
}
317466

467+
/**
468+
* @param array<string, mixed> $context
469+
* @param array{
470+
* defaultVariationValue?: mixed,
471+
* defaultVariableValue?: mixed,
472+
* flagEvaluation?: array<string, mixed>,
473+
* sticky?: array<string, mixed>
474+
* } $options
475+
*/
318476
public function getVariableArray(string $featureKey, string $variableKey, array $context = [], array $options = []): ?array
319477
{
320478
$value = $this->getVariable($featureKey, $variableKey, $context, $options);
@@ -326,6 +484,15 @@ public function getVariableArray(string $featureKey, string $variableKey, array
326484
return is_array($value) ? $value : [$value];
327485
}
328486

487+
/**
488+
* @param array<string, mixed> $context
489+
* @param array{
490+
* defaultVariationValue?: mixed,
491+
* defaultVariableValue?: mixed,
492+
* flagEvaluation?: array<string, mixed>,
493+
* sticky?: array<string, mixed>
494+
* } $options
495+
*/
329496
public function getVariableObject(string $featureKey, string $variableKey, array $context = [], array $options = [])
330497
{
331498
$value = $this->getVariable($featureKey, $variableKey, $context, $options);
@@ -337,6 +504,16 @@ public function getVariableObject(string $featureKey, string $variableKey, array
337504
return is_array($value) ? $value : null;
338505
}
339506

507+
/**
508+
* @param array<string, mixed> $context
509+
* @param array{
510+
* defaultVariationValue?: mixed,
511+
* defaultVariableValue?: mixed,
512+
* flagEvaluation?: array<string, mixed>,
513+
* sticky?: array<string, mixed>
514+
* } $options
515+
* @return array<mixed>|mixed|null
516+
*/
340517
public function getVariableJSON(string $featureKey, string $variableKey, array $context = [], array $options = [])
341518
{
342519
$value = $this->getVariable($featureKey, $variableKey, $context, $options);
@@ -353,6 +530,17 @@ public function getVariableJSON(string $featureKey, string $variableKey, array $
353530
return $value;
354531
}
355532

533+
/**
534+
* @param array<string, mixed> $context
535+
* @param array<string> $featureKeys
536+
* @param array{
537+
* defaultVariationValue?: mixed,
538+
* defaultVariableValue?: mixed,
539+
* flagEvaluation?: array<string, mixed>,
540+
* sticky?: array<string, mixed>
541+
* } $options
542+
* @return array<string, mixed>
543+
*/
356544
public function getAllEvaluations(array $context = [], array $featureKeys = [], array $options = []): array
357545
{
358546
$deps = $this->getEvaluationDependencies($context, $options);

0 commit comments

Comments
 (0)