README

bypassflow/value-kit は、パス指定で PHP の値を読み書きし、入れ子の値構造を軽く組み替えるためのヘルパーパッケージです。利用者向けの正本は配列系データ向けの ArrayPathAccessor としつつ、native array 専用、object 専用、混在値向けの下位ヘルパー、構造変換向けの KeyFlattener、RecursiveFilter、NestedGrouper も提供します。domain model や persistence の責務は持たず、PHP の値に寄り添う小粒ヘルパーを受ける基盤として扱います。

動作要件

• PHP 8.5+

インストール

composer require bypassflow/value-kit

クイックスタート

最短では ArrayPathAccessor からパス access を呼べます。

use bypassflow\ValueKit\Access\ArrayPathAccessor;

$name = ArrayPathAccessor::get(
    ['payload' => ['user' => ['name' => 'alice']]],
    ['payload', 'user', 'name'],
);

構造変換から始めたい場合は KeyFlattener を使えます。

use bypassflow\ValueKit\Structure\KeyFlattener;

$flat = KeyFlattener::dot([
    'payload' => ['user' => ['name' => 'alice']],
]);

公開 API

推奨系統

• Access\ArrayPathAccessor
  • 利用者向けの正本 accessor です
  • array と ArrayAccess を受けます
• Access\StrictArrayPathAccessor
  • native array のみに絞りたい場合の厳密版です
• Access\ObjectPathAccessor
  • object public property のみに絞りたい場合の特化版です

下位ヘルパー

• Access\PathAccessor
  • mixed value 向けの下位 accessor です
  • array と ArrayAccess を受けます
  • object public property もまたぎます

Structure 系

• Structure\KeyFlattener
  • 入れ子の値を平坦な key/value へ変換します
  • 平坦な key map と path/value の組という 2 種類の返り値を持ちます
  • dot() / paths() に加えて flatten() / escaped() を提供します
  • array、走査可能な ArrayAccess、object public property を読めます
• Structure\RecursiveFilter
  • 入れ子の値を再帰的に絞り込みます
  • 配列で返す形と、元の形を保って返す形を持ちます
  • keepObjectAsArray() と keepStdClass() で返り方を分けます
  • 汎用 predicate、branch policy、null / 空文字 / falsey / empty 除去ヘルパーを提供します
• Structure\NestedGrouper
  • row list を入れ子の grouped map へ変換します
  • grouped list と grouped one-map の 2 種類の返り値を持ちます
  • groupBy() / groupOneBy() / groupLastBy() と skip / normalize / duplicate policy を提供します
  • array、走査可能な ArrayAccess、object row を読めます

Accessor の選び方

最初に選ぶ時は、普段使いの系統 から決めて、そこに収まらない時だけ PathAccessor を選ぶのが基本です。

推奨系統

• ArrayPathAccessor
  • array と ArrayAccess を受ける利用者向け正本です
  • 途中パスは配列で生成します
• StrictArrayPathAccessor
  • native array のみに絞る厳密版です
  • 途中パスは配列で生成します
• ObjectPathAccessor
  • object public property のみを扱います
  • magic method や private / protected property は対象外です
  • stdClass の途中パスは object 連鎖で生成します

下位ヘルパー

• PathAccessor
  • array / ArrayAccess / object public property をまたぐ mixed ヘルパーです
  • mixed payload を 1 本で扱いたい時だけ選びます
  • stdClass の途中パスは object 連鎖で生成します

Structure の選び方

形を読むのではなく作り替えたい時は、Structure 系から選びます。

• KeyFlattener
  • 入れ子の値を一覧化したい時に選びます
  • form field map や config flatten に向きます
• RecursiveFilter
  • 入れ子の値全体から不要 leaf を落としたい時に選びます
  • request payload cleanup や export 前の掃除に向きます
• NestedGrouper
  • row list を grouped map へ組み替えたい時に選びます
  • report や template 向けの row shaping に向きます

Structure の返却形

Structure 系はヘルパーごとに返す形が違います。先に返り値の形を揃えて読むと、公開面の違いが追いやすくなります。

• KeyFlattener
  • 平坦な key map
  • path/value の組
• RecursiveFilter
  • 配列で返す形
  • 同じ形で返す形
• NestedGrouper
  • grouped list
  • grouped one-map

Structure の policy

Structure 系では policy 名もなるべく固定しています。現時点の正本語彙は skip、normalize、keep first、keep last、throw on collision です。

注意点

• ArrayAccess
  • ArrayPathAccessor が普段使いの入口です
  • PathAccessor も ArrayAccess を扱えます
  • ただし判定は offsetExists() や isset() の実装に従うため、native array と完全に同じ意味にはなりません
• object access
  • ObjectPathAccessor は object-only の意味を固定したい時に選びます
  • PathAccessor の object branch も public property のみを対象にします
  • magic method、private / protected property、reflection 的な access は行いません
• パス正規化
  • パスは int|string または list<int|string> を正本とします
  • パスに配列を渡した場合、非 list でも array_values() で詰め直して処理します
  • 連想配列パスも受けますが、key ではなく value が要素として使われます

主要メソッド / ヘルパー

Accessor のメソッド群

• existsPath() / has()
  • パス自体が辿れるかを返します
  • 終端値が null でも true です
• issetPath()
  • isset() 相当の判定です
  • 終端値が null なら false です
• get() / set() / remove()
  • 任意階層の読み取り / 更新 / 削除を行います

KeyFlattener のメソッド群

• dot() / flatten() / escaped()
  • 平坦な key map を返すメソッド群です
  • flatten() は separator、leaf transform、throw on collision policy を切り替えられます
  • escaped() は reversible encoding ではなく separator escape ヘルパーです
• paths()
  • path/value の組を返すメソッド群です
  • empty array は leaf として保持します

RecursiveFilter のメソッド群

• keep() / keepObjectAsArray() / keepStdClass()
  • 基本 keep メソッド群です
  • keep() は array 正本、keepObjectAsArray() は object 読み取り variant、keepStdClass() は同形返却 variant です
• removeNull() / removeEmptyString() / removeNullAndEmptyString() / removeFalsy() / removeEmpty()
  • 固定 policy メソッド群です
  • 基本 keep メソッドのよく使う固定 policy をまとめています

NestedGrouper のメソッド群

• groupBy() / groupBySkippingMissing() / groupByNormalized()
  • grouped list 系メソッドです
  • skip missing と normalize key は grouped list 側の policy variant です
• groupOneBy() / groupOneBySkippingMissing() / groupLastBy() / groupLastBySkippingMissing()
  • grouped one-map 系メソッドです
  • groupOneBy() は keep first、groupLastBy() は keep last の grouped one-map です

補助文書

詳しい使い分けと利用例は USAGE.md にまとめています。