Skip to content

Commit 947433b

Browse files
abmmhasanabmmhasan
authored
Merge pull request #12 from infocyph/feature/improvement-25
docs
2 parents a416ab2 + de61604 commit 947433b

2 files changed

Lines changed: 97 additions & 17 deletions

File tree

‎docs/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,13 @@ Contents
1616
:includehidden:
1717

1818
installation
19+
quick-usage
1920
array-helpers
2021
dot-notation
2122
collection
2223
config
2324
traits-and-helpers
24-
quick-usage
2525
rule-reference
2626

2727
The feature pages above are guide-style usage docs.
28-
Use ``API Reference (1:1)`` for the full signature catalog.
28+
Use ``Usage Reference`` for task routing and the exact API signature appendix.

‎docs/rule-reference.rst‎

Lines changed: 95 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,87 @@
1-
API Reference (1:1)
1+
Usage Reference
22
===================
33

4-
This page maps the current public API surface in ``src/`` one-to-one.
4+
This page is usage-first.
5+
Use it to pick the right feature quickly, then go deeper in the dedicated guide pages.
6+
7+
If you need exact method signatures, see the ``Exact API Signatures`` section at the end of this page.
8+
9+
How To Use This Page
10+
--------------------
11+
12+
1. Start from the feature that matches your task.
13+
2. Open the linked guide for full examples and behavior notes.
14+
3. Use the signature appendix only when you need exact parameter and return types.
15+
16+
Feature Entry Points
17+
--------------------
18+
19+
Array helpers (list/map/nested array operations):
20+
:doc:`array-helpers`
21+
22+
Dot-notation read/write for nested data:
23+
:doc:`dot-notation`
24+
25+
Object-style data pipeline and fluent transformations:
26+
:doc:`collection`
27+
28+
Configuration storage with optional get/set hooks:
29+
:doc:`config`
30+
31+
DTO and hook traits plus global helper functions:
32+
:doc:`traits-and-helpers`
33+
34+
Common Workflows
35+
----------------
36+
37+
Nested data access (read/write with fallback):
38+
39+
.. code-block:: php
40+
41+
<?php
42+
$user = ['profile' => ['name' => 'Alice']];
43+
$name = array_get($user, 'profile.name', 'Guest');
44+
array_set($user, 'profile.email', '[email protected]');
45+
46+
Collection transformation pipeline:
47+
48+
.. code-block:: php
49+
50+
<?php
51+
$result = collect([1, 2, 3, 4])
52+
->filter(fn ($v) => $v % 2 === 0)
53+
->map(fn ($v) => $v * 10)
54+
->all(); // [1 => 20, 3 => 40]
55+
56+
Runtime configuration with hooks:
57+
58+
.. code-block:: php
59+
60+
<?php
61+
$config = new \Infocyph\ArrayKit\Config\DynamicConfig();
62+
$config->onSet('app.name', fn ($v) => trim((string) $v));
63+
$config->set('app.name', ' ArrayKit ');
64+
echo $config->get('app.name'); // ArrayKit
65+
66+
Static array utilities for data shaping:
67+
68+
.. code-block:: php
69+
70+
<?php
71+
use Infocyph\ArrayKit\Array\ArrayMulti;
72+
73+
$rows = [
74+
['team' => 'A', 'score' => 10],
75+
['team' => 'B', 'score' => 30],
76+
];
77+
78+
$sorted = ArrayMulti::sortBy($rows, 'score', true);
79+
$scores = ArrayMulti::pluck($rows, 'score');
80+
81+
Exact API Signatures
82+
--------------------
83+
84+
This appendix maps the current public API surface in ``src/`` one-to-one.
585

686
Global Helper Functions
787
-----------------------
@@ -15,7 +95,7 @@ Global Helper Functions
1595
function collect(mixed $data = []): Collection
1696
function chain(mixed $data): Pipeline
1797
18-
Infocyph\ArrayKit\Array\BaseArrayHelper
98+
BaseArrayHelper
1999
---------------------------------------
20100

21101
.. code-block:: php
@@ -35,10 +115,10 @@ Infocyph\ArrayKit\Array\BaseArrayHelper
35115
public static function all(array $array, callable $callback): bool
36116
public static function tap(array $array, callable $callback): array
37117
public static function forget(array &$array, int|string|array $keys): void
38-
public static function random(array $array, int $number = null, bool $preserveKeys = false): mixed
118+
public static function random(array $array, ?int $number = null, bool $preserveKeys = false): mixed
39119
public static function doReject(array $array, mixed $callback): array
40120
41-
Infocyph\ArrayKit\Array\ArraySingle
121+
ArraySingle
42122
-----------------------------------
43123

44124
.. code-block:: php
@@ -83,7 +163,7 @@ Infocyph\ArrayKit\Array\ArraySingle
83163
public static function median(array $array): float|int
84164
public static function except(array $array, array|string $keys): array
85165
86-
Infocyph\ArrayKit\Array\ArrayMulti
166+
ArrayMulti
87167
----------------------------------
88168

89169
.. code-block:: php
@@ -123,7 +203,7 @@ Infocyph\ArrayKit\Array\ArrayMulti
123203
public static function transpose(array $matrix): array
124204
public static function pluck(array $array, string $column, ?string $indexBy = null): array
125205
126-
Infocyph\ArrayKit\Array\DotNotation
206+
DotNotation
127207
-----------------------------------
128208

129209
.. code-block:: php
@@ -149,7 +229,7 @@ Infocyph\ArrayKit\Array\DotNotation
149229
public static function offsetSet(array &$array, string $key, mixed $value): void
150230
public static function offsetUnset(array &$array, string $key): void
151231
152-
Infocyph\ArrayKit\Collection\Collection
232+
Collection
153233
---------------------------------------
154234

155235
Collection uses ``BaseCollectionTrait``. Public API:
@@ -194,7 +274,7 @@ Collection uses ``BaseCollectionTrait``. Public API:
194274
public function count(): int
195275
public function jsonSerialize(): array
196276
197-
Infocyph\ArrayKit\Collection\HookedCollection
277+
HookedCollection
198278
---------------------------------------------
199279

200280
HookedCollection extends ``Collection`` and adds hook behavior (from ``HookTrait``):
@@ -206,7 +286,7 @@ HookedCollection extends ``Collection`` and adds hook behavior (from ``HookTrait
206286
public function onGet(string $offset, callable $callback): static
207287
public function onSet(string $offset, callable $callback): static
208288
209-
Infocyph\ArrayKit\Collection\Pipeline
289+
Pipeline
210290
-------------------------------------
211291

212292
.. code-block:: php
@@ -259,7 +339,7 @@ Infocyph\ArrayKit\Collection\Pipeline
259339
public function when(bool $condition, callable $callback, ?callable $default = null): Collection
260340
public function unless(bool $condition, callable $callback, ?callable $default = null): Collection
261341
262-
Infocyph\ArrayKit\Config\Config
342+
Config
263343
-------------------------------
264344

265345
Config uses ``BaseConfigTrait``. Public API:
@@ -271,14 +351,14 @@ Config uses ``BaseConfigTrait``. Public API:
271351
public function all(): array
272352
public function has(string|array $keys): bool
273353
public function hasAny(string|array $keys): bool
274-
public function get(string|int|array $key = null, mixed $default = null): mixed
354+
public function get(string|int|array|null $key = null, mixed $default = null): mixed
275355
public function set(string|array|null $key = null, mixed $value = null, bool $overwrite = true): bool
276356
public function fill(string|array $key, mixed $value = null): bool
277357
public function forget(string|int|array $key): bool
278358
public function prepend(string $key, mixed $value): bool
279359
public function append(string $key, mixed $value): bool
280360
281-
Infocyph\ArrayKit\Config\DynamicConfig
361+
DynamicConfig
282362
--------------------------------------
283363

284364
DynamicConfig extends Config behavior with hooks and overrides:
@@ -291,7 +371,7 @@ DynamicConfig extends Config behavior with hooks and overrides:
291371
public function onGet(string $offset, callable $callback): static
292372
public function onSet(string $offset, callable $callback): static
293373
294-
Infocyph\ArrayKit\traits\DTOTrait
374+
DTOTrait
295375
---------------------------------
296376

297377
.. code-block:: php
@@ -300,7 +380,7 @@ Infocyph\ArrayKit\traits\DTOTrait
300380
public function fromArray(array $values): static
301381
public function toArray(): array
302382
303-
Infocyph\ArrayKit\traits\HookTrait
383+
HookTrait
304384
----------------------------------
305385

306386
.. code-block:: php

0 commit comments

Comments
 (0)