Example:

// ただの加算の関数版なので同じキーは上書きされない
that(array_add(['a', 'b', 'c'], ['X']))->isSame(['a', 'b', 'c']);
// 異なるキーは生える
that(array_add(['a', 'b', 'c'], ['x' => 'X']))->isSame(['a', 'b', 'c', 'x' => 'X']);

$columns で集計列を指定する。 単一の callable を渡すと結果も単一になる。 複数の callable 連想配列を渡すと [キー => 集系列] の連想配列になる。 いずれにせよ引数としてそのグループの配列が渡ってくるので返り値がその列の値になる。 第2引数には「今までの結果が詰まった配列」が渡ってくる（count, avg, sum など何度もでてくる集計で便利）。

$key で集約列を指定する。 指定しなければ引数の配列そのままで集計される。 複数要素の配列を与えるとその数分潜って集計される。 クロージャを与えると返り値がキーになる。

Example:

// 単純な配列の集計
that(array_aggregate([1, 2, 3], [
    'min' => fn($elems) => min($elems),
    'max' => fn($elems) => max($elems),
    'avg' => fn($elems) => array_sum($elems) / count($elems),
]))->isSame([
    'min' => 1, // 最小値
    'max' => 3, // 最大値
    'avg' => 2, // 平均値
]);

$row1 = ['user_id' => 'hoge', 'group' => 'A', 'score' => 4];
$row2 = ['user_id' => 'fuga', 'group' => 'B', 'score' => 6];
$row3 = ['user_id' => 'fuga', 'group' => 'A', 'score' => 5];
$row4 = ['user_id' => 'hoge', 'group' => 'A', 'score' => 8];

// user_id, group ごとの score を集計して階層配列で返す（第2引数 $current を利用している）
that(array_aggregate([$row1, $row2, $row3, $row4], [
    'scores' => fn($rows) => array_column($rows, 'score'),
    'score'  => fn($rows, $current) => array_sum($current['scores']),
], ['user_id', 'group']))->isSame([
    'hoge' => [
        'A' => [
            'scores' => [4, 8],
            'score'  => 12,
        ],
    ],
    'fuga' => [
        'B' => [
            'scores' => [6],
            'score'  => 6,
        ],
        'A' => [
            'scores' => [5],
            'score'  => 5,
        ],
    ],
]);

// user_id ごとの score を集計して単一列で返す（キーのクロージャも利用している）
that(array_aggregate([$row1, $row2, $row3, $row4],
    fn($rows) => array_sum(array_column($rows, 'score')),
    fn($row) => strtoupper($row['user_id'])))->isSame([
    'HOGE' => 12,
    'FUGA' => 11,
]);

$callback が要求するならキーも渡ってくる。

Example:

that(array_and([true, true]))->isTrue();
that(array_and([true, false]))->isFalse();
that(array_and([false, false]))->isFalse();

array_push のキーが指定できる参照渡しでない版と言える。 キー指定でかつそのキーが存在するとき、値を変えつつ末尾に移動する動作となる。

Example:

// キー未指定は言語機構を利用して末尾に追加される
that(array_append([1, 2, 3], 99))->is([1, 2, 3, 99]);
// キーを指定すればそのキーで生える
that(array_append([1, 2, 3], 99, 'newkey'))->is([1, 2, 3, 'newkey' => 99]);
// 存在する場合は値が変わって末尾に移動する
that(array_append([1, 2, 3], 99, 1))->is([0 => 1, 2 => 3, 1 => 99]);

コールバックは配列で複数与える。そのキーが結果配列のキーになるが、一切マッチしなくてもキー自体は作られる。 複数のコールバックにマッチしたらその分代入されるし、どれにもマッチしなければ代入されない。 つまり5個の配列を分類したからと言って、全要素数が5個になるとは限らない（多い場合も少ない場合もある）。

$rule が要求するならキーも渡ってくる。

Example:

// lt2(2より小さい)で分類
$lt2 = fn($v) => $v < 2;
that(array_assort([1, 2, 3], [
    'lt2' => $lt2,
]))->isSame([
    'lt2' => [1],
]);
// lt3(3より小さい)、ctd(ctype_digit)で分類（両方に属する要素が存在する）
$lt3 = fn($v) => $v < 3;
that(array_assort(['1', '2', '3'], [
    'lt3' => $lt3,
    'ctd' => 'ctype_digit',
]))->isSame([
    'lt3' => ['1', '2'],
    'ctd' => ['1', '2', '3'],
]);

行列が逆転するイメージ。

Example:

$row1 = ['id' => 1, 'name' => 'A'];
$row2 = ['id' => 2, 'name' => 'B'];
$rows = [$row1, $row2];
that(array_columns($rows))->isSame(['id' => [1, 2], 'name' => ['A', 'B']]);
that(array_columns($rows, 'id'))->isSame(['id' => [1, 2]]);
that(array_columns($rows, 'name', 'id'))->isSame(['name' => [1 => 'A', 2 => 'B']]);

$callback は下記の仕様。

引数は (キー, 値, 今まで処理したキー配列) で渡ってくる。 返り値は新しいキーを返す。

• 文字列や数値を返すとそれがキーとして使われる
• null を返すと元のキーがそのまま使われる
• true を返すと数値連番が振られる
• false を返すとその要素は無かったことになる
• 配列を返すとその配列で完全に置換される

$apply_array=false で要素が配列の場合は再帰され、コールバックが適用されない（array_walk_recursive と同じ仕様）。

$apply_array=true だと配列かは問わず全ての要素にコールバックが適用される。 配列も渡ってきてしまうのでコールバック内部で is_array 判定が必要になる場合がある。

「map も filter も可能でキー変更可能かつ再帰的」というとてもマッチョな関数。 複雑だが実質的には「キーも設定できる array_walk_recursive」のように振る舞う（そしてそのような使い方を想定している）。

Example:

$array = [
   'k1' => 'v1',
   'k2' => [
       'k21' => 'v21',
       'k22' => [
           'k221' => 'v221',
           'k222' => 'v222',
       ],
       'k23' => 'v23',
   ],
];
// 全要素に 'prefix-' を付与する。キーには '_' をつける。ただし 'k21' はそのままとする。さらに 'k22' はまるごと伏せる。 'k23' は数値キーになる
$callback = function ($k, &$v) {
    if ($k === 'k21') return null;
    if ($k === 'k22') return false;
    if ($k === 'k23') return true;
    if (!is_array($v)) $v = "prefix-$v";
    return "_$k";
};
that(array_convert($array, $callback, true))->isSame([
    '_k1' => 'prefix-v1',
    '_k2' => [
        'k21' => 'v21',
        0     => 'v23',
    ],
]);

コールバックが true 相当を返した要素をカウントして返す。 普通に使う分には count(array_filter($array, $callback)) とほとんど同じだが、下記の点が微妙に異なる。

• $callback が要求するならキーも渡ってくる
• $callback には配列が渡せる。配列を渡した場合は件数を配列で返す（Example 参照）

$recursive に true を渡すと再帰的に動作する。 末端・配列を問わずに呼び出されるので場合によっては is_array などの判定が必要になる。

Example:

$array = ['hoge', 'fuga', 'piyo'];
// 'o' を含むものの数（2個）
that(array_count($array, fn($s) => strpos($s, 'o') !== false))->isSame(2);
// 'a' と 'o' を含むものをそれぞれ（1個と2個）
that(array_count($array, [
    'a' => fn($s) => strpos($s, 'a') !== false,
    'o' => fn($s) => strpos($s, 'o') !== false,
]))->isSame([
    'a' => 1,
    'o' => 2,
]);

// 再帰版
$array = [
    ['1', '2', '3'],
    ['a', 'b', 'c'],
    ['X', 'Y', 'Z'],
    [[[['a', 'M', 'Z']]]],
];
that(array_count($array, [
    'lower' => fn($v) => !is_array($v) && ctype_lower($v),
    'upper' => fn($v) => !is_array($v) && ctype_upper($v),
    'array' => fn($v) => is_array($v),
], true))->is([
    'lower' => 4, // 小文字の数
    'upper' => 5, // 大文字の数
    'array' => 7, // 配列の数
]);

文字キーは保存されるが数値キーは再割り振りされる。 ただし、文字キーが重複すると例外を投げる。

Example:

// 普通の直積
that(array_cross(
    [1, 2],
    [3, 4]
))->isSame([[1, 3], [1, 4], [2, 3], [2, 4]]);
// キーが維持される
that(array_cross(
    ['a' => 1, 2],
    ['b' => 3, 4]
))->isSame([['a' => 1, 'b' => 3], ['a' => 1, 4], [2, 'b' => 3], [2, 4]]);

フラット配列は 1 と定義する。 つまり、配列を与える限りは 0 以下を返すことはない。

第2引数 $max_depth を与えるとその階層になった時点で走査を打ち切る。 「1階層のみか？」などを調べるときは指定したほうが高速に動作する。

Example:

that(array_depth([]))->isSame(1);
that(array_depth(['hoge']))->isSame(1);
that(array_depth([['nest1' => ['nest2']]]))->isSame(3);

返り値の配列は構造化されたデータではない。 主に文字列化して出力することを想定している。

ユースケースとしては「スキーマデータ」「各環境の設定ファイル」などの差分。

• '+' はキーが追加されたことを表す
• '-' はキーが削除されたことを表す
• 両方が含まれている場合、値の変更を表す

数値キーはキーの比較は行われない。値の差分のみ返す。

Example:

// common は 中身に差分がある。 1 に key1 はあるが、 2 にはない。2 に key2 はあるが、 1 にはない。
that(array_difference([
    'common' => [
        'sub' => [
            'x' => 'val',
        ]
    ],
    'key1'   => 'hoge',
    'array'  => ['a', 'b', 'c'],
], [
    'common' => [
        'sub' => [
            'x' => 'VAL',
        ]
    ],
    'key2'   => 'fuga',
    'array'  => ['c', 'd', 'e'],
]))->isSame([
    'common.sub.x' => ['-' => 'val', '+' => 'VAL'],
    'key1'         => ['-' => 'hoge'],
    'array'        => ['-' => ['a', 'b'], '+' => ['d', 'e']],
    'key2'         => ['+' => 'fuga'],
]);

array_unique は微妙に癖があるのでシンプルに使いやすくしたもの。

• SORT_STRING|SORT_FLAG_CASE のような指定が使える（大文字小文字を無視した重複除去）
  • 厳密に言えば array_unique も指定すれば動く（が、ドキュメントに記載がない）
• 配列を渡すと下記の動作になる
  • 数値キーは配列アクセス
  • 文字キーはメソッドコール（値は引数）
• もちろん（$a, $b を受け取る）クロージャも渡せる
• 引数1つのクロージャを渡すとシュワルツ的動作になる（Example 参照）

Example:

// シンプルな重複除去
that(array_distinct([1, 2, 3, '3']))->isSame([1, 2, 3]);
// 大文字小文字を無視した重複除去
that(array_distinct(['a', 'b', 'A', 'B'], SORT_STRING|SORT_FLAG_CASE))->isSame(['a', 'b']);

$v1 = new \ArrayObject(['id' => '1', 'group' => 'aaa']);
$v2 = new \ArrayObject(['id' => '2', 'group' => 'bbb', 'dummy' => 123]);
$v3 = new \ArrayObject(['id' => '3', 'group' => 'aaa', 'dummy' => 456]);
$v4 = new \ArrayObject(['id' => '4', 'group' => 'bbb', 'dummy' => 789]);
// クロージャを指定して重複除去
that(array_distinct([$v1, $v2, $v3, $v4], fn($a, $b) => $a['group'] <=> $b['group']))->isSame([$v1, $v2]);
// 単純な配列アクセスなら文字列や配列でよい（上記と同じ結果になる）
that(array_distinct([$v1, $v2, $v3, $v4], 'group'))->isSame([$v1, $v2]);
// 文字キーの配列はメソッドコールになる（ArrayObject::count で重複検出）
that(array_distinct([$v1, $v2, $v3, $v4], ['count' => []]))->isSame([$v1, $v2]);
// 上記2つは混在できる（group キー + count メソッドで重複検出。端的に言えば "aaa+2", "bbb+3", "aaa+3", "bbb+3" で除去）
that(array_distinct([$v1, $v2, $v3, $v4], ['group', 'count' => []]))->isSame([$v1, $v2, 2 => $v3]);
// 引数1つのクロージャ
that(array_distinct([$v1, $v2, $v3, $v4], fn($ao) => $ao['group']))->isSame([$v1, $v2]);

存在しない場合は $default を返す。

Example:

$array = [
    'a' => [
        'b' => [
            'c' => 'vvv'
        ]
    ]
];
that(array_dive($array, 'a.b.c'))->isSame('vvv');
that(array_dive($array, 'a.b.x', 9))->isSame(9);
// 配列を与えても良い。その場合 $delimiter 引数は意味をなさない
that(array_dive($array, ['a', 'b', 'c']))->isSame('vvv');

配列をループで回し、その途中経過、値、キー、連番をコールバック引数で渡して最終的な結果を返り値として返す。 array_reduce と少し似てるが、下記の点が異なる。

• いわゆる $carry は返り値で表すのではなく、参照引数で表す
• 値だけでなくキー、連番も渡ってくる
• 巨大配列の場合でも速度劣化が少ない（array_reduce に巨大配列を渡すと実用にならないレベルで遅くなる）

$callback の引数は ($value, $key, $n) （$n はキーとは関係がない 0 ～ 要素数-1 の通し連番）。

返り値ではなく参照引数なので return する必要はない（ワンライナーが書きやすくなる）。 返り値が空くのでループ制御に用いる。 今のところ $callback が false を返すとそこで break するのみ。

第3引数を省略した場合、クロージャの第1引数のデフォルト値が使われる。 これは特筆すべき動作で、不格好な第3引数を完全に省略することができる（サンプルコードを参照）。 ただし「php の文法違反（今のところエラーにはならないし、全てにデフォルト値をつければ一応回避可能）」「リフレクションを使う（ほんの少し遅くなる）」などの弊害が有るので推奨はしない。 （ただ、「意図していることをコードで表す」といった観点ではこの記法の方が正しいとも思う）。

Example:

// 全要素を文字列的に足し合わせる
that(array_each([1, 2, 3, 4, 5], function (&$carry, $v) {$carry .= $v;}, ''))->isSame('12345');
// 値をキーにして要素を2乗値にする
that(array_each([1, 2, 3, 4, 5], function (&$carry, $v) {$carry[$v] = $v * $v;}, []))->isSame([
    1 => 1,
    2 => 4,
    3 => 9,
    4 => 16,
    5 => 25,
]);
// 上記と同じ。ただし、3 で break する
that(array_each([1, 2, 3, 4, 5], function (&$carry, $v, $k){
    if ($k === 3) return false;
    $carry[$v] = $v * $v;
}, []))->isSame([
    1 => 1,
    2 => 4,
    3 => 9,
]);

// 下記は完全に同じ（第3引数の代わりにデフォルト引数を使っている）
that(array_each([1, 2, 3], function (&$carry = [], $v = null) {
        $carry[$v] = $v * $v;
    }))->isSame(array_each([1, 2, 3], function (&$carry, $v) {
        $carry[$v] = $v * $v;
    }, [])
    // 個人的に↑のようなぶら下がり引数があまり好きではない（クロージャを最後の引数にしたい）
);

文字列の explode を更に一階層掘り下げたイメージ。 $condition で指定された要素は結果配列に含まれない。

$condition にはクロージャが指定できる。クロージャの場合は true 相当を返した場合に分割要素とみなされる。 引数は (値, キー)の順番。

$limit に負数を与えると「その絶対値-1までを結合したものと残り」を返す。 端的に言えば「正数を与えると後詰めでその個数で返す」「負数を与えると前詰めでその（絶対値）個数で返す」という動作になる。

Example:

// null 要素で分割
that(array_explode(['a', null, 'b', 'c'], null))->isSame([['a'], [2 => 'b', 3 => 'c']]);
// クロージャで分割（大文字で分割）
that(array_explode(['a', 'B', 'c', 'D', 'e'], fn($v) => ctype_upper($v)))->isSame([['a'], [2 => 'c'], [4 => 'e']]);
// 負数指定
that(array_explode(['a', null, 'b', null, 'c'], null, -2))->isSame([[0 => 'a', 1 => null, 2 => 'b'], [4 => 'c']]);

下記の点で array_replace_recursive と異なる。

• 元配列のキーのみでフィルタされる
• 対象配列にクロージャを渡すと現在の状態を引数にしてコールバックされる
• 値に Generator や Generator 関数を渡すと最後にまとめて値化される
  • つまり、上書きされた値は実質的にコールされない
• recursive かどうかは 最初の引数で分岐する（jQuery の extend と同じ）
• recursive の場合、元配列の値が配列の場合のみ対象となる。配列でない場合は単純に上書きされる
  • 次の値が非配列の場合、末尾に追加される
  • 次の値がクロージャの場合、元の値を引数にしてコールバックされる
  • 次の値が配列の場合
    • 元配列が数値配列なら完全にマージされる
    • 元配列が連想配列なら再帰される

この仕様上、Generator を値とする配列を対象にすることはできないが、そのような状況は稀だろう。 その代わり、使われるかどうか分からない状態でもとりあえず Generator にしておけば無駄な処理を省くことができる。

Example:

# $deep ではない単純呼び出し
that(array_extend([
    'overwrite' => 'hoge',            // 後段で指定されているので上書きされる
    'through'   => 'fuga',            // 後段で指定されていないので生き残る
    'array'     => ['a', 'b', 'c'],   // $deep ではないし後段で指定されているので完全に上書きされる
    'yield1'    => fn() => yield 123, // 後段で指定されているのでコールすらされない
    'yield2'    => fn() => yield 456, // 後段で指定されていないのでコールされる
], [
    'ignore'    => null,              // 元配列に存在しないのでスルーされる
    'overwrite' => 'HOGE',
    'array'     => ['x', 'y', 'z'],
    'yield1'    => fn() => yield 234,
]))->is([
    'overwrite' => 'HOGE',
    'through'   => 'fuga',
    'array'     => ['x', 'y', 'z'],
    'yield1'    => 234,
    'yield2'    => 456,
]);
# $deep の場合のマージ呼び出し
that(array_extend(true, [
    'array'    => ['hoge'],            // 後段がスカラーなので末尾に追加される
    'callback' => ['fuga'],            // 後段がクロージャなのでコールバックされる
    'list'     => ['a', 'b', 'c'],     // 数値配列なのでマージされる
    'hash'     => ['a' => null],       // 連想配列なので再帰される
    'yield'    => [fn() => yield 123], // generator は解決される
], [
    'array'    => 'HOGE',
    'callback' => fn($v) => $v + [1 => 'FUGA'],
    'list'     => ['x', 'y', 'z'],
    'hash'     => ['a' => ['x' => ['y' => ['z' => 'xyz']]]],
    'yield'    => [fn() => yield 456],
]))->is([
    'array'    => ['hoge', 'HOGE'],
    'callback' => ['fuga', 'FUGA'],
    'list'     => ['a', 'b', 'c', 'x', 'y', 'z'],
    'hash'     => ['a' => ['x' => ['y' => ['z' => 'xyz']]]],
    'yield'    => [123, 456],
]);

指定したキー配列をそれらのマップしたもので配列を生成する。 array_combine($keys, array_map($callback, $keys)) とほぼ等価。

Example:

$abc = ['a', 'b', 'c'];
// [a, b, c] から [a => A, b => B, c => C] を作る
that(array_fill_callback($abc, 'strtoupper'))->isSame([
    'a' => 'A',
    'b' => 'B',
    'c' => 'C',
]);
// [a, b, c] からその sha1 配列を作って大文字化する
that(array_fill_callback($abc, fn($v) => strtoupper(sha1($v))))->isSame([
    'a' => '86F7E437FAA5A7FCE15D1DDCB9EAEAEA377667B8',
    'b' => 'E9D71F5EE7C92D6DC9E92FFDAD17B8BD49418F98',
    'c' => '84A516841BA77A5B4648DE2CD0DFCB30EA46DBB4',
]);

「隙間」とは数値キーの隙間のこと。文字キーには関与しない。 連番の抜けている箇所に $values の値を順次詰めていく動作となる。

値が足りなくてもエラーにはならない。つまり、この関数を通したとしても隙間が無くなるわけではない。 また、隙間を埋めても値が余る場合（隙間より与えられた値が多い場合）は末尾に全て追加される。

負数キーは考慮しない。

Example:

// ところどころキーが抜け落ちている配列の・・・
$array = [
    1 => 'b',
    2 => 'c',
    5 => 'f',
    7 => 'h',
];
// 抜けているところを可変引数で順次埋める（'i', 'j' は隙間というより末尾追加）
that(array_fill_gap($array, 'a', 'd', 'e', 'g', 'i', 'j'))->isSame([
    0 => 'a',
    1 => 'b',
    2 => 'c',
    3 => 'd',
    4 => 'e',
    5 => 'f',
    6 => 'g',
    7 => 'h',
    8 => 'i',
    9 => 'j',
]);

// 文字キーには関与しないし、値は足りなくても良い
$array = [
    1   => 'b',
    'x' => 'noize',
    4   => 'e',
    'y' => 'noize',
    7   => 'h',
    'z' => 'noize',
];
// 文字キーはそのまま保持され、値が足りないので 6 キーはない
that(array_fill_gap($array, 'a', 'c', 'd', 'f'))->isSame([
    0   => 'a',
    1   => 'b',
    'x' => 'noize',
    2   => 'c',
    3   => 'd',
    4   => 'e',
    'y' => 'noize',
    5   => 'f',
    7   => 'h',
    'z' => 'noize',
]);

コールバックを適用して、結果が !false 要素のみ取り出す。 コールバックの第1引数を参照にして書き換えると結果にも反映される。

$callback が要求するならキーも渡ってくる。

Example:

that(array_filter_map([' a ', ' b ', ''], fn(&$v) => strlen($v) ? $v = trim($v) : false))->isSame(['a', 'b']);

要素が配列だった場合に再帰する点とコールバックの引数以外は array_filter とほとんど変わらない。 $callback が要求するならキーも渡ってくる。

$unset_empty:true だと再帰で伏せられた結果が空になった場合、そのキーも伏せられる。

Example:

$array = [
    'a'  => 'A', // 生き残る
    'e'  => '',  // 生き残らない
    'a1' => [    // A がいるため $unset_empty は無関係に a1 自体も生き残る
        'A', // 生き残る
        '',  // 生き残らない
    ],
    'a2' => [    // 生き残りが居ないため $unset_empty:true だと a2 自体も生き残らない
        '',  // 生き残らない
        '',  // 生き残らない
    ],
    'b1' => [    // a1 のネスト版
        'a' => [
            'a' => 'A',
            'e' => '',
        ],
    ],
    'b2' => [    // a2 のネスト版
        'a' => [
            'a' => '',
            'e' => '',
        ],
    ],
];
// 親を伏せない版
that(array_filter_recursive($array, fn($v) => strlen($v), false))->isSame([
    "a"  => "A",
    "a1" => ["A"],
    "a2" => [],
    "b1" => [
        "a" => [
            "a" => "A",
        ],
    ],
    "b2" => [
        "a" => [],
    ],
]);
// 親を伏せる版
that(array_filter_recursive($array, fn($v) => strlen($v), true))->isSame([
    "a"  => "A",
    "a1" => ["A"],
    "b1" => [
        "a" => [
            "a" => "A",
        ],
    ],
]);

指定したコールバックで複数回回してフィルタする。 array_filter($array, $f, $g) は array_filter(array_filter($array, $f), $g) とほぼ等しい。 コールバックが要求するならキーも渡ってくる。 さらに文字列関数で "..." から始まっているなら可変引数としてコールする。

少し変わった仕様として、コールバックに [$method => $args] を付けるとそれはメソッド呼び出しになる。 つまり各要素 $v に対して $v->$method(...$args) がフィルタ結果になる。 さらに引数が不要なら @method とするだけで良い。

Example:

// 非 null かつ小文字かつ16進数
that(array_filters(['abc', 'XYZ', null, 'ABC', 'ff', '3e7'],
    fn($v) => $v !== null,
    fn($v) => ctype_lower("$v"),
    fn($v) => ctype_xdigit("$v"),
))->isSame([0 => 'abc', 4 => 'ff']);

コールバックの返り値が true 相当のものを返す。 $is_key に true を与えるとそのキーを返す（デフォルトの動作）。 $is_key に false を与えるとコールバックの結果を返す。

この関数は論理値 FALSE を返す可能性がありますが、FALSE として評価される値を返す可能性もあります。

Example:

// 最初に見つかったキーを返す
that(array_find_first(['a', '8', '9'], 'ctype_digit'))->isSame(1);
that(array_find_first(['a', 'b', 'b'], fn($v) => $v === 'b'))->isSame(1);
// 最初に見つかったコールバック結果を返す（最初の数字の2乗を返す）
$ifnumeric2power = fn($v) => ctype_digit($v) ? $v * $v : false;
that(array_find_first(['a', '8', '9'], $ifnumeric2power, false))->isSame(64);

コールバックの返り値が true 相当のものを返す。 $is_key に true を与えるとそのキーを返す（デフォルトの動作）。 $is_key に false を与えるとコールバックの結果を返す。

この関数は論理値 FALSE を返す可能性がありますが、FALSE として評価される値を返す可能性もあります。

Example:

// 最後に見つかったキーを返す
that(array_find_last(['a', '8', '9'], 'ctype_digit'))->isSame(2);
that(array_find_last(['a', 'b', 'b'], fn($v) => $v === 'b'))->isSame(2);
// 最後に見つかったコールバック結果を返す（最初の数字の2乗を返す）
$ifnumeric2power = fn($v) => ctype_digit($v) ? $v * $v : false;
that(array_find_last(['a', '8', '9'], $ifnumeric2power, false))->isSame(81);

コールバックの返り値が true 相当のものを返す。 $is_key に true を与えるとそのキー配列を返す（デフォルトの動作）。 $is_key に false を与えるとコールバックの結果を返す。

この関数は論理値 FALSE を返す可能性がありますが、FALSE として評価される値を返す可能性もあります。

Example:

// 最初に見つかったキーを配列で返す
that(array_find_recursive([
    'a' => [
        'b' => [
            'c' => [1, 2, 3],
        ],
    ],
], fn($v) => $v === 2))->isSame(['a', 'b', 'c', 1]);

巷にあふれている実装と違って、 ["$pkey.$ckey" => $value] 形式の配列でも返せる。 $delimiter で区切り文字を指定した場合にそのようになる。 $delimiter = null の場合に本当の配列で返す（巷の実装と同じ）。

Example:

$array = [
   'k1' => 'v1',
   'k2' => [
       'k21' => 'v21',
       'k22' => [
           'k221' => 'v221',
           'k222' => 'v222',
           'k223' => [1, 2, 3],
       ],
   ],
];
// 区切り文字指定なし
that(array_flatten($array))->isSame([
   0 => 'v1',
   1 => 'v21',
   2 => 'v221',
   3 => 'v222',
   4 => 1,
   5 => 2,
   6 => 3,
]);
// 区切り文字指定
that(array_flatten($array, '.'))->isSame([
   'k1'            => 'v1',
   'k2.k21'        => 'v21',
   'k2.k22.k221'   => 'v221',
   'k2.k22.k222'   => 'v222',
   'k2.k22.k223.0' => 1,
   'k2.k22.k223.1' => 2,
   'k2.k22.k223.2' => 3,
]);

存在しない場合は $default を返す。

$key に配列を与えるとそれらの値の配列を返す（lookup 的な動作）。 その場合、$default が活きるのは「全て無かった場合」となる。

さらに $key が配列の場合に限り、 $default を省略すると空配列として動作する。

同様に、$key にクロージャを与えると、その返り値が true 相当のものを返す。 その際、 $default が配列なら一致するものを配列で返し、配列でないなら単値で返す。

Example:

// 単純取得
that(array_get(['a', 'b', 'c'], 1))->isSame('b');
// 単純デフォルト
that(array_get(['a', 'b', 'c'], 9, 999))->isSame(999);
// 配列取得
that(array_get(['a', 'b', 'c'], [0, 2]))->isSame([0 => 'a', 2 => 'c']);
// 配列部分取得
that(array_get(['a', 'b', 'c'], [0, 9]))->isSame([0 => 'a']);
// 配列デフォルト（null ではなく [] を返す）
that(array_get(['a', 'b', 'c'], [9]))->isSame([]);
// クロージャ指定＆単値（コールバックが true を返す最初の要素）
that(array_get(['a', 'b', 'c'], fn($v) => in_array($v, ['b', 'c'])))->isSame('b');
// クロージャ指定＆配列（コールバックが true を返すもの）
that(array_get(['a', 'b', 'c'], fn($v) => in_array($v, ['b', 'c']), []))->isSame([1 => 'b', 2 => 'c']);

Example:

that(array_grep_key(['a' => 'A', 'aa' => 'AA', 'b' => 'B'], '#^a#'))->isSame(['a' => 'A', 'aa' => 'AA']);
that(array_grep_key(['a' => 'A', 'aa' => 'AA', 'b' => 'B'], '#^a#', true))->isSame(['b' => 'B']);

コールバックを省略すると値そのもので評価する。 コールバックに配列・文字列を与えるとキーでグループ化する。 コールバックが配列を返すと入れ子としてグループ化する。

Example:

that(array_group([1, 1, 1]))->isSame([
    1 => [1, 1, 1],
]);
that(array_group([1, 2, 3], fn($v) => $v % 2))->isSame([
    1 => [1, 3],
    0 => [2],
]);
// group -> id で入れ子グループにする
$row1 = ['id' => 1, 'group' => 'hoge'];
$row2 = ['id' => 2, 'group' => 'fuga'];
$row3 = ['id' => 3, 'group' => 'hoge'];
that(array_group([$row1, $row2, $row3], fn($row) => [$row['group'], $row['id']]))->isSame([
    'hoge' => [
        1 => $row1,
        3 => $row3,
    ],
    'fuga' => [
        2 => $row2,
    ],
]);

歴史的な理由はないが、引数をどちらの順番でも受けつけることが可能。 ただし、$glue を先に渡すパターンの場合は配列指定が可変引数渡しになる。

文字キーは保存されるが数値キーは再割り振りされる。

Example:

// (配列, 要素) の呼び出し
that(array_implode(['a', 'b', 'c'], 'X'))->isSame(['a', 'X', 'b', 'X', 'c']);
// (要素, ...配列) の呼び出し
that(array_implode('X', 'a', 'b', 'c'))->isSame(['a', 'X', 'b', 'X', 'c']);

$position を省略すると最後に挿入される（≒ array_push）。 $position に負数を与えると後ろから数えられる。 $value には配列も与えられるが、その場合数値キーは振り直される

Example:

that(array_insert([1, 2, 3], 'x'))->isSame([1, 2, 3, 'x']);
that(array_insert([1, 2, 3], 'x', 1))->isSame([1, 'x', 2, 3]);
that(array_insert([1, 2, 3], 'x', -1))->isSame([1, 2, 'x', 3]);
that(array_insert([1, 2, 3], ['a' => 'A', 'b' => 'B'], 1))->isSame([1, 'a' => 'A', 'b' => 'B', 2, 3]);

$from に対して $on を満たす $join の行を結合する。 $from,$join は共にいわゆる「配列の配列」でなければならない。

$on は各レコードが渡ってくるので、true を返せば結合、false を返せば結合されない。 $on には配列も渡すことができ、配列を渡した場合は USING 的な動作になる。

• キーが駆動表のカラム名、値が結合表のカラム名を表す
• キーの値同士を json で判定する（厳密に言えば値を json キーにした一時配列で逆引きされる）
• 複数指定時は AND になる 上記の前提・制約が許容できるなら配列指定の方が高速に動作する。

join 後のキーは各キーを "+" で連結したものになるが、このキーは暫定的なもの。

Example:

// t_article と t_comment の JOIN（のイメージ）
$articles = [
    2 => ['article_id' => 2, 'article_name' => 'hoge'],
    4 => ['article_id' => 4, 'article_name' => 'fuga'],
    5 => ['article_id' => 5, 'article_name' => 'piyo'],
];
$comments = [
    4 => ['comment_id' => 4, 'article_id' => 2, 'comment' => 'foo'],
    6 => ['comment_id' => 6, 'article_id' => 4, 'comment' => 'bar'],
    7 => ['comment_id' => 7, 'article_id' => 4, 'comment' => 'baz'],
    9 => ['comment_id' => 9, 'article_id' => 9, 'comment' => 'dmy'],
];
// INNER っぽい動き
that(array_join($articles, $comments, fn($article, $comment) => $article['article_id'] === $comment['article_id'], false))->isSame([
    '2+4' => ['article_id' => 2, 'article_name' => 'hoge', 'comment_id' => 4, 'comment' => 'foo'],
    '4+6' => ['article_id' => 4, 'article_name' => 'fuga', 'comment_id' => 6, 'comment' => 'bar'],
    '4+7' => ['article_id' => 4, 'article_name' => 'fuga', 'comment_id' => 7, 'comment' => 'baz'],
]);
// LEFT っぽい動き
that(array_join($articles, $comments, fn($article, $comment) => $article['article_id'] === $comment['article_id'], true))->isSame([
    '2+4'    => ['article_id' => 2, 'article_name' => 'hoge', 'comment_id' => 4, 'comment' => 'foo'],
    '4+6'    => ['article_id' => 4, 'article_name' => 'fuga', 'comment_id' => 6, 'comment' => 'bar'],
    '4+7'    => ['article_id' => 4, 'article_name' => 'fuga', 'comment_id' => 7, 'comment' => 'baz'],
    '5+null' => ['article_id' => 5, 'article_name' => 'piyo', 'comment_id' => null, 'comment' => null],
]);
// ↑のような単純比較クロージャなら配列でも指定できる（そしてこの方がはるかに速い）
that(array_join($articles, $comments, ['article_id' => 'article_id'], false))->isSame([
    '2+4' => ['article_id' => 2, 'article_name' => 'hoge', 'comment_id' => 4, 'comment' => 'foo'],
    '4+6' => ['article_id' => 4, 'article_name' => 'fuga', 'comment_id' => 6, 'comment' => 'bar'],
    '4+7' => ['article_id' => 4, 'article_name' => 'fuga', 'comment_id' => 7, 'comment' => 'baz'],
]);

指定キーが全て存在するなら true を返す。 配列ではなく単一文字列を与えても動作する（array_key_exists と全く同じ動作になる）。

$keys に空を与えると例外を投げる。 $keys に配列を与えるとキーで潜ってチェックする（Example 参照）。

Example:

// すべて含むので true
that(array_keys_exist(['a', 'b', 'c'], ['a' => 'A', 'b' => 'B', 'c' => 'C']))->isTrue();
// N は含まないので false
that(array_keys_exist(['a', 'b', 'N'], ['a' => 'A', 'b' => 'B', 'c' => 'C']))->isFalse();
// 配列を与えると潜る（日本語で言えば「a というキーと、x というキーとその中に x1, x2 というキーがあるか？」）
that(array_keys_exist(['a', 'x' => ['x1', 'x2']], ['a' => 'A', 'x' => ['x1' => 'X1', 'x2' => 'X2']]))->isTrue();

$callback は (キー, 値, $callback) が渡ってくるので 「その位置に配置したい配列」を返せばそこに置換される。 つまり、空配列を返せばそのキー・値は消えることになるし、複数の配列を返せば要素が増えることになる。 ただし、数値キーは新しく採番される。 null を返すと特別扱いで、そのキー・値をそのまま維持する。 iterable を返す必要があるが、もし iterable でない場合は配列キャストされる。

「map も filter も可能でキー変更可能」というとてもマッチョな関数。 実質的には「数値キーが再採番される再帰的でない array_convert」のように振る舞う。 ただし、再帰処理はないので自前で管理する必要がある。

Example:

$array = [
   'a' => 'A',
   'b' => 'B',
   'c' => 'C',
   'd' => 'D',
];
// キーに '_' 、値に 'prefix-' を付与。'b' は一切何もしない。'c' は値のみ。'd' はそれ自体伏せる
that(array_kvmap($array, function ($k, $v) {
    if ($k === 'b') return null;
    if ($k === 'd') return [];
    if ($k !== 'c') $k = "_$k";
    return [$k => "prefix-$v"];
}))->isSame([
    '_a' => 'prefix-A',
    'b'  => 'B',
    'c'  => 'prefix-C',
]);

// 複数返せばその分増える（要素の水増し）
that(array_kvmap($array, fn($k, $v) => [
    "{$k}1" => "{$v}1",
    "{$k}2" => "{$v}2",
]))->isSame([
   'a1' => 'A1',
   'a2' => 'A2',
   'b1' => 'B1',
   'b2' => 'B2',
   'c1' => 'C1',
   'c2' => 'C2',
   'd1' => 'D1',
   'd2' => 'D2',
]);

// $callback には $callback 自体も渡ってくるので再帰も比較的楽に書ける
that(array_kvmap([
    'x' => [
        'X',
        'y' => [
            'Y',
            'z' => ['Z'],
        ],
    ],
], function ($k, $v, $callback) {
    // 配列だったら再帰する
    return ["_$k" => is_array($v) ? array_kvmap($v, $callback) : "prefix-$v"];
}))->isSame([
    "_x" => [
        "_0" => "prefix-X",
        "_y" => [
            "_0" => "prefix-Y",
            "_z" => [
                "_0" => "prefix-Z",
            ],
        ],
    ],
]);

「配列の上から/下からN件取りたい」というユースケースがそれなりに多いが、毎回迷う上に1文で書けないので関数化した。

$limit が負数の場合は戻って読む。 $offset 省略時は $limit の符号で自動で先頭か末尾になる。 $offset を指定することは少なく、端的に言えば「$limit が整数なら先頭から、負数なら末尾から $limit 件返す」と考えてもよい。 配列を無限数直線にマッピングし、位置範囲指定で切り取るイメージ。 文章で書くと複雑なので Example を参照。

また、「array_slice しても結果が変わらないケース」でコールせずに結果を返すようにしてある。 （結果が変わらなくても無駄に呼ばれて速度低下があるため）。 例えば array_slice($array, 0, 0) は必ず空配列を返すし array_slice($array, 0, null) は必ず元の配列を返すはず。 にも関わらず array_slice は愚直に切り取り処理をしているようで、その分岐の有る無しで速度がだいぶ違う。

$preserve_keys は array_slice と同じだが、 null を渡すと「通常配列時に true, 連想配列時に false」が動的に決まるようになる。 ユースケースとしてはそのような使い方が多いはず。 あくまで null 指定の場合のみなのでこの動作が嫌なら明示的に bool を渡せばよい。

Example:

$array = ['a', 'b', 'c', 'd', 'e'];

that(array_limit($array, 3))->isSame(['a', 'b', 'c']);     // シンプルに先頭から3件
that(array_limit($array, -3))->isSame(['c', 'd', 'e']);    // シンプルに末尾から3件

that(array_limit($array, 3, 1))->isSame(['b', 'c', 'd']);  // 1番目（'b'）から正順に3件
that(array_limit($array, -3, 1))->isSame(['a', 'b']);      // 1番目（'b'）から逆順に3件（足りないので結果は2件）

that(array_limit($array, 3, 3))->isSame(['d', 'e']);       // 3番目（'d'）から正順に3件（足りないので結果は2件）
that(array_limit($array, -3, 3))->isSame(['b', 'c', 'd']); // 3番目（'d'）から逆順に3件

that(array_limit($array, 3, -2))->isSame(['a']);           // -2番目（範囲外）から正順に3件（'a'だけがギリギリ範囲に入る）
that(array_limit($array, -3, 6))->isSame(['e']);           // 6番目（範囲外）から逆順に3件（'e'だけがギリギリ範囲に入る）

that(array_limit($array, 3, -100))->isSame([]);            // -100番目（範囲外）から正順に3件（完全に範囲外なので空）
that(array_limit($array, -3, 100))->isSame([]);            // 100番目（範囲外）から逆順に3件（完全に範囲外なので空）

array_column は キーを保存することが出来ないが、この関数は引数を2つだけ与えるとキーはそのままで array_column 相当の配列を返す。 逆に第3引数にクロージャを与えるとその結果をキーにすることが出来る。

$column_key に配列を与えるとそれだけの配列を返す。

Example:

$array = [
    11 => ['id' => 1, 'name' => 'name1', 'status' => true],
    12 => ['id' => 2, 'name' => 'name2', 'status' => false],
    13 => ['id' => 3, 'name' => 'name3', 'status' => true],
];
// 第3引数を渡せば array_column と全く同じ
that(array_lookup($array, 'name', 'id'))->isSame(array_column($array, 'name', 'id'));
that(array_lookup($array, 'name', null))->isSame(array_column($array, 'name', null));
// 省略すればキーが保存される
that(array_lookup($array, 'name'))->isSame([
    11 => 'name1',
    12 => 'name2',
    13 => 'name3',
]);
// クロージャを指定すればキーが生成される
that(array_lookup($array, 'name', fn($v, $k) => $k * 2))->isSame([
    22 => 'name1',
    24 => 'name2',
    26 => 'name3',
]);
// $column_key に配列を与えるとそれだけの配列を返す
that(array_lookup($array, ['id', 'status']))->isSame([
    11 => ['id' => 1, 'status' => true],
    12 => ['id' => 2, 'status' => false],
    13 => ['id' => 3, 'status' => true],
]);

コールバックを適用して、結果が true 相当の要素のみ取り出す。 $strict に true を与えると「null でない」要素のみ返される。

$callback が要求するならキーも渡ってくる。

Example:

that(array_map_filter([' a ', ' b ', ''], 'trim'))->isSame(['a', 'b']);
that(array_map_filter([' a ', ' b ', ''], 'trim', true))->isSame(['a', 'b', '']);

$callback が null を返すとその要素は取り除かれる。

Example:

that(array_map_key(['a' => 'A', 'b' => 'B'], 'strtoupper'))->isSame(['A' => 'A', 'B' => 'B']);
that(array_map_key(['a' => 'A', 'b' => 'B'], function () { }))->isSame([]);

下記の点で少し array_map とは挙動が異なる。

• 配列だけでなく iterable も対象になる（引数で指定可能。デフォルト true）
  • つまりオブジェクト構造は維持されず、結果はすべて配列になる
• 値だけでなくキーも渡ってくる

Example:

// デフォルトでは array_walk 等と同様に葉のみが渡ってくる（iterable も対象になる）
that(array_map_recursive([
    'k' => 'v',
    'c' => new \ArrayObject([
        'k1' => 'v1',
        'k2' => 'v2',
    ]),
], 'strtoupper'))->isSame([
    'k' => 'V',
    'c' => [
        'k1' => 'V1',
        'k2' => 'V2',
    ],
]);

// ただし、その挙動は引数で変更可能
that(array_map_recursive([
    'k' => 'v',
    'c' => new \ArrayObject([
        'k1' => 'v1',
        'k2' => 'v2',
    ]),
], 'gettype', false))->isSame([
    'k' => 'string',
    'c' => 'object',
]);

// さらに、自身にも適用できる（呼び出しは子が先で、本当の意味で「すべての要素」で呼び出される）
that(array_map_recursive([
    'k' => 'v',
    'c' => [
        'k1' => 'v1',
        'k2' => 'v2',
    ],
], function ($v) {
    // 配列は stdclass 化、それ以外は大文字化
    return is_array($v) ? (object) $v : strtoupper($v);
}, true, true))->is((object) [
    'k' => 'V',
    'c' => (object) [
        'k1' => 'V1',
        'k2' => 'V2',
    ],
]);

指定したコールバックで複数回回してマップする。 array_maps($array, $f, $g) は array_map($g, array_map($f, $array)) とほぼ等しい。 ただし、引数は順番が違う（可変引数のため）し、コールバックが要求するならキーも渡ってくる。 さらに文字列関数で "..." から始まっているなら可変引数としてコールする。

少し変わった仕様として、コールバックに [$method => $args] を付けるとそれはメソッド呼び出しになる。 つまり各要素 $v に対して $v->$method(...$args) がマップ結果になる。 さらに引数が不要なら @method とするだけで良い。

Example:

// 値を3乗したあと16進表記にして大文字化する
that(array_maps([1, 2, 3, 4, 5], fn($v) => pow($v, 3), 'dechex', 'strtoupper'))->isSame(['1', '8', '1B', '40', '7D']);
// キーも渡ってくる
that(array_maps(['a' => 'A', 'b' => 'B'], fn($v, $k) => "$k:$v"))->isSame(['a' => 'a:A', 'b' => 'b:B']);
// ... で可変引数コール
that(array_maps([[1, 3], [1, 5, 2]], '...range'))->isSame([[1, 2, 3], [1, 3, 5]]);
// メソッドコールもできる（引数不要なら `@method` でも同じ）
that(array_maps([new \Exception('a'), new \Exception('b')], ['getMessage' => []]))->isSame(['a', 'b']);
that(array_maps([new \Exception('a'), new \Exception('b')], '@getMessage'))->isSame(['a', 'b']);

キー・値が維持される点で array_merge とは異なる（振り直しをせず数値配列で返す）。 きちんと0からの連番で構成される点で配列の加算とは異なる。 要するに「できるだけキーが自然数（の並び）になるように」マージする。

歯抜けはそのまま維持され、文字キーは後ろに追加される（負数キーも同様）。

Example:

// キーが入り乱れているがよく見ると通し番号が振られている配列をマージ
that(array_merge2([4 => 4, 1 => 1], [0 => 0], [5 => 5, 2 => 2, 3 => 3]))->isSame([0, 1, 2, 3, 4, 5]);
// 歯抜けの配列をマージ
that(array_merge2([4 => 4, 1 => 1], [0 => 0], [5 => 5, 3 => 3]))->isSame([0, 1, 3 => 3, 4 => 4, 5 => 5]);
// 負数や文字キーは後ろに追いやられる
that(array_merge2(['a' => 'A', 1 => 1], [0 => 0], [-1 => 'X', 2 => 2, 3 => 3]))->isSame([0, 1, 2, 3, -1 => 'X', 'a' => 'A']);
// 同じキーは後ろ優先
that(array_merge2([0, 'a' => 'A0'], [1, 'a' => 'A1'], [2, 'a' => 'A2']))->isSame([2, 'a' => 'A2']);

引数の配列を横断的に追加して返す。 数値キーは振り直される。文字キーはそのまま追加される（同じキーは後方上書き）。

配列の長さが異なる場合、短い方に対しては何もしない。そのまま追加される。

Example:

// 奇数配列と偶数配列をミックスして自然数配列を生成
that(array_mix([1, 3, 5], [2, 4, 6]))->isSame([1, 2, 3, 4, 5, 6]);
// 長さが異なる場合はそのまま追加される（短い方の足りない分は無視される）
that(array_mix([1], [2, 3, 4]))->isSame([1, 2, 3, 4]);
that(array_mix([1, 3, 4], [2]))->isSame([1, 2, 3, 4]);
// 可変引数なので3配列以上も可
that(array_mix([1], [2, 4], [3, 5, 6]))->isSame([1, 2, 3, 4, 5, 6]);
that(array_mix([1, 4, 6], [2, 5], [3]))->isSame([1, 2, 3, 4, 5, 6]);
// 文字キーは維持される
that(array_mix(['a' => 'A', 1, 3], ['b' => 'B', 2]))->isSame(['a' => 'A', 'b' => 'B', 1, 2, 3]);

定義的に array_flatten の逆関数のような扱いになる。 $delimiter で階層を表現する。

同名とみなされるキーは上書きされるか例外が飛ぶ。具体的には Example を参照。

Example:

// 単純な階層展開
$array = [
   'k1'            => 'v1',
   'k2.k21'        => 'v21',
   'k2.k22.k221'   => 'v221',
   'k2.k22.k222'   => 'v222',
   'k2.k22.k223.0' => 1,
   'k2.k22.k223.1' => 2,
   'k2.k22.k223.2' => 3,
];
that(array_nest($array))->isSame([
   'k1' => 'v1',
   'k2' => [
       'k21' => 'v21',
       'k22' => [
           'k221' => 'v221',
           'k222' => 'v222',
           'k223' => [1, 2, 3],
       ],
   ],
]);
// 同名になるようなキーは上書きされる
$array = [
   'k1.k2' => 'v1', // この時点で 'k1' は配列になるが・・・
   'k1'    => 'v2', // この時点で 'k1' は文字列として上書きされる
];
that(array_nest($array))->isSame([
   'k1' => 'v2',
]);
// 上書きすら出来ない場合は例外が飛ぶ
$array = [
   'k1'    => 'v1', // この時点で 'k1' は文字列になるが・・・
   'k1.k2' => 'v2', // この時点で 'k1' にインデックスアクセスすることになるので例外が飛ぶ
];
try {
    array_nest($array);
}
catch (\Exception $e) {
    that($e)->isInstanceOf(\InvalidArgumentException::class);
}

存在しない場合は $default を返す。

$key に配列を与えるとそれらの値の配列を返す（lookup 的な動作）。 その場合、$default が活きるのは「全て無かった場合」となる。 さらに $key が配列の場合に限り、 $default を省略すると空配列として動作する。

Example:

$fuga_of_array = array_of('fuga');
that($fuga_of_array(['hoge' => 'HOGE', 'fuga' => 'FUGA']))->isSame('FUGA');

$callback が要求するならキーも渡ってくる。

Example:

that(array_or([true, true]))->isTrue();
that(array_or([true, false]))->isTrue();
that(array_or([false, false]))->isFalse();

データベースからフェッチしたような連想配列の配列を想定しているが、スカラー配列(['key' => 'value'])にも対応している。 その場合 $orders に配列ではなく直値を渡せば良い。

$orders には下記のような配列を渡す。 キーに空文字を渡すとそれは「キー自体」を意味する。

$orders = [
    'col1' => true,                              // true: 昇順, false: 降順。照合は型に依存
    'col2' => SORT_NATURAL,                      // SORT_NATURAL, SORT_REGULAR などで照合。正数で昇順、負数で降順
    'col3' => ['sort', 'this', 'order'],         // 指定した配列順で昇順
    'col4' => fn($v) => $v,                      // 引数1個: クロージャを通した値で昇順。照合は返り値の型に依存
    // 'col4' => fn($v, $o = SORT_DESC) => $v,   // ↑の亜種（第2引数のデフォルト値がオーダーを表す）
    'col5' => fn($av, $bv) => $av - $bv,         // 引数2個: クロージャで比較して値昇順（いわゆる比較関数を渡す）
    'col6' => fn($ak, $bk, $array) => $ak - $bk, // 引数3個: クロージャで比較してキー昇順（いわゆる比較関数を渡す）
];

Example:

$v1 = ['id' => '1', 'no' => 'a03', 'name' => 'yyy'];
$v2 = ['id' => '2', 'no' => 'a4',  'name' => 'yyy'];
$v3 = ['id' => '3', 'no' => 'a12', 'name' => 'xxx'];
// name 昇順, no 自然降順
that(array_order([$v1, $v2, $v3], ['name' => true, 'no' => -SORT_NATURAL]))->isSame([$v3, $v2, $v1]);

array_intersect_key($array, array_flip($keys)) とほぼ同義。 違いは Traversable を渡せることと、結果配列の順番が $keys に従うこと。

$keys に連想配列を渡すとキーを読み替えて動作する（Example を参照）。 さらにその時クロージャを渡すと($key, $value)でコールされた結果が新しいキーになる。

Example:

$array = ['a' => 'A', 'b' => 'B', 'c' => 'C'];
// a と c を取り出す
that(array_pickup($array, ['a', 'c']))->isSame(['a' => 'A', 'c' => 'C']);
// 順番は $keys 基準になる
that(array_pickup($array, ['c', 'a']))->isSame(['c' => 'C', 'a' => 'A']);
// 連想配列を渡すと読み替えて返す
that(array_pickup($array, ['c' => 'cX', 'a' => 'aX']))->isSame(['cX' => 'C', 'aX' => 'A']);
// コールバックを渡せる
that(array_pickup($array, ['c' => fn($k, $v) => "$k-$v"]))->isSame(['c-C' => 'C']);

負数を与えると逆から N 番目となる。

Example:

that(array_pos([1, 2, 3], 1))->isSame(2);
that(array_pos([1, 2, 3], -1))->isSame(3);
that(array_pos(['a' => 'A', 'b' => 'B', 'c' => 'C'], 1))->isSame('B');
that(array_pos(['a' => 'A', 'b' => 'B', 'c' => 'C'], 1, true))->isSame('b');

$key に配列を与えるとその全ての位置を返す。

Example:

that(array_pos_key(['a' => 'A', 'b' => 'B', 'c' => 'C'], 'c'))->isSame(2);
that(array_pos_key(['a' => 'A', 'b' => 'B', 'c' => 'C'], 'x', -1))->isSame(-1);
 that(array_pos_key(['a' => 'A', 'b' => 'B', 'c' => 'C'], ['a', 'c']))->isSame(['a' => 0, 'c' => 2]);

array_unshift のキーが指定できる参照渡しでない版と言える。 配列の数値キーは振り直される。 キー指定でかつそのキーが存在するとき、値を変えつつ先頭に移動する動作となる。

Example:

// キー未指定は0で挿入される
that(array_prepend([1, 2, 3], 99))->is([99, 1, 2, 3]);
// キーを指定すればそのキーで生える
that(array_prepend([1, 2, 3], 99, 'newkey'))->is(['newkey' => 99, 1, 2, 3]);
// 存在する場合は値が変わって先頭に移動する
that(array_prepend([1, 2, 3], 99, 1))->is([1 => 99, 0 => 1, 2 => 3]);

とはいえ多少の差異がある。

• 第2引数に null を与えると単一の値として返す
• 第2引数に数値を与えると配列で返す（たとえ1でも配列で返す）
• 第2引数に 0 を与えてもエラーにはならない（空配列を返す）
• 第2引数に負数を与えるとその個数に満たなくても例外にならない
• 第3引数に true を与えるとキーを維持して返す

Example:

mt_srand(4); // テストがコケるので種固定
// 配列からランダムに値1件取得（単一で返す）
that(array_random(['a' => 'A', 'b' => 'B', 'c' => 'C']))->isSame('B');
// 配列からランダムに値2件取得（配列で返す）
that(array_random(['a' => 'A', 'b' => 'B', 'c' => 'C'], 2))->isSame(['B', 'C']);
// 配列からランダムに値2件取得（キーを維持）
that(array_random(['a' => 'A', 'b' => 'B', 'c' => 'C'], 2, true))->isSame(['a' => 'A', 'c' => 'C']);
// 配列からランダムに値N件取得（負数指定。配列数を超えた指定は例外になるので負数にする必要がある）
that(array_random(['a' => 'A', 'b' => 'B', 'c' => 'C'], -999, true))->isSame(['a' => 'A', 'b' => 'B', 'c' => 'C']);

• 文字列に対応
• 日時に対応
• $start, $end から $step の自動算出
• $start < $end で $step < 0 の場合、空配列を返す
• $start > $end で $step > 0 の場合、空配列を返す

逆に言うと $start, $end の大小を意識しないと正しい値は返らないことになる。 標準 range の下記の挙動が個人的に違和感があるので実装した。

• range(1, 3, -1); // [1, 2, 3]
• range(3, 1, +1); // [3, 2, 1]

Example:

// 文字列（具体的にはデクリメント）
that(array_range('a', 'c', +1))->isSame(['a', 'b', 'c']);
that(array_range('c', 'a', -1))->isSame(['c', 'b', 'a']);

// 日時
that(array_range('2014/12/24 12:34:56', '2014/12/26 12:34:56', 'P1D', ['format' => 'Y/m/d H:i:s']))->isSame([
    '2014/12/24 12:34:56',
    '2014/12/25 12:34:56',
    '2014/12/26 12:34:56',
]);
that(array_range('2014/12/26 12:34:56', '2014/12/24 12:34:56', 'P-1D', ['format' => 'Y/m/d H:i:s']))->isSame([
    '2014/12/26 12:34:56',
    '2014/12/25 12:34:56',
    '2014/12/24 12:34:56',
]);

// step は省略可能（+/-1 になる）
that(array_range(1, 3))->isSame([1, 2, 3]);
that(array_range(3, 1))->isSame([3, 2, 1]);
that(array_range('a', 'c'))->isSame(['a', 'b', 'c']);
that(array_range('c', 'a'))->isSame(['c', 'b', 'a']);

// 範囲外は空配列を返す
that(array_range(1, 3, -1))->isSame([]);
that(array_range(3, 1, +1))->isSame([]);
that(array_range('a', 'c', -1))->isSame([]);
that(array_range('c', 'a', +1))->isSame([]);
that(array_range('2014/12/24', '2014/12/27', 'P-1D'))->isSame([]);
that(array_range('2014/12/27', '2014/12/24', 'P1D'))->isSame([]);

同ランクはすべて返す。 つまり $length=10 でも10件以上を返すこともある。

$length が負数の場合、降順ソートして後ろから取り出す。 端的に言えば

正数

下位N件

負数

上位N件

という動作になる。

ソートの型は最初の要素で決まる。 文字列なら SORT_STRING で、違うなら SORT_NUMERIC

変換先・返り値が null だとその要素は取り除かれる。 callable 指定時の引数は (キー, 値, 連番インデックス, 対象配列そのもの) が渡ってくる。

Example:

$array = ['a' => 'A', 'b' => 'B', 'c' => 'C'];
// a は x に c は z に置換される
that(array_rekey($array, ['a' => 'x', 'c' => 'z']))->isSame(['x' => 'A', 'b' => 'B', 'z' => 'C']);
// b は削除され c は z に置換される
that(array_rekey($array, ['b' => null, 'c' => 'z']))->isSame(['a' => 'A', 'z' => 'C']);
// キーの交換にも使える（a ⇔ c）
that(array_rekey($array, ['a' => 'c', 'c' => 'a']))->isSame(['c' => 'A', 'b' => 'B', 'a' => 'C']);
// callable
that(array_rekey($array, 'strtoupper'))->isSame(['A' => 'A', 'B' => 'B', 'C' => 'C']);

array_diff_key($array, array_flip($keys)) とほぼ同義。 違いは Traversable を渡せること。

array_pickup の逆とも言える。

Example:

$array = ['a' => 'A', 'b' => 'B', 'c' => 'C'];
// a と c を伏せる（b を残す）
that(array_remove($array, ['a', 'c']))->isSame(['b' => 'B']);

$map の当該キー要素が・・・

クロージャの場合

キーの有無に関わらずコールされる

null の場合

キーが削除される

それ以外の場合

キーが追加される（存在しない場合のみ）

という処理を行う。

Example:

that(array_revise([
    'id'      => 123,
    'name'    => 'hoge',
    'age'     => 18,
    'delete'  => '',
], [
    'name'    => 'ignored',            // 存在するのでスルーされる
    'append'  => 'newkey',             // 存在しないので追加される
    'age'     => fn($age) => $age + 1, // クロージャは現在の値を引数にしてコールされる
    'delete'  => null,                 // null は削除される
    'null'    => fn() => null,         // 削除の目印として null を使っているので null を追加したい場合はクロージャで包む必要がある
]))->isSame([
    'id'      => 123,
    'name'    => 'hoge',
    'age'     => 19,
    'append'  => 'newkey',
    'null'    => null,
]);

type

値の型を指定する

is_XXX の XXX 部分

左記で検証

number

is_int or is_float で検証

class 名

instanceof で検証

list

値がマージされて通常配列になる

• list@string のようにすると配列の中身の型を指定できる

hash

連想配列になる

string|int

string or int

['string', 'int']

上と同じ

closure

指定クロージャで検証・フィルタ

all

値を引数に取り、返り値が新しい値となる

unique

重複を除去する

list

重複除去（パラメータがソートアルゴリズムになる）

enum

値が指定値のいずれかであるか検証する

all

in_array で検証する

min

値が指定値以上であるか検証する

string

strlen で検証

list

count で検証

all

その値で検証

max

値が指定値以下であるか検証する

• min の逆

match

値が正規表現にマッチするか検証する

all

preg_match で検証する

unmatch

値が正規表現にマッチしないか検証する

• match の逆

include

値が指定値を含むか検証する

string

strpos で検証

list

in_array で検証

exclude

値が指定値を含まないか検証する

• include の逆

検証・フィルタは原則として型を見ない（指定されていればすべて実行される）。 のでおかしな型におかしな検証・フィルタを与えると型エラーが出ることがある。

検証は途中経過を問わない。 後ろの配列で上書きされた値や unique で減った配列などは以下に違反していても valid と判断される。

素直に json schema を使えという内なる声が聞こえなくもない。

$columns に単純な値を渡すとそのキーの値を選択する。 キー付きで値を渡すと読み替えて選択する。 キー付きでクロージャを渡すと (キーの値, 行自体, 現在行のキー) を引数としてコールバックして選択する。 単一のクロージャを渡すと (行自体, 現在行のキー) を引数としてコールバックして選択する（array_map とほぼ同じ）。

Example:

$array = [
    11 => ['id' => 1, 'name' => 'name1'],
    12 => ['id' => 2, 'name' => 'name2'],
    13 => ['id' => 3, 'name' => 'name3'],
];

that(array_select($array, [
    'id',              // id を単純取得
    'alias' => 'name', // name を alias として取得
]))->isSame([
    11 => ['id' => 1, 'alias' => 'name1'],
    12 => ['id' => 2, 'alias' => 'name2'],
    13 => ['id' => 3, 'alias' => 'name3'],
]);

that(array_select($array, [
    // id の 10 倍を取得
    'id'     => fn($id) => $id * 10,
    // id と name の結合を取得
    'idname' => fn($null, $row, $index) => $row['id'] . $row['name'],
]))->isSame([
    11 => ['id' => 10, 'idname' => '1name1'],
    12 => ['id' => 20, 'idname' => '2name2'],
    13 => ['id' => 30, 'idname' => '3name3'],
]);

第3引数を省略すると（null を与えると）言語機構を使用して配列の最後に設定する（$array[] = $value）。 第3引数に配列を指定すると潜って設定する。

第4引数で追加する条件クロージャを指定できる。 クロージャには (追加する要素, 追加するキー, 追加される元配列) が渡ってくる。 このクロージャが false 相当を返した時は追加されないようになる。

Example:

$array = ['a' => 'A', 'B'];
// 第3引数省略（最後に連番キーで設定）
that(array_set($array, 'Z'))->isSame(1);
that($array)->isSame(['a' => 'A', 'B', 'Z']);
// 第3引数でキーを指定
that(array_set($array, 'Z', 'z'))->isSame('z');
that($array)->isSame(['a' => 'A', 'B', 'Z', 'z' => 'Z']);
that(array_set($array, 'Z', 'z'))->isSame('z');
// 第3引数で配列を指定
that(array_set($array, 'Z', ['x', 'y', 'z']))->isSame('z');
that($array)->isSame(['a' => 'A', 'B', 'Z', 'z' => 'Z', 'x' => ['y' => ['z' => 'Z']]]);
// 第4引数で条件を指定（キーが存在するなら追加しない）
that(array_set($array, 'Z', 'z', fn($v, $k, $array) => !isset($array[$k])))->isSame(null);
// 第4引数で条件を指定（値が存在するなら追加しない）
that(array_set($array, 'Z', null, fn($v, $k, $array) => !in_array($v, $array)))->isSame(null);

array_intersect_key は「左優先で共通項を取る」という動作だが、この関数は「右優先で共通項を取る」という動作になる。 「配列の並び順はそのままで値だけ変えたい/削ぎ落としたい」という状況はまれによくあるはず。

Example:

$array1 = ['a' => 'A1', 'b' => 'B1', 'c' => 'C1'];
$array2 = ['c' => 'C2', 'b' => 'B2', 'a' => 'A2'];
$array3 = ['c' => 'C3', 'dummy' => 'DUMMY'];
// 全共通項である 'c' キーのみが生き残り、その値は最後の 'C3' になる
that(array_shrink_key($array1, $array2, $array3))->isSame(['c' => 'C3']);

Example:

that(array_shuffle(['a' => 'A', 'b' => 'B', 'c' => 'C']))->is(['b' => 'B', 'a' => 'A', 'c' => 'C']);

配列の各要素を文字列化して返すイメージ。 $glue を与えるとさらに implode して返す（返り値が文字列になる）。

$format は書式文字列（$v, $k）。 callable を与えると sprintf ではなくコールバック処理になる（$v, $k）。 省略（null）するとキーを format 文字列、値を引数として vsprintf する。

Example:

$array = ['key1' => 'val1', 'key2' => 'val2'];
// key, value を利用した sprintf
that(array_sprintf($array, '%2$s=%1$s'))->isSame(['key1=val1', 'key2=val2']);
// 第3引数を与えるとさらに implode される
that(array_sprintf($array, '%2$s=%1$s', ' '))->isSame('key1=val1 key2=val2');
// クロージャを与えるとコールバック動作になる
$closure = fn($v, $k) => "$k=" . strtoupper($v);
that(array_sprintf($array, $closure, ' '))->isSame('key1=VAL1 key2=VAL2');
// 省略すると vsprintf になる
that(array_sprintf([
    'str:%s,int:%d' => ['sss', '3.14'],
    'single:%s'     => 'str',
], null, '|'))->isSame('str:sss,int:3|single:str');

$key_prefix, $val_prefix でそれぞれ「キーに付与する文字列」「値に付与する文字列」が指定できる。 配列を与えると [サフィックス, プレフィックス] という意味になる。 デフォルト（ただの文字列）はプレフィックス（値だけに付与したいなら array_map で十分なので）。

Example:

$array = ['key1' => 'val1', 'key2' => 'val2'];
// キーにプレフィックス付与
that(array_strpad($array, 'prefix-'))->isSame(['prefix-key1' => 'val1', 'prefix-key2' => 'val2']);
// 値にサフィックス付与
that(array_strpad($array, '', ['-suffix']))->isSame(['key1' => 'val1-suffix', 'key2' => 'val2-suffix']);

$template を指定すると「それに含まれる配列かつ値がデフォルト」になる（要するに $default みたいなもの）。 キーがバラバラな配列を指定する場合は指定したほうが良い。が、null を指定すると最初の要素が使われるので大抵の場合は null で良い。

Example:

that(array_uncolumns([
    'id'   => [1, 2],
    'name' => ['A', 'B'],
]))->isSame([
    ['id' => 1, 'name' => 'A'],
    ['id' => 2, 'name' => 'B'],
]);

$key に配列を与えると全て伏せて配列で返す。 その場合、$default が活きるのは「全て無かった場合」となる。

さらに $key が配列の場合に限り、 $default を省略すると空配列として動作する。

配列を与えた場合の返り値は与えた配列の順番・キーが活きる。 これを利用すると list の展開の利便性が上がったり、連想配列で返すことができる。

同様に、$key にクロージャを与えると、その返り値が true 相当のものを伏せて配列で返す。 callable ではなくクロージャのみ対応する。

Example:

$array = ['a' => 'A', 'b' => 'B'];
// ない場合は $default を返す
that(array_unset($array, 'x', 'X'))->isSame('X');
// 指定したキーを返す。そのキーは伏せられている
that(array_unset($array, 'a'))->isSame('A');
that($array)->isSame(['b' => 'B']);

$array = ['a' => 'A', 'b' => 'B', 'c' => 'C'];
// 配列を与えるとそれらを返す。そのキーは全て伏せられている
that(array_unset($array, ['a', 'b', 'x']))->isSame(['A', 'B']);
that($array)->isSame(['c' => 'C']);

$array = ['a' => 'A', 'b' => 'B', 'c' => 'C'];
// 配列のキーは返されるキーを表す。順番も維持される
that(array_unset($array, ['x2' => 'b', 'x1' => 'a']))->isSame(['x2' => 'B', 'x1' => 'A']);

$array = ['hoge' => 'HOGE', 'fuga' => 'FUGA', 'piyo' => 'PIYO'];
// 値に "G" を含むものを返す。その要素は伏せられている
that(array_unset($array, fn($v) => strpos($v, 'G') !== false))->isSame(['hoge' => 'HOGE', 'fuga' => 'FUGA']);
that($array)->isSame(['piyo' => 'PIYO']);

違いは下記。

• 第3引数はなし
  • クロージャの use で十分だしそちらの方が優れている
• コールバックは ($value, $key, $array, $keys) が渡ってくる
  • $value, $array はリファレンスにすることで書き換え可能
• 返り値で返す
  • 元の array_walk_recursive の返り値はほとんど意味がない
  • 返り値が空いてるなら変に参照を使わず返り値の方がシンプル

array_walk_recursive で「この要素は伏せたいのに…」「このノードだけ触りたいのに…」ということはままあるが、

• $array が渡ってくるので unset したり他のキーを生やしたりすることが可能
• $keys が渡ってくるのでツリー構造の特定のノードだけ触ることが可能 になっている。

「map も filter も可能」という少しマッチョな関数。 実質的には「再帰的な array_kvmap」のように振る舞う。

array_column があるなら array_where があってもいいはず。

$column はコールバックに渡ってくる配列のキー名を渡す。null を与えると行全体が渡ってくる。 $callback は絞り込み条件を渡す。null を与えると true 相当の値でフィルタする。 つまり $column も $callback も省略した場合、実質的に array_filter と同じ動作になる。

$column は配列を受け入れる。配列を渡した場合その値の共通項がコールバックに渡る。 連想配列の場合は「キーのカラム == 値」で filter する（それぞれで AND。厳密かどうかは $callback で指定。説明が難しいので Example を参照）。

$callback が要求するならキーも渡ってくる。

Example:

$array = [
    0 => ['id' => 1, 'name' => 'hoge', 'flag' => false],
    1 => ['id' => 2, 'name' => 'fuga', 'flag' => true],
    2 => ['id' => 3, 'name' => 'piyo', 'flag' => false],
];
// 'flag' が true 相当のものだけ返す
that(array_where($array, 'flag'))->isSame([
    1 => ['id' => 2, 'name' => 'fuga', 'flag' => true],
]);
// 'name' に 'h' を含むものだけ返す
$contain_h = fn($name) => strpos($name, 'h') !== false;
that(array_where($array, 'name', $contain_h))->isSame([
    0 => ['id' => 1, 'name' => 'hoge', 'flag' => false],
]);
// $callback が引数2つならキーも渡ってくる（キーが 2 のものだけ返す）
$equal_2 = fn($row, $key) => $key === 2;
that(array_where($array, null, $equal_2))->isSame([
    2 => ['id' => 3, 'name' => 'piyo', 'flag' => false],
]);
// $column に配列を渡すと共通項が渡ってくる
$idname_is_2fuga = fn($idname) => ($idname['id'] . $idname['name']) === '2fuga';
that(array_where($array, ['id', 'name'], $idname_is_2fuga))->isSame([
    1 => ['id' => 2, 'name' => 'fuga', 'flag' => true],
]);
// $column に連想配列を渡すと「キーのカラム == 値」で filter する（要するに「name が piyo かつ flag が false」で filter）
that(array_where($array, ['name' => 'piyo', 'flag' => false]))->isSame([
    2 => ['id' => 3, 'name' => 'piyo', 'flag' => false],
]);
// 上記において値に配列を渡すと in_array で判定される
that(array_where($array, ['id' => [2, 3]]))->isSame([
    1 => ['id' => 2, 'name' => 'fuga', 'flag' => true],
    2 => ['id' => 3, 'name' => 'piyo', 'flag' => false],
]);
// $column の連想配列の値にはコールバックが渡せる（それぞれで AND）
that(array_where($array, [
    'id'   => fn($id) => $id >= 3,                       // id が 3 以上
    'name' => fn($name) => strpos($name, 'o') !== false, // name に o を含む
]))->isSame([
    2 => ['id' => 3, 'name' => 'piyo', 'flag' => false],
]);

array_map(null, ...$arrays) とほぼ同義。ただし

• 文字キーは保存される（数値キーは再割り振りされる）
• 一つだけ配列を与えても構造は壊れない（array_map(null) は壊れる）

Example:

// 普通の zip
that(array_zip(
    [1, 2, 3],
    ['hoge', 'fuga', 'piyo']
))->is([[1, 'hoge'], [2, 'fuga'], [3, 'piyo']]);
// キーが維持される
that(array_zip(
    ['a' => 1, 2, 3],
    ['hoge', 'b' => 'fuga', 'piyo']
))->is([['a' => 1, 'hoge'], [2, 'b' => 'fuga'], [3, 'piyo']]);

配列以外を渡すと配列化されて追加される。 配列を渡してもそのままだが、連番配列の場合はマージ、連想配列の場合は結合となる。 iterable や Traversable は考慮せずあくまで「配列」としてチェックする。

Example:

// 値は配列化される
that(arrayize(1, 2, 3))->isSame([1, 2, 3]);
// 配列はそのまま
that(arrayize([1], [2], [3]))->isSame([1, 2, 3]);
// 連想配列、連番配列の挙動
that(arrayize([1, 2, 3], [4, 5, 6], ['a' => 'A1'], ['a' => 'A2']))->isSame([1, 2, 3, 4, 5, 6, 'a' => 'A1']);
// stdClass は foreach 可能だがあくまで配列としてチェックする
$object = new \stdClass();
that(arrayize($object, false, [1, 2, 3]))->isSame([$object, false, 1, 2, 3]);

「シーケンシャルに」とは要するに数値連番が得られるように走査するということ。 0ベースの連番を作ってインクリメントしながら foreach するのと全く変わらない。

キーは連番、値は [$key, $value] で返す。 つまり、 Example のように foreach の list 構文を使えば「連番、キー、値」でループを回すことが可能になる。 「foreach で回したいんだけど連番も欲しい」という状況はまれによくあるはず。

Example:

$array = ['a' => 'A', 'b' => 'B', 'c' => 'C'];
$nkv = [];
foreach (arrays($array) as $n => [$k, $v]) {
    $nkv[] = "$n,$k,$v";
}
that($nkv)->isSame(['0,a,A', '1,b,B', '2,c,C']);

空の場合は $default を返す。

Example:

that(first_key(['a', 'b', 'c']))->isSame(0);
that(first_key([], 999))->isSame(999);

空の場合は $default を返す。

Example:

that(first_keyvalue(['a', 'b', 'c']))->isSame([0, 'a']);
that(first_keyvalue([], 999))->isSame(999);

空の場合は $default を返す。

Example:

that(first_value(['a', 'b', 'c']))->isSame('a');
that(first_value([], 999))->isSame(999);

$grouper でグルーピングされた部分配列を $comparator でソートし、元の位置に埋め込む。 元の配列の並び順は可能な限り維持される。

$grouper はグループを決定づける何かを返す。 一意であれば何でも良いが、内部的に配列のキーに格納されるため、文字列であることが望ましい。

Example:

// 下記のような配列を元の順番を保ちつつ各々の group で部分的にソートする
$array = [
    ['id' => 1, 'group' => 'A', 'name' => 'q'],
    ['id' => 2, 'group' => 'A', 'name' => 'a'],
    ['id' => 3, 'group' => 'A', 'name' => 'z'],
    ['id' => 4, 'group' => null, 'name' => 'noise'],
    ['id' => 5, 'group' => 'B', 'name' => 'w'],
    ['id' => 6, 'group' => 'B', 'name' => 's'],
    ['id' => 7, 'group' => 'B', 'name' => 'x'],
    ['id' => 8, 'group' => 'C', 'name' => 'e'],
    ['id' => 9, 'group' => 'C', 'name' => 'd'],
    ['id' => 10, 'group' => null, 'name' => 'noise'],
    ['id' => 11, 'group' => 'C', 'name' => 'c'],
];
that(groupsort($array, fn($v, $k) => $v['group'], fn($a, $b) => $a['name'] <=> $b['name']))->is([
    1  => ["id" => 2, "group" => "A", "name" => "a"],
    0  => ["id" => 1, "group" => "A", "name" => "q"],
    2  => ["id" => 3, "group" => "A", "name" => "z"],
    3  => ["id" => 4, "group" => null, "name" => "noise"],
    5  => ["id" => 6, "group" => "B", "name" => "s"],
    4  => ["id" => 5, "group" => "B", "name" => "w"],
    6  => ["id" => 7, "group" => "B", "name" => "x"],
    10 => ["id" => 11, "group" => "C", "name" => "c"],
    8  => ["id" => 9, "group" => "C", "name" => "d"],
    7  => ["id" => 8, "group" => "C", "name" => "e"],
    9  => ["id" => 10, "group" => null, "name" => "noise"],
]);

配列 $haystack が $needle の「すべてを含む」ときに true を返す。

$needle が非配列の場合は配列化される。 $needle が空の場合は常に false を返す。

Example:

that(in_array_and([1], [1, 2, 3]))->isTrue();
that(in_array_and([9], [1, 2, 3]))->isFalse();
that(in_array_and([1, 9], [1, 2, 3]))->isFalse();

配列 $haystack が $needle の「どれかを含む」ときに true を返す。

$needle が非配列の場合は配列化される。 $needle が空の場合は常に false を返す。

Example:

that(in_array_or([1], [1, 2, 3]))->isTrue();
that(in_array_or([9], [1, 2, 3]))->isFalse();
that(in_array_or([1, 9], [1, 2, 3]))->isTrue();

空の配列は普通の配列とみなす。

Example:

that(is_hasharray([]))->isFalse();
that(is_hasharray([1, 2, 3]))->isFalse();
that(is_hasharray(['x' => 'X']))->isTrue();

空の配列も数値配列とみなす。 さらにいわゆる「連番配列」ではなく「キーが数値のみか？」で判定する。

つまり、 is_hasharray とは排他的ではない。

Example:

that(is_indexarray([]))->isTrue();
that(is_indexarray([1, 2, 3]))->isTrue();
that(is_indexarray(['x' => 'X']))->isFalse();
// 抜け番があっても true になる（これは is_hasharray も true になる）
that(is_indexarray([1 => 1, 2 => 2, 3 => 3]))->isTrue();

比較関数は ($valueA, $valueB, $keyA, $keyB) という引数を取る。 「値で比較して同値だったらキーも見たい」という状況はまれによくあるはず。 さらに安定ソートであり、同値だとしても元の並び順は維持される。

$schwartzians を指定した場合は呼び出しが ($schwartzianA, $schwartzianB, $valueA, $valueB, $keyA, $keyB) になる。 $schwartzianX は単一値の場合はその結果、配列の場合はキー構造が維持されて渡ってくる。 このあたりは表現しにくいので Example を参照。

$comparator は省略できる。省略した場合、型に基づいてよしなにソートする。 （が、比較のたびに型チェックが入るので指定したほうが高速に動く）。

ただし、標準のソート関数とは異なり、参照渡しではなくソートして返り値で返す。 また、いわゆる asort であり、キー・値は常に維持される。

Example:

$array = [
    'a'  => 3,
    'b'  => 1,
    'c'  => 2,
    'x1' => 9,
    'x2' => 9,
    'x3' => 9,
];
// 普通のソート
that(kvsort($array))->isSame([
    'b'  => 1,
    'c'  => 2,
    'a'  => 3,
    'x1' => 9,
    'x2' => 9,
    'x3' => 9,
]);
// キーを使用したソート
that(kvsort($array, fn($av, $bv, $ak, $bk) => strcmp($bk, $ak)))->isSame([
    'x3' => 9,
    'x2' => 9,
    'x1' => 9,
    'c'  => 2,
    'b'  => 1,
    'a'  => 3,
]);
// シュワルツ変換を使用したソート（引数説明のために全て列挙している）
that(kvsort($array, fn($hashA, $hashB, $av, $bv, $ak, $bk) => ($hashA['md5'] <=> $hashB['md5']) ?: ($hashA['sha1'] <=> $hashB['sha1']), [
    'md5'  => fn($v) => md5($v),
    'sha1' => fn($v) => sha1($v),
]))->isSame([
    'x1' => 9,
    'x2' => 9,
    'x3' => 9,
    'b'  => 1,
    'c'  => 2,
    'a'  => 3,
]);
// シュワルツ変換の場合 $comparator は省略可能（昇順）で、配列ではなく単一値を渡せばその結果値が渡ってくる（これは要するに md5 での昇順ソート）
that(kvsort($array, null, fn($v) => md5($v)))->isSame([
    'x1' => 9,
    'x2' => 9,
    'x3' => 9,
    'b'  => 1,
    'c'  => 2,
    'a'  => 3,
]);

空の場合は $default を返す。

Example:

that(last_key(['a', 'b', 'c']))->isSame(2);
that(last_key([], 999))->isSame(999);

空の場合は $default を返す。

Example:

that(last_keyvalue(['a', 'b', 'c']))->isSame([2, 'c']);
that(last_keyvalue([], 999))->isSame(999);

空の場合は $default を返す。

Example:

that(last_value(['a', 'b', 'c']))->isSame('c');
that(last_value([], 999))->isSame(999);

$key が最後のキーだった場合は null を返す。 $key が存在しない場合は false を返す。 $key が未指定だと「次に生成されるキー」（$array[]='hoge' で生成されるキー）を返す。

$array[] = 'hoge' で作成されるキーには完全準拠しない（標準は unset すると結構乱れる）。公式マニュアルを参照。

Example:

$array = [9 => 9, 'a' => 'A', 'b' => 'B', 'c' => 'C'];
// 'b' キーの次は 'c'
that(next_key($array, 'b'))->isSame('c');
// 'c' キーの次は無いので null
that(next_key($array, 'c'))->isSame(null);
// 'x' キーはそもそも存在しないので false
that(next_key($array, 'x'))->isSame(false);
// 次に生成されるキーは 10
that(next_key($array, null))->isSame(10);

$key が最初のキーだった場合は null を返す。 $key が存在しない場合は false を返す。

Example:

$array = ['a' => 'A', 'b' => 'B', 'c' => 'C'];
// 'b' キーの前は 'a'
that(prev_key($array, 'b'))->isSame('a');
// 'a' キーの前は無いので null
that(prev_key($array, 'a'))->isSame(null);
// 'x' キーはそもそも存在しないので false
that(prev_key($array, 'x'))->isSame(false);

かなり局所的な実装で vendor ディレクトリを変更していたりするとそれだけで例外になる。

Example:

that(auto_loader())->contains('autoload.php');

class_alias は即座にオートロードされるが、この関数は必要とされるまでオートロードしない。

Example:

class_aliases([
    'TestCase' => \PHPUnit\Framework\TestCase::class,
]);
that(class_exists('TestCase', false))->isFalse(); // オートロードを走らせなければまだ定義されていない
that(class_exists('TestCase', true))->isTrue();   // オートロードを走らせなければ定義されている

(new \ReflectionClass($class))->getConstants() とほぼ同じだが、可視性でフィルタができる。 さらに「自分自身の定義か？」でもフィルタできる。

Example:

$class = new class extends \ArrayObject
{
    private   const C_PRIVATE   = 'private';
    protected const C_PROTECTED = 'protected';
    public    const C_PUBLIC    = 'public';
};
// 普通に全定数を返す
that(class_constants($class))->isSame([
    'C_PRIVATE'      => 'private',
    'C_PROTECTED'    => 'protected',
    'C_PUBLIC'       => 'public',
    'STD_PROP_LIST'  => \ArrayObject::STD_PROP_LIST,
    'ARRAY_AS_PROPS' => \ArrayObject::ARRAY_AS_PROPS,
]);
// public のみを返す
that(class_constants($class, IS_PUBLIC))->isSame([
    'C_PUBLIC'       => 'public',
    'STD_PROP_LIST'  => \ArrayObject::STD_PROP_LIST,
    'ARRAY_AS_PROPS' => \ArrayObject::ARRAY_AS_PROPS,
]);
// 自身定義でかつ public のみを返す
that(class_constants($class, IS_OWNSELF | IS_PUBLIC))->isSame([
    'C_PUBLIC'       => 'public',
]);

インスタンスに特異メソッド・特異フィールドのようなものを生やす。 ただし、特異フィールドの用途はほとんどない（php はデフォルトで特異フィールドのような動作なので）。 そのクラスの __set/__get が禁止されている場合に使えるかもしれない程度。

クロージャ配列を渡すと特異メソッドになる。 そのクロージャの $this は元オブジェクトで bind される。 ただし、static closure を渡した場合はそれは static メソッドとして扱われる。

$implements でインターフェースの配列を渡すとすべてが動的に implement される。 つまり得られたオブジェクトが instanceof を通るようになる。 もちろんメソッド配列としてその名前が含まれていなければならない。

内部的にはいわゆる Decorator パターンを動的に実行しているだけであり、実行速度は劣悪。 当然ながら final クラス/メソッドの拡張もできない。

Example:

// Exception に「count」メソッドと「コードとメッセージを結合して返す」メソッドを動的に生やす
$object = new \Exception('hoge', 123);
$newobject = class_extends($object, [
    'count'       => function () { return $this->code; },
    'codemessage' => function () {
        // bind されるので protected フィールドが使える
        return $this->code . ':' . $this->message;
    },
], [], [\Countable::class]);
that($newobject->count())->isSame(123);
that($newobject->codemessage())->isSame('123:hoge');
that($newobject)->isInstanceOf(\Countable::class); // instanceof をパスできる

// オーバーライドもできる（ArrayObject の count を2倍になるように上書き）
$object = new \ArrayObject([1, 2, 3]);
$newobject = class_extends($object, [
    'count' => function () {
        // parent は元オブジェクトを表す
        return parent::count() * 2;
    },
]);
that($newobject->count())->isSame(6);

かなり局所的な実装で vendor ディレクトリを変更していたりするとそれだけで例外になる。

Example:

that(class_loader())->isInstanceOf(\Composer\Autoload\ClassLoader::class);

実質的には composer で読み込まれるクラスマップを返す。 つまり dump-autoload -o したときの getClassMap 相当を返す。

ファイル名からクラス名を逆引きする都合上、猛烈に遅いので注意。

Example:

that(class_namespace('vendor\\namespace\\ClassName'))->isSame('vendor\\namespace');

例えば継承ツリーが下記の場合を考える。

classA <- classB <- classC

この場合、「classC は classB に」「classB は classA に」それぞれ依存している、と考えることができる。 これは静的に決定的であり、この依存を壊したり注入したりする手段は存在しない。 例えば classA の実装を差し替えたいときに、いかに classA を継承した classAA を定義したとしても classB の親は classA で決して変わらない。

この関数を使うと本当に classA そのものを弄るので、継承ツリーを下記のように変えることができる。

classA <- classAA <- classB <- classC

つまり、classA を継承した classAA を定義してそれを classA とみなすことが可能になる。 ただし、内部的には class_alias を使用して実現しているので厳密には異なるクラスとなる。

実際のところかなり強力な機能だが、同時にかなり黒魔術的なので乱用は控えたほうがいい。

Example:

// Y1 extends X1 だとしてクラス定義でオーバーライドする
class_replace('\\ryunosuke\\Test\\Package\\files\\classes\\X1', function () {
    // アンスコがついたクラスが定義されるので匿名クラスを返す
    return new class() extends \ryunosuke\Test\Package\files\classes\X1_
    {
        function method(){return 'this is X1d';}
        function newmethod(){return 'this is newmethod';}
    };
});
// X1 を継承している Y1 にまで影響が出ている（X1 を完全に置換できたということ）
that((new \ryunosuke\Test\Package\files\classes\Y1())->method())->isSame('this is X1d');
that((new \ryunosuke\Test\Package\files\classes\Y1())->newmethod())->isSame('this is newmethod');

// Y2 extends X2 だとしてクロージャ配列でオーバーライドする
class_replace('\\ryunosuke\\Test\\Package\\files\classes\\X2', fn() => [
    'method'    => function () {return 'this is X2d';},
    'newmethod' => function () {return 'this is newmethod';},
]);
// X2 を継承している Y2 にまで影響が出ている（X2 を完全に置換できたということ）
that((new \ryunosuke\Test\Package\files\classes\Y2())->method())->isSame('this is X2d');
that((new \ryunosuke\Test\Package\files\classes\Y2())->newmethod())->isSame('this is newmethod');

// メソッド定義だけであればクロージャではなく配列指定でも可能。さらに trait 配列を渡すとそれらを use できる
class_replace('\\ryunosuke\\Test\\Package\\files\classes\\X3', [
    [\ryunosuke\Test\Package\files\classes\XTrait::class],
    'method' => function () {return 'this is X3d';},
]);
// X3 を継承している Y3 にまで影響が出ている（X3 を完全に置換できたということ）
that((new \ryunosuke\Test\Package\files\classes\Y3())->method())->isSame('this is X3d');
// トレイトのメソッドも生えている
that((new \ryunosuke\Test\Package\files\classes\Y3())->traitMethod())->isSame('this is XTrait::traitMethod');

// メソッドとトレイトだけならば無名クラスを渡すことでも可能
class_replace('\\ryunosuke\\Test\\Package\\files\classes\\X4', new class() {
    use \ryunosuke\Test\Package\files\classes\XTrait;
    function method(){return 'this is X4d';}
});
// X4 を継承している Y4 にまで影響が出ている（X4 を完全に置換できたということ）
that((new \ryunosuke\Test\Package\files\classes\Y4())->method())->isSame('this is X4d');
// トレイトのメソッドも生えている
that((new \ryunosuke\Test\Package\files\classes\Y4())->traitMethod())->isSame('this is XTrait::traitMethod');

Example:

that(class_shorten('vendor\\namespace\\ClassName'))->isSame('ClassName');

トレイトが use しているトレイトが use しているトレイトが use している・・・のような場合もすべて返す。

Example:

trait T1{}
trait T2{use T1;}
trait T3{use T2;}
that(class_uses_all(new class{use T3;}))->isSame([
    'Example\\T3' => 'Example\\T3', // クラスが直接 use している
    'Example\\T2' => 'Example\\T2', // T3 が use している
    'Example\\T1' => 'Example\\T1', // T2 が use している
]);

グローバル定数も調べられる。ので実質的には defined とほぼ同じで違いは下記。

• defined は単一引数しか与えられないが、この関数は2つの引数も受け入れる
• defined は private const で即死するが、この関数はきちんと調べることができる
• ClassName::class は常に true を返す

あくまで存在を調べるだけで実際にアクセスできるかは分からないので注意（property_exists と同じ）。

Example:

// クラス定数が調べられる（1引数、2引数どちらでも良い）
that(const_exists('ArrayObject::STD_PROP_LIST'))->isTrue();
that(const_exists('ArrayObject', 'STD_PROP_LIST'))->isTrue();
that(const_exists('ArrayObject::UNDEFINED'))->isFalse();
that(const_exists('ArrayObject', 'UNDEFINED'))->isFalse();
// グローバル（名前空間）もいける
that(const_exists('PHP_VERSION'))->isTrue();
that(const_exists('UNDEFINED'))->isFalse();

指定パスに名前空間を持つような php ファイルが有るならその名前空間を返す。 指定パスに名前空間を持つような php ファイルが無いなら親をたどる。 親に名前空間を持つような php ファイルが有るならその名前空間＋ローカルパスを返す。

言葉で表すとややこしいが、「そのパスに配置しても違和感の無い名前空間」を返してくれるはず。

Example:

// Example 用としてこのパッケージの Transporter を使用してみる
$dirname = dirname(class_loader()->findFile(\ryunosuke\Functions\Transporter::class));
// "$dirname/Hoge" の名前空間を推測して返す
that(namespace_detect("$dirname/Hoge"))->isSame("ryunosuke\\Functions\\Hoge");

存在しない場合は $default を返す。

Example:

$class = (object) [
    'a' => (object) [
        'b' => (object) [
            'c' => 'vvv'
        ]
    ]
];
that(object_dive($class, 'a.b.c'))->isSame('vvv');
that(object_dive($class, 'a.b.x', 9))->isSame(9);
// 配列を与えても良い。その場合 $delimiter 引数は意味をなさない
that(object_dive($class, ['a', 'b', 'c']))->isSame('vvv');

内部でオブジェクト自体は保持しない。 つまり、そのオブジェクトは GC の対象になる。

オブジェクトを与えると一意な整数を返す。 内部で連番を保持するので PHP_INT_MAX まで生成できる。 PHP_INT_MAX を超えた場合の挙動は未定義（まぁまずありえないだろう）。 null は特別扱いとして必ず 0 を返す。

逆に整数を与えると対応したオブジェクトを返す。 設定していないか既に GC されている場合は null を返す。 0 は特別扱いとして必ず null を返す。

Example:

// spl_object_id は容易に重複するが・・・
that(spl_object_id(new \stdClass()) === spl_object_id(new \stdClass()))->isTrue();
// この object_id 関数は重複しない
that(object_id(new \stdClass()) === object_id(new \stdClass()))->isFalse();

$o = new \stdClass();
// オブジェクトを与えると固有IDを返す
that($id = object_id($o))->isInt();
// そのIDを与えると元のオブジェクトが得られる
that($o === object_id($id))->isTrue();
// 参照を握っているわけではないので GC されていると null を返す
unset($o);
that(null === object_id($id))->isTrue();

get_object_vars + no public プロパティを返すイメージ。 クロージャだけは特別扱いで this + use 変数を返す。

Example:

$object = new #[\AllowDynamicProperties] class('something', 42) extends \Exception{};
$object->oreore = 'oreore';

// get_object_vars はそのスコープから見えないプロパティを取得できない
// var_dump(get_object_vars($object));

// array キャストは全て得られるが null 文字を含むので扱いにくい
// var_dump((array) $object);

// この関数を使えば不可視プロパティも取得できる
that(object_properties($object))->subsetEquals([
    'message' => 'something',
    'code'    => 42,
    'oreore'  => 'oreore',
]);

// クロージャは this と use 変数を返す
that(object_properties(fn() => $object))->is([
    'this'   => $this,
    'object' => $object,
]);

実質的に WeakMap と同じ。 ただし php 内部では本来オブジェクトであるべきものもリソースとして扱われる（curl とか）ので統一のためにリソースも扱える。

典型的な利用法として「クロージャに値を持たせたい」がある。 クロージャに限らず、大抵の内部オブジェクトは動的プロパティを生やせないので、値の保持がめんどくさい。 （spl_object_id は重複するので使えないし、下手に実装すると参照が握られて GC されない羽目になる）。

Example:

$storage = object_storage('test');
$closure = fn() => 123;
$resource = tmpfile();

// このように set すると・・・
$storage->set($closure, 'attached data1');
// get で取り出せる
that($storage->get($closure))->isSame('attached data1');
// リソースも扱える
$storage->set($resource, 'attached data2');
that($storage->get($resource))->isSame('attached data2');

// 名前空間が同じならインスタンスをまたいで取得できる
$storage2 = object_storage('test');
that($storage2->get($closure))->isSame('attached data1');

// オブジェクトが死ぬと同時に消える
unset($closure);
that($storage2->count())->isSame(1);
// リソースの場合は close でも消える
fclose($resource);
that($storage2->count())->isSame(0);
that($storage2->get($resource))->is(null);

before を使って「クラスを読み込み前に動的に書き換える」のようなことが可能になる。 after を使って「__initialize を呼ぶ」のような規約を定めればスタティックイニシャライザのようなことが可能になる。

prepend なオートローダで実装してあるので、その後のさらに prepend されたようなオートローダでの読み込みは感知できない。 もちろんロード済みクラスも感知できない。

before 内で無条件にクラスを呼ぶと無限ループになるので注意（オートローダが呼ばれて before が呼ばれてオートローダが呼ばれて before が呼ばれて・・・）。

ローダーオブジェクトを返すが特に意味はなく、使うべきではない。

object キャストとほとんど同じだが、名前付き可変引数を採用しているので JSON ライクに宣言することができる。 その代わり数値キー等の php の識別子として不正なキーを生やすことはできない。 （厳密に言えば名前付き引数を使わなければ数値キーは生成できるが…そんなことをするなら普通に object キャストをすればよい）。

Example:

// 名前付き可変引数でコールできる
that(stdclass(a: 1, b: 2))->isInstanceOf(\stdClass::class);
// iterable も渡せる（この場合は実質的に object キャストと同義）
that(stdclass(...['a' => 1, 'b' => 2]))->isInstanceOf(\stdClass::class);

class/interface/trait/enum exists の合せ技。 trait/enum のように今後型的なものがさらに増えるかもしれないし、class_exists だけして interface/trait が抜けているコードを何度も見てきた。 それを一元管理するような関数となる。

Example:

that(class_exists(\Throwable::class))->isFalse();     // class_exists は class にしか反応しない
that(interface_exists(\Exception::class))->isFalse(); // interface_exists は interface にしか反応しない
that(trait_exists(\Error::class))->isFalse();         // trait_exists は trait にしか反応しない
// type_exists であれば全てに反応する
that(type_exists(\Throwable::class))->isTrue();
that(type_exists(\Exception::class))->isTrue();
that(type_exists(\Error::class))->isTrue();

非常に荒くアドホックに実装しているのでこの関数で得られた SQL を実際に実行してはならない。 あくまでログ出力やデバッグ用途で視認性を高める目的である。

プレースホルダは ? か :alnum で混在していても良い。

Example:

that(sql_bind('select ?', 1))->isSame("select 1");
that(sql_bind('select :hoge', ['hoge' => 'hoge']))->isSame("select 'hoge'");
that(sql_bind('select ?, :hoge', [1, 'hoge' => 'hoge']))->isSame("select 1, 'hoge'");

非常に荒くアドホックに実装しているのでこの関数で得られた SQL を実際に実行してはならない。 あくまでログ出力やデバッグ用途で視認性を高める目的である。

JOIN 句は FROM 句とみなさず、別句として処理する。 AND と && は微妙に処理が異なる。 AND は改行されるが && は改行されない（OR と || も同様）。

非常に荒くアドホックに実装しているのでこの関数で得られた値で実際に実行してはならない。 あくまでログ出力やデバッグ用途で視認性を高める目的である。

• null は NULL になる
• 数字はそのまま数字になる
• bool は 0 or 1 になる
• 配列は再帰的にカンマ区切りになる
  • この実装はエラー回避の意味合いが強く、実装は変更される可能性がある
• それ以外は addcslashes される

Example:

that(sql_quote(null))->isSame('NULL');
that(sql_quote(123))->isSame(123);
that(sql_quote(true))->isSame(1);
that(sql_quote("hoge"))->isSame("'hoge'");
that(sql_quote([1, 2, 3]))->isSame("1,2,3");

包含などではない属性セレクタを与えると属性として認識する。 独自仕様として・・・

[!attr]

否定属性として false を返す

styles

style 属性とみなす

がある。

Example:

that(css_selector('#hoge.c1.c2[name=hoge\[\]][href="http://hoge"][hidden][!readonly]{width:123px;height:456px}'))->is([
    'id'       => 'hoge',
    'class'    => ['c1', 'c2'],
    'name'     => 'hoge[]',
    'href'     => 'http://hoge',
    'hidden'   => true,
    'readonly' => false,
    'style'    => [
        'width'  => '123px',
        'height' => '456px',
    ],
]);

CSV ヘッダ行は全連想配列のキーの共通項となる。 順番には依存しないが、余計な要素があってもそのキーはヘッダには追加されないし、データ行にも含まれない。 ただし、オプションで headers が与えられた場合はそれを使用する。 この headers オプションに連想配列を与えるとヘッダ文字列変換になる（[key => header] で「key を header で吐き出し」となる）。 数値配列を与えると単純に順序指定での出力指定になるが、ヘッダ行が出力されなくなる。

callback オプションが渡された場合は「あらゆる処理の最初」にコールされる。 つまりヘッダの読み換えや文字エンコーディングの変換が行われる前の状態でコールされる。 また、 false を返すとその要素はスルーされる。

output オプションにリソースを渡すとそこに対して書き込みが行われる（fclose はされない）。

Example:

// シンプルな実行例
$csvarrays = [
    ['a' => 'A1', 'b' => 'B1', 'c' => 'C1'],             // 普通の行
    ['c' => 'C2', 'a' => 'A2', 'b' => 'B2'],             // 順番が入れ替わっている行
    ['c' => 'C3', 'a' => 'A3', 'b' => 'B3', 'x' => 'X'], // 余計な要素が入っている行
];
that(csv_export($csvarrays))->is("a,b,c
A1,B1,C1
A2,B2,C2
A3,B3,C3
");

// ヘッダを指定できる
that(csv_export($csvarrays, [
    'headers' => ['a' => 'A', 'c' => 'C'], // a と c だけを出力＋ヘッダ文字変更
]))->is("A,C
A1,C1
A2,C2
A3,C3
");

// ヘッダ行を出さない
that(csv_export($csvarrays, [
    'headers' => ['a', 'c'], // a と c だけを出力＋ヘッダ行なし
]))->is("A1,C1
A2,C2
A3,C3
");

// structure:true で配列も扱える
that(csv_export([
    ['scalar' => '123', 'list' => ['list11', 'list12'], 'hash' => ['a' => 'hash1A', 'b' => 'hash1B']],
    ['scalar' => '456', 'list' => ['list21', 'list22'], 'hash' => ['a' => 'hash2A', 'b' => 'hash2B']],
], [
    'structure' => true,
]))->is("scalar,list[],list[],hash[a],hash[b]
123,list11,list12,hash1A,hash1B
456,list21,list22,hash2A,hash2B
");

1行目をヘッダ文字列とみなしてそれをキーとした連想配列の配列を返す。 ただし、オプションで headers が与えられた場合はそれを使用する。 この headers オプションはヘッダフィルタも兼ねる（[n => header] で「n 番目フィールドを header で取り込み」となる）。 入力にヘッダがありかつ headers に連想配列が渡された場合はフィルタ兼読み換えとなる（Example を参照）。

structure オプションが渡された場合は query like なヘッダーで配列になる。

callback オプションが渡された場合は「あらゆる処理の最後」にコールされる。 つまりヘッダの読み換えや文字エンコーディングの変換が行われた後の状態でコールされる。 また、 false を返すとその要素はスルーされる。

メモリ効率は意識しない（どうせ配列を返すので意識しても無駄）。

Example:

// シンプルな実行例
that(csv_import("
a,b,c
A1,B1,C1
A2,B2,C2
A3,B3,C3
"))->is([
    ['a' => 'A1', 'b' => 'B1', 'c' => 'C1'],
    ['a' => 'A2', 'b' => 'B2', 'c' => 'C2'],
    ['a' => 'A3', 'b' => 'B3', 'c' => 'C3'],
]);

// ヘッダを指定できる
that(csv_import("
A1,B1,C1
A2,B2,C2
A3,B3,C3
", [
    'headers' => [0 => 'a', 2 => 'c'], // 1がないので1番目のフィールドを読み飛ばしつつ、0, 2 は "a", "c" として取り込む
]))->is([
    ['a' => 'A1', 'c' => 'C1'],
    ['a' => 'A2', 'c' => 'C2'],
    ['a' => 'A3', 'c' => 'C3'],
]);

// ヘッダありで連想配列で指定するとキーの読み換えとなる（指定しなければ読み飛ばしも行える）
that(csv_import("
a,b,c
A1,B1,C1
A2,B2,C2
A3,B3,C3
", [
    'headers' => ['a' => 'hoge', 'c' => 'piyo'], // a は hoge, c は piyo で読み込む。 b は指定がないので飛ばされる
]))->is([
    ['hoge' => 'A1', 'piyo' => 'C1'],
    ['hoge' => 'A2', 'piyo' => 'C2'],
    ['hoge' => 'A3', 'piyo' => 'C3'],
]);

// structure:true で配列も扱える
that(csv_import("
scalar,list[],list[],hash[a],hash[b]
123,list11,list12,hash1A,hash1B
456,list21,list22,hash2A,hash2B
", [
    'structure' => true,
]))->is([
    ['scalar' => '123', 'list' => ['list11', 'list12'], 'hash' => ['a' => 'hash1A', 'b' => 'hash1B']],
    ['scalar' => '456', 'list' => ['list21', 'list22'], 'hash' => ['a' => 'hash2A', 'b' => 'hash2B']],
]);

data-* や style, 論理属性など、全てよしなに変換して文字列で返す。 返り値の文字列はエスケープが施されており、基本的にはそのまま html に埋め込んで良い。 （オプション次第では危険だったり乱れたりすることはある）。

separator オプションを指定すると属性の区切り文字を指定できる。 大抵の場合は半角スペースであり、少し特殊な場合に改行文字を指定するくらいだろう。 ただし、この separator に null を与えると文字列ではなく生の配列で返す。 この配列は 属性名 => 属性値 な生の配列であり、エスケープも施されていない。 $options 自体に文字列を与えた場合は separator 指定とみなされる。

属性の変換ルールは下記。

• 属性名が数値の場合は属性としては生成されない
• 属性名は camelCase -> cahin-case の変換が行われる
• 値が null の場合は無条件で無視される
  • 下記 false との違いは「配列返しの場合に渡ってくるか？」である（null は無条件フィルタなので配列返しでも渡ってこない）
• 値が true の場合は論理属性とみなし値なしで生成される
• 値が false の場合は論理属性とみなし、 属性としては生成されない
• 値が配列の場合は ","（カンマ）で結合される
  • これは観測範囲内でカンマ区切りが多いため（srcset, accept など）。属性によってはカンマが適切ではない場合がある
  • 更にその配列が文字キーを持つ場合、キーが "=" で結合される
    • これは観測範囲内で = 区切りが多いため（viewport など）。属性によっては = が適切ではない場合がある
• 値が配列で属性名が class, style, data の場合は下記の特殊な挙動を示す

  class

  半角スペースで結合される

  • キーは無視される

  style

  キーが css 名、値が css 値として ";" で結合される

  • キーは cahin-case に変換される
  • キーが数値の場合は値がそのまま追加される
  • 値が配列の場合は半角スペースで結合される

  data-

  キーが data 名、値が data 値として data 属性になる

  • キーは cahin-case に変換される
  • 値が真偽値以外のスカラーの場合はそのまま、非スカラー||真偽値の場合は json で埋め込まれる
    • これは jQuery において json をよしなに扱うことができるため

※ 上記における「配列」とは iterable を指すが、toString を実装した iterable なオブジェクトは toString が優先され、文字列とみなされる

複雑に見えるが「よしなに」やってくれると考えて良い。 配列や真偽値で分岐が大量にあるが、大前提として「string だった場合は余計なことはしない」がある。 ので迷ったり予期しない結果の場合は呼び出し側で文字列化して呼べば良い。

Example:

that(html_attr([
    // camelCase は camel-case になる
    'camelCase' => '<value>',
    // true は論理属性 true とみなし、値なし属性になる
    'checked'   => true,
    // false は論理属性 false とみなし、属性として現れない
    'disabled'  => false,
    // null は無条件で無視され、属性として現れない
    'readonly'  => null,
    // 配列はカンマで結合される
    'srcset'    => [
        'hoge.jpg 1x',
        'fuga.jpg 2x',
    ],
    // 連想配列は = で結合される
    'content'   => [
        'width' => 'device-width',
        'scale' => '1.0',
    ],
    // class はスペースで結合される
    'class'     => ['hoge', 'fuga'],
    // style 原則的に proerty:value; とみなす
    'style'     => [
        'color'           => 'red',
        'backgroundColor' => 'white',      // camel-case になる
        'margin'          => [1, 2, 3, 4], // スペースで結合される
        'opacity:0.5',                     // 直値はそのまま追加される
    ],
    // data- はその分属性が生える
    'data-'     => [
        'camelCase' => 123,
        'hoge'      => false,        // 真偽値は文字列として埋め込まれる
        'fuga'      => "fuga",       // 文字列はそのまま文字列
        'piyo'      => ['a' => 'A'], // 非スカラー以外は json になる
    ],
], ['separator' => "\n"]))->is('camel-case="&lt;value&gt;"
checked
srcset="hoge.jpg 1x,fuga.jpg 2x"
content="width=device-width,scale=1.0"
class="hoge fuga"
style="color:red;background-color:white;margin:1 2 3 4;opacity:0.5"
data-camel-case="123"
data-hoge="false"
data-fuga="fuga"
data-piyo="{&quot;a&quot;:&quot;A&quot;}"');

文字列的ではなく DOM 的に行うのでおかしな部分 html を食わせると意図しない結果になる可能性がある。 その副作用として属性のクオートやタグ内空白は全て正規化される。

html コメントも削除される。 また、空白が意味を持つタグ（textarea, pre）は対象にならない。 さらに、php を含むような html （テンプレート）の php タグは一切の対象外となる。

これらの挙動の一部はオプションで指定が可能。

Example:

// e.g. id が " でクオートされている
// e.g. class のクオートが " になっている
// e.g. タグ内空白（id, class の間隔等）がスペース1つになっている
// e.g. php タグは一切変更されていない
// e.g. textarea は保持されている
that(html_strip("<span  id=id  class='c1  c2  c3'><?= '<hoge>  </hoge>' ?> a  b  c </span> <pre> a  b  c </pre>"))->isSame('<span id="id" class="c1  c2  c3"><?= \'<hoge>  </hoge>\' ?> a b c </span><pre> a  b  c </pre>');

tag#id.class[attr=value] のような css セレクタから <tag id="id" class="class" attr="value"></tag> のような html 文字列を返す。 配列を与えるとキーがセレクタ、値がコンテント文字列になる。 さらに値が配列だと再帰して生成する。

値や属性は適切に htmlspecialchars される。

Example:

// 単純文字列はただのタグを生成する
that(
    html_tag('a#hoge.c1.c2[name=hoge\[\]][href="http://hoge"][hidden]'))
    ->isSame('<a id="hoge" class="c1 c2" name="hoge[]" href="http://hoge" hidden></a>'
);
// ペア配列を与えるとコンテント文字列になる
that(
    html_tag(['a.c1#hoge.c2[name=hoge\[\]][href="http://hoge"][hidden]' => "this is text's content"]))
    ->isSame('<a id="hoge" class="c1 c2" name="hoge[]" href="http://hoge" hidden>this is text&#039;s content</a>'
);
// ネストした配列を与えると再帰される
that(
    html_tag([
        'div#wrapper' => [
            'b.class1' => [
                '<plain>',
            ],
            'b.class2' => [
                '<plain1>',
                's' => '<strike>',
                '<plain2>',
            ],
        ],
    ]))
    ->isSame('<div id="wrapper"><b class="class1">&lt;plain&gt;</b><b class="class2">&lt;plain1&gt;<s>&lt;strike&gt;</s>&lt;plain2&gt;</b></div>'
);

Example:

that(ini_export(['a' => 1, 'b' => 'B', 'c' => PHP_SAPI]))->is('a = 1
b = "B"
c = "cli"
');

Example:

that(ini_import("
a = 1
b = 'B'
c = PHP_VERSION
"))->is(['a' => 1, 'b' => 'B', 'c' => PHP_VERSION]);

引数体系とデフォルト値を変更してある。また、エラー時に例外が飛ぶ。

下記の拡張オプションがある。

JSON_INLINE_LEVEL

PRETTY_PRINT 時に指定以上の階層をインライン化する（数値以外にパスで階層も指定できる）

JSON_INLINE_SCALARLIST

PRETTY_PRINT 時にスカラーのみのリストをインライン化する

JSON_INDENT

PRETTY_PRINT 時にインデント数・文字列を指定する

JSON_CLOSURE

任意のリテラルを埋め込む

• クロージャの返り値がそのまま埋め込まれるので、文字列化可能な結果を返さなければならない

JSON_ES5 を与えると JSON5 互換でエンコードされる。 その際下記のプションも使用可能になる。

JSON_TEMPLATE_LITERAL

改行を含む文字列をテンプレートリテラルで出力する

JSON_TRAILING_COMMA

末尾カンマを強制する

JSON_COMMENT_PREFIX

コメントとして埋め込まれるキープレフィックスを指定する

• そのキーで始まる要素が文字列なら // コメントになる
• そのキーで始まる要素が配列なら /* コメントになる

Example:

// オプションはこのように [定数 => bool] で渡す。false は指定されていないとみなされる（JSON_MAX_DEPTH 以外）
that(json_export(['a' => 'A', 'b' => 'B'], [
   JSON_PRETTY_PRINT => false,
]))->is('{"a":"A","b":"B"}');
// json5 でコメント付きかつ末尾カンマ強制モード
that(json_export(['a' => 'A', '#comment' => 'this is comment', 'b' => 'B'], [
   JSON_ES5            => true,
   JSON_TRAILING_COMMA => true,
   JSON_COMMENT_PREFIX => '#',
   JSON_PRETTY_PRINT   => true,
]))->is('{
    a: "A",
    // this is comment
    b: "B",
}');

引数体系とデフォルト値を変更してある。

JSON_ES5 に null か true を渡すと json5 としてでデコードする（null はまず json_decode で試みる、true は json5 のみ）。 その場合拡張オプションとして下記がある。

JSON_INT_AS_STRING

常に整数を文字列で返す

JSON_FLOAT_AS_STRING

常に小数を文字列で返す

JSON_BARE_AS_STRING

bare string を文字列として扱う

JSON_TEMPLATE_LITERAL

テンプレートリテラルが使用可能になる

• あくまで「文字列の括りに ` が使えるようになる」というものでテンプレートリテラルそのものではない
• 末尾のインデントと同じインデントがすべて除去され、前後の改行は取り除かれる

Example:

// オプションはこのように [定数 => bool] で渡す。false は指定されていないとみなされる（JSON_MAX_DEPTH 以外）
that(json_import('{"a":"A","b":"B"}', [
   JSON_OBJECT_AS_ARRAY => true,
]))->is(['a' => 'A', 'b' => 'B']);

// json5 が使える
that(json_import('{a: "A", b: "B", }'))->is(['a' => 'A', 'b' => 'B']);

// テンプレートリテラル
that(json_import('`
    1
    2
    3
    `', [
    JSON_TEMPLATE_LITERAL => true,
]))->is("1\n2\n3");