Hash

class Hash

Added in version 2.2

配列マネジメントはとても強力かつ便利なツールであり、適切に使いさえすれば、よりスマートでより最適化されたコードを書くことができるようになるものです。 CakePHP ではとても便利なユーティリティ群を Hash クラスの中に static で用意しており、まさにこれをするのに使えます。

CakePHP の Hash クラスは Inflector クラスと同様で、どのモデルやコントローラからでも呼ぶことができます。例: Hash::combine()。

Hash パス構文

下記のパス構文は Hash が持つすべてのメソッドで使われるものです。ただし、すべてのパス構文が、すべてのメソッドで使用可能であるとは限りません。パスの式はいくつものトークンで構成されます。トークンは、配列データの移動に使う『式』と、要素を絞り込む『マッチャー』の２つのグループに大きく分けられます。マッチャーは要素の式に対して適用することができます。

式の種類

式	説明
`{n}`	数値キーを意味する。どんな文字列キーでも数値型のキーでも一致する。
`{s}`	文字列キーを意味する。数値文字列を含め、どんな文字列でも一致する。
`{*}`	型に関係なく任意の値を表す。
`Foo`	完全に同じ値だった場合のみ一致する。

要素の式はいずれも、すべてのメソッドで使うことができます。特定のメソッドでは、要素の式に加え、属性で絞り込むこともできます。該当するメソッドは、 extract(),　combine(), format(), check(), map(), reduce(), apply(), sort(), insert(), remove() と nest() です。

属性の絞り込み種別

マッチャー	説明
`[id]`	記述されたキーと一致する要素に絞り込む。
`[id=2]`	id が 2 となっている要素に絞り込む。
`[id!=2]`	id が 2 ではない要素に絞り込む。
`[id>2]`	id が 2 より大きい要素に絞り込む。
`[id>=2]`	id が 2 以上の要素に絞り込む。
`[id<2]`	id が 2 より小さい要素に絞り込む。
`[id<=2]`	id が 2 以下の要素に絞り込む。
`[text=/.../]`	正規表現 `...` と合致する値を持っている要素に絞り込む。

Changed in version 2.5

insert() と remove() にマッチャーのサポートが追加されました。

static Hash::get(array $data, $path, $default = null)

戻り値の型: mixed

get() は extract() のシンプル版で、直接的に指定するパス式のみがサポートされます。 {n} や {s} 、マッチャーを使ったパスはサポートされません。配列から１つの値だけを取り出したい場合に get() を使ってください。

static Hash::extract(array $data, $path)

戻り値の型: array

Hash::extract() は Hash Path Syntax にあるすべての式とマッチャーをサポートします。extract を使うことで、配列から好きなパスに沿ったデータを手早く取り出すことができます。もはやデータ構造をループする必要はありません。その代わりに欲しい要素を絞り込むパス式を使うのです:

php

// 共通の使い方:
$users = $this->user->find('all');
$results = Hash::extract($users, '{n}.User.id');
// $results は以下のとおり:
// [1,2,3,4,5,...];

static Hash::insert(array $data, $path, $values = null)

戻り値の型: array

$data を $path の定義に従って配列の中に挿入します。　:

php

$a = [
    'pages' => ['name' => 'page'],
];
$result = Hash::insert($a, 'files', ['name' => 'files']);
// $result は以下のようになります:

[
    [pages] => 
        [
            [name] => page
        ]
    [files] => 
        [
            [name] => files
        ]
]

{n} や {s} を使ったパスを使うことで、複数のポイントにデータを挿入することができます:

php

$users = $this->User->find('all');
$users = Hash::insert($users, '{n}.User.new', 'value');

Changed in version 2.5

2.5.0 から、 insert() で属性のマッチャー表現が動作します。

static Hash::remove(array $data, $path)

戻り値の型: array

$path に合致するすべての要素を配列から削除します。

php

$a = [
    'pages' => ['name' => 'page'],
    'files' => ['name' => 'files'],
];
$result = Hash::remove($a, 'files');
/* $result は以下のようになります:
    [
        [pages] => [
                [name] => page
            ]

    ]
*/

{n} や {s} を使うことで、複数の値を一度に削除することができます。

Changed in version 2.5

2.5.0 から、 insert() で属性のマッチャー表現が動作します。

static Hash::combine(array $data, $keyPath, $valuePath = null, $groupPath = null)

戻り値の型: array

$keyPath のパスをキー、$valuePath （省略可）のパスを値として使って連想配列を作ります。 $valuePath が省略された場合や、$valuePath に合致するものが無かった場合は、値は null で初期化されます。 $groupPath が指定された場合は、そのパスにしたがって生成したものをグルーピングします:

php

$a = [
    [
        'User' => [
            'id' => 2,
            'group_id' => 1,
            'Data' => [
                'user' => 'mariano.iglesias',
                'name' => 'Mariano Iglesias',
            ],
        ],
    ],
    [
        'User' => [
            'id' => 14,
            'group_id' => 2,
            'Data' => [
                'user' => 'phpnut',
                'name' => 'Larry E. Masters',
            ],
        ],
    ],
];

$result = Hash::combine($a, '{n}.User.id');
/* $result は以下のようになります:
    [
        [2] =>
        [14] =>
    ]
*/

$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data');
/* $result は以下のようになります:
    [
        [2] => [
                [user] => mariano.iglesias
                [name] => Mariano Iglesias
            ]
        [14] => [
                [user] => phpnut
                [name] => Larry E. Masters
            ]
    ]
*/

$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data.name');
/* $result は以下のようになります:
    [
        [2] => Mariano Iglesias
        [14] => Larry E. Masters
    ]
*/

$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data', '{n}.User.group_id');
/* $result は以下のようになります:
    [
        [1] => [
                [2] => [
                        [user] => mariano.iglesias
                        [name] => Mariano Iglesias
                    ]
            ]
        [2] => [
                [14] => [
                        [user] => phpnut
                        [name] => Larry E. Masters
                    ]
            ]
    ]
*/

$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data.name', '{n}.User.group_id');
/* $result は以下のようになります:
    [
        [1] => [
                [2] => Mariano Iglesias
            ]
        [2] => [
                [14] => Larry E. Masters
            ]
    ]
*/

$keyPath と $valuePath の両方とも、配列を指定することができます。その場合は、配列の１要素目はフォーマット文字列とみなされ、２要素目以降のパスで取得された値のために使われます:

php

$result = Hash::combine(
    $a,
    '{n}.User.id',
    ['%s: %s', '{n}.User.Data.user', '{n}.User.Data.name'],
    '{n}.User.group_id',
);
/* $result は以下のようになります:
    [
        [1] => [
                [2] => mariano.iglesias: Mariano Iglesias
            ]
        [2] => [
                [14] => phpnut: Larry E. Masters
            ]
    ]
*/

$result = Hash::combine(
    $a,
    ['%s: %s', '{n}.User.Data.user', '{n}.User.Data.name'],
    '{n}.User.id',
);
/* $result は以下のようになります:
    [
        [mariano.iglesias: Mariano Iglesias] => 2
        [phpnut: Larry E. Masters] => 14
    ]
*/

static Hash::format(array $data, array $paths, $format)

戻り値の型: array

配列から取り出し、フォーマット文字列でフォーマットされた文字列の配列を返します:

php

$data = [
    [
        'Person' => [
            'first_name' => 'Nate',
            'last_name' => 'Abele',
            'city' => 'Boston',
            'state' => 'MA',
            'something' => '42',
        ],
    ],
    [
        'Person' => [
            'first_name' => 'Larry',
            'last_name' => 'Masters',
            'city' => 'Boondock',
            'state' => 'TN',
            'something' => '{0}',
        ],
    ],
    [
        'Person' => [
            'first_name' => 'Garrett',
            'last_name' => 'Woodworth',
            'city' => 'Venice Beach',
            'state' => 'CA',
            'something' => '{1}',
        ],
    ],
];

$res = Hash::format($data, ['{n}.Person.first_name', '{n}.Person.something'], '%2$d, %1$s');
/*
[
    [0] => 42, Nate
    [1] => 0, Larry
    [2] => 0, Garrett
]
*/

$res = Hash::format($data, ['{n}.Person.first_name', '{n}.Person.something'], '%1$s, %2$d');
/*
[
    [0] => Nate, 42
    [1] => Larry, 0
    [2] => Garrett, 0
]
*/

static Hash::contains(array $data, array $needle)

戻り値の型: boolean

一方のハッシュや配列の中に、もう一方のキーと値が厳密に見てすべて存在しているかを判定します:

php

$a = [
    0 => ['name' => 'main'],
    1 => ['name' => 'about'],
];
$b = [
    0 => ['name' => 'main'],
    1 => ['name' => 'about'],
    2 => ['name' => 'contact'],
    'a' => 'b',
];

$result = Hash::contains($a, $a);
// true
$result = Hash::contains($a, $b);
// false
$result = Hash::contains($b, $a);
// true

static Hash::check(array $data, string $path = null)

戻り値の型: boolean

配列の中に特定のパスがセットされているかをチェックします:

php

$set = [
    'My Index 1' => ['First' => 'The first item'],
];
$result = Hash::check($set, 'My Index 1.First');
// $result == True

$result = Hash::check($set, 'My Index 1');
// $result == True

$set = [
    'My Index 1' => ['First' =>
        ['Second' =>
            ['Third' =>
                ['Fourth' => 'Heavy. Nesting.']]]],
];
$result = Hash::check($set, 'My Index 1.First.Second');
// $result == True

$result = Hash::check($set, 'My Index 1.First.Second.Third');
// $result == True

$result = Hash::check($set, 'My Index 1.First.Second.Third.Fourth');
// $result == True

$result = Hash::check($set, 'My Index 1.First.Seconds.Third.Fourth');
// $result == False

static Hash::filter(array $data, $callback = ['Hash', 'filter'])

戻り値の型: array

配列から空の要素（ただし '0' 以外）を取り除きます。また、カスタム引数 $callback を指定することで配列の要素を抽出することができます。コールバック関数が false を返した場合、その要素は配列から取り除かれます:

php

$data = [
    '0',
    false,
    true,
    0,
    ['one thing', 'I can tell you', 'is you got to be', false],
];
$res = Hash::filter($data);

/* $data は以下のとおり:
    [
        [0] => 0
        [2] => true
        [3] => 0
        [4] => [
                [0] => one thing
                [1] => I can tell you
                [2] => is you got to be
            ]
    ]
*/

static Hash::flatten(array $data, string $separator = '.')

戻り値の型: array

多次元配列を１次元配列へと平坦化します:

php

$arr = [
    [
        'Post' => ['id' => '1', 'title' => 'First Post'],
        'Author' => ['id' => '1', 'user' => 'Kyle'],
    ],
    [
        'Post' => ['id' => '2', 'title' => 'Second Post'],
        'Author' => ['id' => '3', 'user' => 'Crystal'],
    ],
];
$res = Hash::flatten($arr);
/* $res は以下のようになります:
    [
        [0.Post.id] => 1
        [0.Post.title] => First Post
        [0.Author.id] => 1
        [0.Author.user] => Kyle
        [1.Post.id] => 2
        [1.Post.title] => Second Post
        [1.Author.id] => 3
        [1.Author.user] => Crystal
    ]
*/

static Hash::expand(array $data, string $separator = '.')

戻り値の型: array

Hash::flatten():: によって前もって平坦化された配列を再構築します:

php

$data = [
    '0.Post.id' => 1,
    '0.Post.title' => First Post,
    '0.Author.id' => 1,
    '0.Author.user' => Kyle,
    '1.Post.id' => 2,
    '1.Post.title' => Second Post,
    '1.Author.id' => 3,
    '1.Author.user' => Crystal,
];
$res = Hash::expand($data);
/* $res は以下のとおり:
[
    [
        'Post' => ['id' => '1', 'title' => 'First Post'],
        'Author' => ['id' => '1', 'user' => 'Kyle'],
    ],
    [
        'Post' => ['id' => '2', 'title' => 'Second Post'],
        'Author' => ['id' => '3', 'user' => 'Crystal'],
    ],
];
*/

static Hash::merge(array $data, array $merge[, array $n])

戻り値の型: array

この関数は PHP の array_merge と array_merge_recursive の両方の機能を持っていると考えることができます。この２つの関数との違いは、一方の配列キーがもう一方に含まれていた場合には (array_merge と違って) 再帰的に動きますが、含まれていなかった場合には (array_merge_recursive と違って) 再帰的には動きません。

NOTE

この関数の引数の個数に制限はありません。また、配列以外が引数に指定された場合は配列へとキャストされます。

php

$array = [
    [
        'id' => '48c2570e-dfa8-4c32-a35e-0d71cbdd56cb',
        'name' => 'mysql raleigh-workshop-08 < 2008-09-05.sql ',
        'description' => 'Importing an sql dump',
    ],
    [
        'id' => '48c257a8-cf7c-4af2-ac2f-114ecbdd56cb',
        'name' => 'pbpaste | grep -i Unpaid | pbcopy',
        'description' => 'Remove all lines that say "Unpaid".',
    ],
];
$arrayB = 4;
$arrayC = [0 => 'test array', 'cats' => 'dogs', 'people' => 1267];
$arrayD = ['cats' => 'felines', 'dog' => 'angry'];
$res = Hash::merge($array, $arrayB, $arrayC, $arrayD);

/* $res は以下のとおり:
[
    [0] => [
            [id] => 48c2570e-dfa8-4c32-a35e-0d71cbdd56cb
            [name] => mysql raleigh-workshop-08 < 2008-09-05.sql
            [description] => Importing an sql dump
        ]
    [1] => [
            [id] => 48c257a8-cf7c-4af2-ac2f-114ecbdd56cb
            [name] => pbpaste | grep -i Unpaid | pbcopy
            [description] => Remove all lines that say "Unpaid".
        ]
    [2] => 4
    [3] => test array
    [cats] => felines
    [people] => 1267
    [dog] => angry
]
*/

static Hash::numeric(array $data)

戻り値の型: boolean

配列内のすべての値が数値であるかをチェックします:

php

$data = ['one'];
$res = Hash::numeric(array_keys($data));
// $res は true

$data = [1 => 'one'];
$res = Hash::numeric($data);
// $res は false

static Hash:😗*dimensions **(array $data)

戻り値の型: integer

配列の次元数を数えます。このメソッドは配列の１つ目の要素だけを見て次元を判定します:

php

$data = ['one', '2', 'three'];
$result = Hash::dimensions($data);
// $result == 1

$data = ['1' => '1.1', '2', '3'];
$result = Hash::dimensions($data);
// $result == 1

$data = ['1' => ['1.1' => '1.1.1'], '2', '3' => ['3.1' => '3.1.1']];
$result = Hash::dimensions($data);
// $result == 2

$data = ['1' => '1.1', '2', '3' => ['3.1' => '3.1.1']];
$result = Hash::dimensions($data);
// $result == 1


$data = ['1' => ['1.1' => '1.1.1'], '2', '3' => ['3.1' => ['3.1.1' => '3.1.1.1']]];
$result = Hash::countDim($data);
// $result == 2

static Hash::maxDimensions(array $data)

Hash::dimensions() に似ていますが、このメソッドは配列内にあるもっとも大きな次元数を返します:

php

$data = ['1' => '1.1', '2', '3' => ['3.1' => '3.1.1']];
$result = Hash::dimensions($data, true);
// $result == 2

$data = ['1' => ['1.1' => '1.1.1'], '2', '3' => ['3.1' => ['3.1.1' => '3.1.1.1']]];
$result = Hash::countDim($data, true);
// $result == 3

static Hash::map(array $data, $path, $function)

$path で抽出し、各要素に $function を割り当て（map）ることで新たな配列を作ります。このメソッドでは式とマッチャーの両方を使うことができます。

static Hash::reduce(array $data, $path, $function)

$path で抽出し、抽出結果を $function で縮小（reduce）することでを単一の値を作ります。このメソッドでは式とマッチャーの両方を使うことができます。

static Hash::sort(array $data, $path, $dir, $type = 'regular')

戻り値の型: array

Hash Path Syntax によって、どの次元のどの値によってでもソートすることができます。このメソッドでは式のみがサポートされます:

php

$a = [
    0 => ['Person' => ['name' => 'Jeff']],
    1 => ['Shirt' => ['color' => 'black']],
];
$result = Hash::sort($a, '{n}.Person.name', 'asc');
/* $result は以下のとおり:
    [
        [0] => [
                [Shirt] => [
                        [color] => black
                    ]
            ]
        [1] => [
                [Person] => [
                        [name] => Jeff
                    ]
            ]
    ]
*/

$dir には asc もしくは desc を指定することができます。 $type には次のいずれかを指定することができます。

regular : 通常のソート。
numeric : 数値とみなしてソート。
string : 文字列としてソート。
natural : ヒューマン・フレンドリー・ソート。例えば、 foo10 が foo2 の下に配置される。

Added in version 2.8

$type オプションは、配列に対応しました。 ignoreCase オプションは、大文字小文字の区別しないソートを有効にします。

static Hash::diff(array $data, array $compare)

戻り値の型: array

２つの配列の差分を計算します:

php

$a = [
    0 => ['name' => 'main'],
    1 => ['name' => 'about'],
];
$b = [
    0 => ['name' => 'main'],
    1 => ['name' => 'about'],
    2 => ['name' => 'contact'],
];

$result = Hash::diff($a, $b);
/* $result は以下のとおり:
    [
        [2] => [
                [name] => contact
            ]
    ]
*/

static Hash::mergeDiff(array $data, array $compare)

戻り値の型: array

この関数は２つの配列をマージし、差分は、その結果の配列の下部に push します。

例１ :

php

$array1 = ['ModelOne' => ['id' => 1001, 'field_one' => 'a1.m1.f1', 'field_two' => 'a1.m1.f2']];
$array2 = ['ModelOne' => ['id' => 1003, 'field_one' => 'a3.m1.f1', 'field_two' => 'a3.m1.f2', 'field_three' => 'a3.m1.f3']];
$res = Hash::mergeDiff($array1, $array2);

/* $res は以下のとおり:
    [
        [ModelOne] => [
                [id] => 1001
                [field_one] => a1.m1.f1
                [field_two] => a1.m1.f2
                [field_three] => a3.m1.f3
            ]
    ]
*/

例２ :

php

$array1 = ['a' => 'b', 1 => 20938, 'c' => 'string'];
$array2 = ['b' => 'b', 3 => 238, 'c' => 'string', ['extra_field']];
$res = Hash::mergeDiff($array1, $array2);
/* $res は以下のとおり:
    [
        [a] => b
        [1] => 20938
        [c] => string
        [b] => b
        [3] => 238
        [4] => [
                [0] => extra_field
            ]
    ]
*/

static Hash::normalize(array $data, $assoc = true)

戻り値の型: array

配列を正規化します。 $assoc が true なら、連想配列へと正規化された配列が返ります。値を持つ数値キーは null を持つ文字列キーへと変換されます。配列を正規化すると、 Hash::merge() で扱いやすくなります:

php

$a = ['Tree', 'CounterCache',
    'Upload' => [
        'folder' => 'products',
        'fields' => ['image_1_id', 'image_2_id'],
    ],
];
$result = Hash::normalize($a);
/* $result は以下のとおり:
    [
        [Tree] => null
        [CounterCache] => null
        [Upload] => [
                [folder] => products
                [fields] => [
                        [0] => image_1_id
                        [1] => image_2_id
                    ]
            ]
    ]
*/

$b = [
    'Cacheable' => ['enabled' => false],
    'Limit',
    'Bindable',
    'Validator',
    'Transactional',
];
$result = Hash::normalize($b);
/* $result は以下のとおり:
    [
        [Cacheable] => [
                [enabled] => false
            ]

        [Limit] => null
        [Bindable] => null
        [Validator] => null
        [Transactional] => null
    ]
*/

static Hash::nest(array $data, array $options = [])

平坦な配列から、多次元配列もしくはスレッド状（threaded）の構造化データを生成します。 Model::find('threaded') のようなメソッドで使われます。

オプション:

children : 子の配列のために使われる戻り値のキー名。デフォルトは 'children'。
idPath : 各要素を識別するためのキーを指すパス。 Hash::extract() と同様に指定する。デフォルトは {n}.$alias.id
parentPath : 各要素の親を識別するためのキーを指すパス。 Hash::extract() と同様に指定する。デフォルトは {n}.$alias.parent_id
root : 最上位となる要素の id 。

例:

php

$data = [
    ['ModelName' => ['id' => 1, 'parent_id' => null]],
    ['ModelName' => ['id' => 2, 'parent_id' => 1]],
    ['ModelName' => ['id' => 3, 'parent_id' => 1]],
    ['ModelName' => ['id' => 4, 'parent_id' => 1]],
    ['ModelName' => ['id' => 5, 'parent_id' => 1]],
    ['ModelName' => ['id' => 6, 'parent_id' => null]],
    ['ModelName' => ['id' => 7, 'parent_id' => 6]],
    ['ModelName' => ['id' => 8, 'parent_id' => 6]],
    ['ModelName' => ['id' => 9, 'parent_id' => 6]],
    ['ModelName' => ['id' => 10, 'parent_id' => 6]],
];

$result = Hash::nest($data, ['root' => 6]);
/* $result は以下のとおり:
[
        (int) 0 => [
            'ModelName' => [
                'id' => (int) 6,
                'parent_id' => null
            ],
            'children' => [
                (int) 0 => [
                    'ModelName' => [
                        'id' => (int) 7,
                        'parent_id' => (int) 6
                    ],
                    'children' => []
                ],
                (int) 1 => [
                    'ModelName' => [
                        'id' => (int) 8,
                        'parent_id' => (int) 6
                    ],
                    'children' => []
                ],
                (int) 2 => [
                    'ModelName' => [
                        'id' => (int) 9,
                        'parent_id' => (int) 6
                    ],
                    'children' => []
                ],
                (int) 3 => [
                    'ModelName' => [
                        'id' => (int) 10,
                        'parent_id' => (int) 6
                    ],
                    'children' => []
                ]
            ]
        ]
    ]
    */

Hash ​

Hash パス構文 ​

式の種類 ​

属性の絞り込み種別 ​

Hash

Hash パス構文

式の種類

属性の絞り込み種別