PHPackages                             bypassflow/value-kit - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. bypassflow/value-kit

ActiveLibrary[Search & Filtering](/categories/search)

bypassflow/value-kit
====================

PHP の値に対する path access と構造変換を束ねる value 基盤。

v0.0.0(1mo ago)00MITPHPPHP >=8.5.0CI passing

Since Apr 8Pushed 1mo agoCompare

[ Source](https://github.com/bypassflow/value-kit)[ Packagist](https://packagist.org/packages/bypassflow/value-kit)[ Docs](https://ickx.jp)[ RSS](/packages/bypassflow-value-kit/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

bypassflow/value-kit
====================

[](#bypassflowvalue-kit)

`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
------

[](#公開-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-系)

- `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 の選び方
-------------

[](#accessor-の選び方)

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

### 推奨系統

[](#推奨系統-1)

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

### 下位ヘルパー

[](#下位ヘルパー-1)

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

Structure の選び方
--------------

[](#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-の返却形)

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

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

Structure の policy
------------------

[](#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` を正本とします
    - パスに配列を渡した場合、非 `list` でも `array_values()` で詰め直して処理します
    - 連想配列パスも受けますが、key ではなく value が要素として使われます

主要メソッド / ヘルパー
-------------

[](#主要メソッド--ヘルパー)

### Accessor のメソッド群

[](#accessor-のメソッド群)

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

### KeyFlattener のメソッド群

[](#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 のメソッド群

[](#recursivefilter-のメソッド群)

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

### NestedGrouper のメソッド群

[](#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](/app/modules/value-kit/USAGE.md) にまとめています。

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance94

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

32d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/95a802f3e306e0656f6d96c12b9ad645aa54a0dc015d418f2c5dc74204c05561?d=identicon)[Project ICKX](/maintainers/Project%20ICKX)

---

Top Contributors

[![wakabadou](https://avatars.githubusercontent.com/u/16948950?v=4)](https://github.com/wakabadou "wakabadou (2 commits)")

---

Tags

accessorarrayaccessbypassflowfilterflattengroupingnested-grouperobjectpath-accessorphprecursive-filterstructuretraversalvalue-kitobjectfilterstructureaccessorgroupingArrayAccessflattentraversalbypassflowvalue-kitpath-accessorrecursive-filternested-grouper

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/bypassflow-value-kit/health.svg)

```
[![Health](https://phpackages.com/badges/bypassflow-value-kit/health.svg)](https://phpackages.com/packages/bypassflow-value-kit)
```

###  Alternatives

[clue/stream-filter

A simple and modern approach to stream filtering in PHP

1.7k261.7M7](/packages/clue-stream-filter)[laminas/laminas-filter

Programmatically filter and normalize data and files

9428.0M148](/packages/laminas-laminas-filter)[friendsofcake/search

CakePHP Search plugin using PRG pattern

1742.0M37](/packages/friendsofcake-search)[htmlawed/htmlawed

Official htmLawed PHP library for HTML filtering

401.1M9](/packages/htmlawed-htmlawed)[outl1ne/nova-multiselect-filter

Multiselect filter for Laravel Nova.

45802.7k3](/packages/outl1ne-nova-multiselect-filter)[outl1ne/nova-detached-filters

This Laravel Nova package allows you to detach filters from the filter dropdown

64343.5k](/packages/outl1ne-nova-detached-filters)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)