【Laravel】ヘルパ関数の紹介配列編４【isAssoc、last、only、pluck、prepend、pull、query】

.Dev.Record

#6239da8fda012
【Laravel】ヘルパ関数の紹介配列編４【isAssoc、last、only、pluck、prepend、pull、query】
2022.03.22

前回に引き続き本記事でもLaravelの配列関連のへルパ関数を解説していきたいと思います。

参考になれば幸いです。

Memo

Laravelのバージョンは8系統になります。

今回解説するへルパ関数は以下です。

本記事で取り扱うへルパ関数

Arr::isAssoc 連想配列かを判定
Arr::last 条件に一致した最後の要素を返す
Arr::only 配列を指定したキー/値のペアのみにフィルタリング
Arr::pluck 指定したキーの値を全て取得
Arr::prepend 配列の先頭に要素を追加
Arr::pull 指定したキーの値を取得し、取得元の配列からは削除する
Arr::query 配列をクエリ文字に変換する

Arr::isAssoc 連想配列かを判定する

指定した配列が連想配列の場合にtrueを返します。

Arr::isAssoc

Arr::isAssoc(配列): bool

連想配列の場合にtrueを返す
連想配列と添字配列が混ざっている場合はtrueを返す
多次元配列の場合は、一階層目を見て判定する
コレクションは使用不可（エラーになる）

使用例
1// 連想配列の場合にtrue
2$array = ['key-1' => 1];
3Arr::isAssoc($array)
4
5// 添字配列の場合はfalse
6$array = [1, 2];
7Arr::isAssoc($array)
8
9// 連想配列と添字配列が混ざっている場合はtrue
10$array = [1, 2, 'key-1' => 1];
11Arr::isAssoc($array);
12
13// 多次元配列の場合は一階層目を見て判定する
14// 下記の場合は一階層目は添字配列なのでfalse
15$array = [1, 2, ['key-1' => 3]];
16
17// コレクションは不可（エラー）
18// Illuminate\Support\Arr::isAssoc(): Argument #1 ($array) must be of type array
19$collection = Collection::make(['key-1' => 1]);
20Arr::isAssoc($array)

Arr::last 配列内で条件に一致した最後の要素を返す

配列内で条件に一致した最後の要素を返します。

条件はコールバック関数で指定し、配列内の要素毎にコールバック関数が実施されます。

Arr::last

Arr::last(配列, 要素を検証するコールバック関数（値, キー）, （オプション）条件に一致する要素がなかった場合に返す値)

第二引数のコールバック関数内に要素を判定する条件を記載します。
コールバック関数は配列の要素毎に実行され、最後にtrueが返った要素が返り値となります。
コールバック関数は検証する配列の各要素の値とキーを引数に取れます。（第一引数に値、第二引数にキー）
第三引数はオプションで指定すると、条件に一致する要素が存在しない場合に返されるデフォルト値として扱われます。
コレクションも可

使用例
1$array = ['key-1' => 100, 'key-2' => 200, 'key-3' => 300];
2dd(Arr::last($array, function($value, $key) {
3    return $value >= 200;
4}));
5
6// 結果
7300

上記の例では、第二引数のコールバック関数内で値が200以上という条件を指定しており、条件に一致するのは200と300になります。

返り値として返されるのは条件に一致した最後の値になるので300がこの例の場合の返り値になります。

以下はサンプルのコールバック関数の実行イメージになります。

実行例のイメージ
1$array = ['key-1' => 100, 'key-2' => 200, 'key-3' => 300];
2Arr::last($array, function($value, $key) {
3    // コールバック関数は配列の要素毎に実施される
4    // 一周目、$value = 100で条件に一致しないので次の要素へ
5    // 二周目に$value = 200で条件に一致するのでtrueの判定になり次の要素へ
6    // 三周目に$value = 300で条件に一致するのでtrueの判定。
7    // 配列の要素が全て検証し終わり、最後に条件に一致したのは$value = 300なので返り値として300が返される
8    return $value >= 200;
9});

第三引数に値を設定すると、条件に一致する要素がなかった場合のデフォルト値を指定できます。

第三引数を設定した場合
1$array   = ['key-1' => 100, 'key-2' => 200, 'key-3' => 300];
2$default = 'default';
3
4// 第三引数を指定すると条件に一致する値がなかった場合のデフォルト値となる
5dd(Arr::last($array, function($value, $key) {
6    return $value >= 500;
7}, $default));
8
9// 結果
10"default"

Arr::only 配列を指定したキー/値のペアのみにフィルタリング

配列を指定したキー/値のペアのみにフィルタリングします。

Arr::only

Arr::only(配列, フィルタリングをかけるキー): array

フィルタリングをかけるキーは配列で複数指定可能
コレクションは不可（エラーになる）
多次元配列の階層が深い部分のキーは指定できない。

使用例
1$array = ['key-1' => 100, 'key-2' => 200, 'key-3' => 300];
2dd(Arr::only($array, 'key-1'));
3
4// 結果
5array:1 [▼
6  "key-1" => 100
7]
8
9// 指定したキーが存在しない場合は空の配列が返る
10$array = ['key-1' => 100, 'key-2' => 200, 'key-3' => 300];
11dd(Arr::only($array, 'key-4'));
12
13// 結果
14[]

指定するキーは配列で複数指定可能です。

キーを複数指定
1$array = ['key-1' => 100, 'key-2' => 200, 'key-3' => 300];
2dd(Arr::only($array, ['key-1', 'key-2']));
3
4// 結果
5array:2 [▼
6  "key-1" => 100
7  "key-2" => 200
8]

コレクションでは使用できずエラーになります。

コレクションを使用した場合（エラー）
1$collection = Collection::make(['key-1' => 100, 'key-2' => 200, 'key-3' => 300]);
2dd(Arr::only($collection, 'key-1'));
3// エラー
4// array_intersect_key(): Argument #1 ($array) must be of type array, Illuminate\Support\Collection given

多次元配列の場合は階層が深い部分のキーは指定できないようです。

多次元配列の階層が深い部分
1$array = ['key-1' => 100, 'key-2' => ['key-2-1' => 200]];
2dd(Arr::only($array, 'key-2.key-2-1'));
3
4// 結果（期待された動作とならない）
5[]

Arr::pluck 指定したキーの値を全て取得する

配列内の指定したキーの値を全て取得します。

Arr::pluck

Arr::pluck(配列, 取得するキー, 返り値のキーを指定)

指定するキーはドット記法で深い階層も取得可能
キーに(アスタリスク)を使用することで任意の階層の値を取得することも可能*
第三引数を指定することで返り値にキーを指定できます。
コレクションも使用可能

使用例
1$array = [
2    ['key-1' => 1, 'key-2' => 2],
3    ['key-1' => 3, 'key-2' => 4],
4];
5dd(Arr::pluck($array, 'key-1'));
6
7// 結果
8array:2 [▼
9  0 => 1
10  1 => 3
11]

コレクションも可能です。

コレクション
1$collection = Collection::make([
2    ['id' => 'id-1', 'name' => 'PHP'],
3    ['id' => 'id-2', 'name' => 'Laravel'],
4]);
5dd(Arr::pluck($collection, 'name'));
6
7// 結果
8array:2 [▼
9  0 => "PHP"
10  1 => "Laravel"
11]

ドット記法を用いることで多次元配列の深い階層のキー取得可能です。

ドット記法で深い階層のキーを指定
1$array = [
2    ['key-1' => ['key-1-1' => 1], 'key-2' => 2],
3    ['key-1' => ['key-1-1' => 3], 'key-2' => 4],
4];
5dd(Arr::pluck($array, 'key-1.key-1-1'));
6
7// 結果
8array:2 [▼
9  0 => 1
10  1 => 3
11]

指定するキーに*(アスタリスク)を使用することで階層を指定することができます。

*(アスタリスク)を使用
1$array = [
2    ['key-1' => 1, 'key-2' => 2, ['key-3' => 3, 'key-4' => [4]]],
3    ['key-1' => 5, 'key-2' => 6, ['key-3' => 7, 'key-4' => [8]]],
4];
5
6// 二階層目の値を全て指定
7dd(Arr::pluck($array, '*.*'));
8
9// 結果
10array:2 [▼
11  0 => array:2 [▼
12    0 => 3
13    1 => array:1 [▼
14      0 => 4
15    ]
16  ]
17  1 => array:2 [▼
18    0 => 7
19    1 => array:1 [▼
20      0 => 8
21    ]
22  ]
23]

第三引数で返り値のキーを指定できます。

第三引数を指定
1$array = [
2    ['id' => 'id-1', 'name' => 'PHP'],
3    ['id' => 'id-2', 'name' => 'Laravel'],
4];
5dd(Arr::pluck($array, 'name', 'id'));
6
7// 結果
8array:2 [▼
9  "id-1" => "PHP"
10  "id-2" => "Laravel"
11]

Arr::prepend 配列の先頭に要素を追加

配列の先頭に要素を追加します。

Arr::prepend

Arr::prepend(配列, 追加する要素, （オプション）追加するキー)

第三引数には追加するキーを指定可能
コレクションは使用不可（エラーになる）

使用例
1$array = [1, 2, 3, 4];
2dd(Arr::prepend($array, 0));
3
4// 結果
5array:5 [▼
6  0 => 0
7  1 => 1
8  2 => 2
9  3 => 3
10  4 => 4
11]

第三引数に追加する値に対応するキーの指定ができます。

第三引数に追加するキーを指定
1$array = ['key-1' => 1, 'key-2' => 2];
2dd(Arr::prepend($array, 0, 'key-0'));
3
4// 結果
5array:3 [▼
6  "key-0" => 0
7  "key-1" => 1
8  "key-2" => 2
9]

コレクションは使用できずエラーになります。

コレクションを指定（エラー）
1$array = Collection::make([1, 2]);
2dd(Arr::prepend($array, 0));
3
4// エラー
5// array_unshift(): Argument #1 ($array) must be of type array, Illuminate\Support\Collection given

Arr::pull 指定したキーの値を取得し、取得元の配列からは削除する

指定したキーの値を取得し、かつ取得元の配列から削除します。

Arr::pull

Arr::pull(&配列, 削除するキー, （オプション）削除するキーが存在しない場合のデフォルト値): 削除した値

第三引数は指定したキーが存在しない場合に返すデフォルト値
削除キーの指定はドット記法が使える
コレクションも使用可能

使用例
1$array = ['key-1' => 1, 'key-2' => 2];
2dd(Arr::pull($array, 'key-2'), $array);
3
4// 結果（返り値）
52
6
7// 結果（削除後の配列）
8array:1 [▼
9  "key-1" => 1
10]

第三引数を指定した場合はキーが存在しない場合のデフォルト値になります。

第三引数を指定
1$array = ['key-1' => 1, 'key-2' => 2];
2dd(Arr::pull($array, 'key-3', 3), $array);
3
4// 結果（返り値）
53
6
7// 結果（削除元の配列には変化なし）
8array:2 [▼
9  "key-1" => 1
10  "key-2" => 2
11]

ドット記法を用いることで階層が深いキーの指定もできます。

ドット記法の使用
1$array = ['key-1' => 1, 'key-2' => ['key-2-1' => 2]];
2dd(Arr::pull($array, 'key-2.key-2-1'), $array);
3
4// 結果（返り値）
52
6
7// 結果（削除後の配列）
8array:2 [▼
9  "key-1" => 1
10  "key-2" => []
11]

コレクションでも使用可能です。

コレクション
1$collection = Collection::make(['key-1' => 1, 'key-2' => 2]);
2dd(Arr::pull($collection, 'key-2'), $collection);
3
4// 結果（返り値）
52
6
7// 結果（削除後のコレクション）
8Illuminate\Support\Collection {#306 ▼
9  items: array:1 [▼
10    "key-1" => 1
11  ]
12  escapeWhenCastingToString: false
13}

Arr::query 配列をクエリ文字に変換する

配列をクエリ文字列に変換します。

Arr::query

Arr::query

日本語や%が含まれる場合はエンコードされる（エンコード形式はRFC3986）

使用例
1$array = ['name' => 'php', 'id' => 1];
2dd(Arr::query($array));
3
4// 結果
5"name=php&id=1"

エンコード対象の文字列が含まれている場合はエンコードされた状態で出力されます。

エンコードの形式はRFC3986に沿って変換されます。

エンコードされる例
1// 日本語が含まれている場合
2$array = ['name' => 'ピーエイチピー', 'title' => '漢字タイトル'];
3dd(Arr::query($array));
4
5// 結果
6"name=%E3%83%94%E3%83%BC%E3%82%A8%E3%82%A4%E3%83%81%E3%83%94%E3%83%BC&title=%E6%BC%A2%E5%AD%97%E3%82%BF%E3%82%A4%E3%83%88%E3%83%AB"
7
8// %が含まれている場合
9$array = ['name' => '%'];
10dd(Arr::query($array));
11
12// 結果
13"name=%25"

今回は７つの配列系へルパ関数の紹介でした。

以下まとめです。

まとめ

Arr::isAssoc 連想配列かを判定
Arr::last 条件に一致した最後の要素を返す
Arr::only 配列を指定したキー/値のペアのみにフィルタリング
Arr::pluck 指定したキーの値を全て取得
Arr::prepend 配列の先頭に要素を追加
Arr::pull 指定したキーの値を取得し、取得元の配列からは削除する
Arr::query 配列をクエリ文字に変換する

今回はLaravel内部の実装コードも見てみたのですが、公式ドキュメントには記載のない部分も知れて勉強になりました。

残りの配列系のヘルパ関数もまとめていきたいと思います。

.Dev.Record

【Laravel】ヘルパ関数の紹介 配列編４【isAssoc、last、only、pluck、prepend、pull、query】

【Laravel】ヘルパ関数の紹介配列編４【isAssoc、last、only、pluck、prepend、pull、query】