ヘルパー

はじめに
利用可能なメソッド
その他のユーティリティ

#はじめに

Laravel にはさまざまなグローバルの「ヘルパー」PHP関数が含まれています。これらの多くはフレームワーク自身で使用されていますが、便利だと感じた場合は自分のアプリケーションでも自由に使えます。

#利用可能なメソッド

#配列とオブジェクト

#その他

#配列とオブジェクト

#`Arr::accessible()` {.collection-method .first-collection-method}

Arr::accessible メソッドは、指定された値が配列アクセス可能かどうかを判定します：

use Illuminate\Support\Arr;
use Illuminate\Support\Collection;

$isAccessible = Arr::accessible(['a' => 1, 'b' => 2]);

// true

$isAccessible = Arr::accessible(new Collection);

// true

$isAccessible = Arr::accessible('abc');

// false

$isAccessible = Arr::accessible(new stdClass);

// false

#`Arr::add()` {.collection-method}

Arr::add メソッドは、指定したキーが配列に存在しないか null の場合に、キーと値のペアを配列に追加します：

use Illuminate\Support\Arr;

$array = Arr::add(['name' => 'Desk'], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

$array = Arr::add(['name' => 'Desk', 'price' => null], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

#`Arr::collapse()` {.collection-method}

Arr::collapse メソッドは、配列の配列を単一の配列にまとめます：

use Illuminate\Support\Arr;

$array = Arr::collapse([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);

// [1, 2, 3, 4, 5, 6, 7, 8, 9]

#`Arr::crossJoin()` {.collection-method}

Arr::crossJoin メソッドは、指定した配列同士の直積（カルテシアン積）を返します。すべての組み合わせを含みます：

use Illuminate\Support\Arr;

$matrix = Arr::crossJoin([1, 2], ['a', 'b']);

/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/

$matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);

/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

#`Arr::divide()` {.collection-method}

Arr::divide メソッドは、与えられた配列のキーと値をそれぞれ別の配列として返します：

use Illuminate\Support\Arr;

[$keys, $values] = Arr::divide(['name' => 'Desk']);

// $keys: ['name']

// $values: ['Desk']

#`Arr::dot()` {.collection-method}

Arr::dot メソッドは、多次元配列を「ドット」表記を使った単一レベルの配列に変換します：

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

$flattened = Arr::dot($array);

// ['products.desk.price' => 100]

#`Arr::except()` {.collection-method}

Arr::except メソッドは、指定したキーのペアを配列から除外します：

use Illuminate\Support\Arr;

$array = ['name' => 'Desk', 'price' => 100];

$filtered = Arr::except($array, ['price']);

// ['name' => 'Desk']

#`Arr::exists()` {.collection-method}

Arr::exists メソッドは、指定したキーが配列に存在するかどうかをチェックします：

use Illuminate\Support\Arr;

$array = ['name' => 'John Doe', 'age' => 17];

$exists = Arr::exists($array, 'name');

// true

$exists = Arr::exists($array, 'salary');

// false

#`Arr::first()` {.collection-method}

Arr::first メソッドは、指定した条件を満たす配列の最初の要素を返します：

use Illuminate\Support\Arr;

$array = [100, 200, 300];

$first = Arr::first($array, function (int $value, int $key) {
    return $value >= 150;
});

// 200

条件を満たす要素がない場合に返すデフォルト値を、第3引数として渡すこともできます：

use Illuminate\Support\Arr;

$first = Arr::first($array, $callback, $default);

#`Arr::flatten()` {.collection-method}

Arr::flatten メソッドは、多次元配列を単一レベルの配列に平坦化します：

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];

$flattened = Arr::flatten($array);

// ['Joe', 'PHP', 'Ruby']

#`Arr::forget()` {.collection-method}

Arr::forget メソッドは、「ドット」表記を使って深くネストされた配列から指定したキーを削除します：

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

Arr::forget($array, 'products.desk');

// ['products' => []]

#`Arr::get()` {.collection-method}

Arr::get メソッドは、「ドット」表記を使って深くネストされた配列から値を取得します：

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

$price = Arr::get($array, 'products.desk.price');

// 100

Arr::get メソッドは、指定したキーが存在しない場合に返すデフォルト値も受け付けます：

use Illuminate\Support\Arr;

$discount = Arr::get($array, 'products.desk.discount', 0);

// 0

#`Arr::has()` {.collection-method}

Arr::has メソッドは、「ドット」表記を使って配列に指定したキーまたはキー群が存在するかをチェックします：

use Illuminate\Support\Arr;

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$contains = Arr::has($array, 'product.name');

// true

$contains = Arr::has($array, ['product.price', 'product.discount']);

// false

#`Arr::hasAny()` {.collection-method}

Arr::hasAny メソッドは、「ドット」表記を使って配列に指定したキー群のうちいずれかが存在するかをチェックします：

use Illuminate\Support\Arr;

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$contains = Arr::hasAny($array, 'product.name');

// true

$contains = Arr::hasAny($array, ['product.name', 'product.discount']);

// true

$contains = Arr::hasAny($array, ['category', 'product.discount']);

// false

#`Arr::isAssoc()` {.collection-method}

Arr::isAssoc メソッドは、与えられた配列が連想配列である場合に true を返します。配列は、0から始まる連続した数値キーを持たない場合に「連想配列」と見なされます：

use Illuminate\Support\Arr;

$isAssoc = Arr::isAssoc(['product' => ['name' => 'Desk', 'price' => 100]]);

// true

$isAssoc = Arr::isAssoc([1, 2, 3]);

// false

#`Arr::isList()` {.collection-method}

Arr::isList メソッドは、与えられた配列のキーが0から始まる連続した整数である場合に true を返します:

use Illuminate\Support\Arr;

$isList = Arr::isList(['foo', 'bar', 'baz']);

// true

$isList = Arr::isList(['product' => ['name' => 'Desk', 'price' => 100]]);

// false

#`Arr::join()` {.collection-method}

Arr::join メソッドは、配列の要素を文字列で結合します。第2引数で区切り文字を指定でき、第3引数で最後の要素の前に使う区切り文字を指定できます：

use Illuminate\Support\Arr;

$array = ['Tailwind', 'Alpine', 'Laravel', 'Livewire'];

$joined = Arr::join($array, ', ');

// Tailwind, Alpine, Laravel, Livewire

$joined = Arr::join($array, ', ', ' and ');

// Tailwind, Alpine, Laravel and Livewire

#`Arr::keyBy()` {.collection-method}

Arr::keyBy メソッドは、指定したキーで配列をキー付けします。同じキーを持つ複数の要素がある場合は、最後の要素だけが新しい配列に残ります：

use Illuminate\Support\Arr;

$array = [
    ['product_id' => 'prod-100', 'name' => 'Desk'],
    ['product_id' => 'prod-200', 'name' => 'Chair'],
];

$keyed = Arr::keyBy($array, 'product_id');

/*
    [
        'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

#`Arr::last()` {.collection-method}

Arr::last メソッドは、指定した条件を満たす配列の最後の要素を返します：

use Illuminate\Support\Arr;

$array = [100, 200, 300, 110];

$last = Arr::last($array, function (int $value, int $key) {
    return $value >= 150;
});

// 300

メソッドの第3引数にデフォルト値を渡せます。条件を満たす値がない場合、この値が返されます：

use Illuminate\Support\Arr;

$last = Arr::last($array, $callback, $default);

#`Arr::map()` {.collection-method}

Arr::map メソッドは配列をループし、各値とキーをコールバックに渡します。配列の値はコールバックの返り値で置き換えられます：

use Illuminate\Support\Arr;

$array = ['first' => 'james', 'last' => 'kirk'];

$mapped = Arr::map($array, function (string $value, string $key) {
    return ucfirst($value);
});

// ['first' => 'James', 'last' => 'Kirk']

#`Arr::mapWithKeys()` {.collection-method}

Arr::mapWithKeys メソッドは配列をループし、各値をコールバックに渡します。コールバックは単一のキーと値のペアを含む連想配列を返す必要があります：

use Illuminate\Support\Arr;

$array = [
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => '[email protected]',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => '[email protected]',
    ]
];

$mapped = Arr::mapWithKeys($array, function (array $item, int $key) {
    return [$item['email'] => $item['name']];
});

/*
    [
        '[email protected]' => 'John',
        '[email protected]' => 'Jane',
    ]
*/

#`Arr::only()` {.collection-method}

Arr::only メソッドは、指定したキーと値のペアだけを配列から返します：

use Illuminate\Support\Arr;

$array = ['name' => 'Desk', 'price' => 100, 'orders' => 10];

$slice = Arr::only($array, ['name', 'price']);

// ['name' => 'Desk', 'price' => 100]

#`Arr::pluck()` {.collection-method}

Arr::pluck メソッドは、配列から指定したキーのすべての値を取得します：

use Illuminate\Support\Arr;

$array = [
    ['developer' => ['id' => 1, 'name' => 'Taylor']],
    ['developer' => ['id' => 2, 'name' => 'Abigail']],
];

$names = Arr::pluck($array, 'developer.name');

// ['Taylor', 'Abigail']

結果のリストのキーを指定することもできます：

use Illuminate\Support\Arr;

$names = Arr::pluck($array, 'developer.name', 'developer.id');

// [1 => 'Taylor', 2 => 'Abigail']

#`Arr::prepend()` {.collection-method}

Arr::prepend メソッドは、配列の先頭にアイテムを追加します：

use Illuminate\Support\Arr;

$array = ['one', 'two', 'three', 'four'];

$array = Arr::prepend($array, 'zero');

// ['zero', 'one', 'two', 'three', 'four']

必要に応じて、値に使うキーを指定できます：

use Illuminate\Support\Arr;

$array = ['price' => 100];

$array = Arr::prepend($array, 'Desk', 'name');

// ['name' => 'Desk', 'price' => 100]

#`Arr::prependKeysWith()` {.collection-method}

Arr::prependKeysWith メソッドは、連想配列のすべてのキー名に指定したプレフィックスを付けて返します：

use Illuminate\Support\Arr;

$array = [
    'name' => 'Desk',
    'price' => 100,
];

$keyed = Arr::prependKeysWith($array, 'product.');

/*
    [
        'product.name' => 'Desk',
        'product.price' => 100,
    ]
*/

#`Arr::pull()` {.collection-method}

Arr::pull メソッドは、配列からキーと値のペアを取得し、同時に削除します：

use Illuminate\Support\Arr;

$array = ['name' => 'Desk', 'price' => 100];

$name = Arr::pull($array, 'name');

// $name: Desk

// $array: ['price' => 100]

キーが存在しない場合に返すデフォルト値を第3引数に渡せます：

use Illuminate\Support\Arr;

$value = Arr::pull($array, $key, $default);

#`Arr::query()` {.collection-method}

Arr::query メソッドは、配列をクエリ文字列に変換します：

use Illuminate\Support\Arr;

$array = [
    'name' => 'Taylor',
    'order' => [
        'column' => 'created_at',
        'direction' => 'desc'
    ]
];

Arr::query($array);

// name=Taylor&order[column]=created_at&order[direction]=desc

#`Arr::random()` {.collection-method}

Arr::random メソッドは、配列からランダムな値を返します：

use Illuminate\Support\Arr;

$array = [1, 2, 3, 4, 5];

$random = Arr::random($array);

// 4 - （ランダムに取得）

返すアイテム数を第2引数で指定できます。この場合、1つでも配列で返されます：

use Illuminate\Support\Arr;

$items = Arr::random($array, 2);

// [2, 5] - （ランダムに取得）

#`Arr::set()` {.collection-method}

Arr::set メソッドは、"dot" 表記を使って多次元配列の値を設定します：

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

Arr::set($array, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

#`Arr::shuffle()` {.collection-method}

Arr::shuffle メソッドは、配列の要素をランダムにシャッフルします：

use Illuminate\Support\Arr;

$array = Arr::shuffle([1, 2, 3, 4, 5]);

// [3, 2, 5, 1, 4] - （ランダムに生成）

#`Arr::sort()` {.collection-method}

Arr::sort メソッドは、配列を値で昇順にソートします：

use Illuminate\Support\Arr;

$array = ['Desk', 'Table', 'Chair'];

$sorted = Arr::sort($array);

// ['Chair', 'Desk', 'Table']

クロージャの結果で配列をソートすることもできます：

use Illuminate\Support\Arr;

$array = [
    ['name' => 'Desk'],
    ['name' => 'Table'],
    ['name' => 'Chair'],
];

$sorted = array_values(Arr::sort($array, function (array $value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Chair'],
        ['name' => 'Desk'],
        ['name' => 'Table'],
    ]
*/

#`Arr::sortDesc()` {.collection-method}

Arr::sortDesc メソッドは、配列を値で降順にソートします：

use Illuminate\Support\Arr;

$array = ['Desk', 'Table', 'Chair'];

$sorted = Arr::sortDesc($array);

// ['Table', 'Desk', 'Chair']

クロージャの結果で配列をソートすることもできます：

use Illuminate\Support\Arr;

$array = [
    ['name' => 'Desk'],
    ['name' => 'Table'],
    ['name' => 'Chair'],
];

$sorted = array_values(Arr::sortDesc($array, function (array $value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Table'],
        ['name' => 'Desk'],
        ['name' => 'Chair'],
    ]
*/

#`Arr::sortRecursive()` {.collection-method}

Arr::sortRecursive メソッドは、数値添字のサブ配列は sort 関数で、連想サブ配列は ksort 関数で再帰的にソートします：

use Illuminate\Support\Arr;

$array = [
    ['Roman', 'Taylor', 'Li'],
    ['PHP', 'Ruby', 'JavaScript'],
    ['one' => 1, 'two' => 2, 'three' => 3],
];

$sorted = Arr::sortRecursive($array);

/*
    [
        ['JavaScript', 'PHP', 'Ruby'],
        ['one' => 1, 'three' => 3, 'two' => 2],
        ['Li', 'Roman', 'Taylor'],
    ]
*/

結果を降順でソートしたい場合は、Arr::sortRecursiveDesc メソッドを使えます。

$sorted = Arr::sortRecursiveDesc($array);

#`Arr::take()` {.collection-method}

Arr::take メソッドは、指定した数のアイテムを含む新しい配列を返します：

use Illuminate\Support\Arr;

$array = [0, 1, 2, 3, 4, 5];

$chunk = Arr::take($array, 3);

// [0, 1, 2]

負の整数を渡すと、配列の末尾から指定数のアイテムを取得します：

$array = [0, 1, 2, 3, 4, 5];

$chunk = Arr::take($array, -2);

// [4, 5]

#`Arr::toCssClasses()` {.collection-method}

Arr::toCssClasses メソッドは条件に応じて CSS クラス文字列を生成します。配列のキーに追加したいクラス名を、値に真偽値の式を指定します。数値キーの要素は常に含まれます：

use Illuminate\Support\Arr;

$isActive = false;
$hasError = true;

$array = ['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError];

$classes = Arr::toCssClasses($array);

/*
    'p-4 bg-red'
*/

#`Arr::toCssStyles()` {.collection-method}

Arr::toCssStyles メソッドは条件に応じて CSS スタイル文字列を生成します。配列のキーに追加したいスタイルを、値に真偽値の式を指定します。数値キーの要素は常に含まれます：

use Illuminate\Support\Arr;

$hasColor = true;

$array = ['background-color: blue', 'color: blue' => $hasColor];

$classes = Arr::toCssStyles($array);

/*
    'background-color: blue; color: blue;'
*/

このメソッドは、Bladeコンポーネントの属性バッグにクラスをマージする方法や @class のBladeディレクティブといったLaravelの機能を支えています。

#`Arr::undot()` {.collection-method}

Arr::undot メソッドは、"dot" 表記の一次元配列を多次元配列に展開します：

use Illuminate\Support\Arr;

$array = [
    'user.name' => 'Kevin Malone',
    'user.occupation' => 'Accountant',
];

$array = Arr::undot($array);

// ['user' => ['name' => 'Kevin Malone', 'occupation' => 'Accountant']]

#`Arr::where()` {.collection-method}

Arr::where メソッドは、指定したクロージャで配列をフィルタリングします：

use Illuminate\Support\Arr;

$array = [100, '200', 300, '400', 500];

$filtered = Arr::where($array, function (string|int $value, int $key) {
    return is_string($value);
});

// [1 => '200', 3 => '400']

#`Arr::whereNotNull()` {.collection-method}

Arr::whereNotNull メソッドは、配列からすべての null 値を除外します：

use Illuminate\Support\Arr;

$array = [0, null];

$filtered = Arr::whereNotNull($array);

// [0 => 0]

#`Arr::wrap()` {.collection-method}

Arr::wrap メソッドは、渡された値を配列でラップします。すでに配列の場合はそのまま返します：

use Illuminate\Support\Arr;

$string = 'Laravel';

$array = Arr::wrap($string);

// ['Laravel']

渡された値が null の場合は空配列を返します：

use Illuminate\Support\Arr;

$array = Arr::wrap(null);

// []

#`data_fill()` {.collection-method}

data_fill 関数は、"dot" 表記を使ってネストされた配列やオブジェクトの欠損値を設定します：

$data = ['products' => ['desk' => ['price' => 100]]];

data_fill($data, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 100]]]

data_fill($data, 'products.desk.discount', 10);

// ['products' => ['desk' => ['price' => 100, 'discount' => 10]]]

この関数はワイルドカードとしてアスタリスクも受け付け、対象を適切に埋めます：

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2'],
    ],
];

data_fill($data, 'products.*.price', 200);

/*
    [
        'products' => [
            ['name' => 'Desk 1', 'price' => 100],
            ['name' => 'Desk 2', 'price' => 200],
        ],
    ]
*/

#`data_get()` {.collection-method}

data_get 関数は、ドット記法を使ってネストされた配列やオブジェクトから値を取得します：

$data = ['products' => ['desk' => ['price' => 100]]];

$price = data_get($data, 'products.desk.price');

// 100

data_get 関数は、指定したキーが見つからなかった場合に返すデフォルト値も受け取れます：

$discount = data_get($data, 'products.desk.discount', 0);

// 0

この関数はアスタリスクを使ったワイルドカードも受け付け、配列やオブジェクトの任意のキーを対象にできます：

$data = [
    'product-one' => ['name' => 'Desk 1', 'price' => 100],
    'product-two' => ['name' => 'Desk 2', 'price' => 150],
];

data_get($data, '*.name');

// ['Desk 1', 'Desk 2'];

#`data_set()` {.collection-method}

data_set 関数は、ドット記法を使ってネストされた配列やオブジェクトに値を設定します：

$data = ['products' => ['desk' => ['price' => 100]]];

data_set($data, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

この関数もアスタリスクを使ったワイルドカードを受け付け、対象に応じて値を設定します：

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2', 'price' => 150],
    ],
];

data_set($data, 'products.*.price', 200);

/*
    [
        'products' => [
            ['name' => 'Desk 1', 'price' => 200],
            ['name' => 'Desk 2', 'price' => 200],
        ],
    ]
*/

デフォルトでは既存の値は上書きされます。存在しない場合のみ値を設定したい場合は、関数の第4引数に false を渡してください：

$data = ['products' => ['desk' => ['price' => 100]]];

data_set($data, 'products.desk.price', 200, overwrite: false);

// ['products' => ['desk' => ['price' => 100]]]

#`data_forget()` {.collection-method}

data_forget 関数は、ドット記法を使ってネストされた配列やオブジェクトから値を削除します：

$data = ['products' => ['desk' => ['price' => 100]]];

data_forget($data, 'products.desk.price');

// ['products' => ['desk' => []]]

この関数もアスタリスクを使ったワイルドカードを受け付け、対象に応じて値を削除します：

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2', 'price' => 150],
    ],
];

data_forget($data, 'products.*.price');

/*
    [
        'products' => [
            ['name' => 'Desk 1'],
            ['name' => 'Desk 2'],
        ],
    ]
*/

#`head()` {.collection-method}

head 関数は、指定した配列の最初の要素を返します：

$array = [100, 200, 300];

$first = head($array);

// 100

#`last()` {.collection-method}

last 関数は、指定した配列の最後の要素を返します：

$array = [100, 200, 300];

$last = last($array);

// 300

#Numbers

#`Number::abbreviate()` {.collection-method}

Number::abbreviate メソッドは、与えられた数値を単位の略称付きで人間に読みやすい形式で返します：

use Illuminate\Support\Number;

$number = Number::abbreviate(1000);

// 1K

$number = Number::abbreviate(489939);

// 490K

$number = Number::abbreviate(1230000, precision: 2);

// 1.23M

#`Number::clamp()` {.collection-method}

Number::clamp メソッドは、指定した範囲内に数値を収めます。数値が最小値より小さい場合は最小値を、最大値より大きい場合は最大値を返します：

use Illuminate\Support\Number;

$number = Number::clamp(105, min: 10, max: 100);

// 100

$number = Number::clamp(5, min: 10, max: 100);

// 10

$number = Number::clamp(10, min: 10, max: 100);

// 10

$number = Number::clamp(20, min: 10, max: 100);

// 20

#`Number::currency()` {.collection-method}

Number::currency メソッドは、与えられた値を通貨表現の文字列として返します：

use Illuminate\Support\Number;

$currency = Number::currency(1000);

// $1,000

$currency = Number::currency(1000, in: 'EUR');

// €1,000

$currency = Number::currency(1000, in: 'EUR', locale: 'de');

// 1.000 €

#`Number::fileSize()` {.collection-method}

Number::fileSize メソッドは、与えられたバイト数をファイルサイズの文字列表現として返します：

use Illuminate\Support\Number;

$size = Number::fileSize(1024);

// 1 KB

$size = Number::fileSize(1024 * 1024);

// 1 MB

$size = Number::fileSize(1024, precision: 2);

// 1.00 KB

#`Number::forHumans()` {.collection-method}

Number::forHumans メソッドは、与えられた数値を人間に読みやすい形式で返します：

use Illuminate\Support\Number;

$number = Number::forHumans(1000);

// 1 thousand

$number = Number::forHumans(489939);

// 490 thousand

$number = Number::forHumans(1230000, precision: 2);

// 1.23 million

#`Number::format()` {.collection-method}

Number::format メソッドは、与えられた数値をロケールに応じた文字列にフォーマットします：

use Illuminate\Support\Number;

$number = Number::format(100000);

// 100,000

$number = Number::format(100000, precision: 2);

// 100,000.00

$number = Number::format(100000.123, maxPrecision: 2);

// 100,000.12

$number = Number::format(100000, locale: 'de');

// 100.000

#`Number::ordinal()` {.collection-method}

Number::ordinal メソッドは、数値の序数表現を返します：

use Illuminate\Support\Number;

$number = Number::ordinal(1);

// 1st

$number = Number::ordinal(2);

// 2nd

$number = Number::ordinal(21);

// 21st

#`Number::percentage()` {.collection-method}

Number::percentage メソッドは、与えられた値のパーセンテージ表現を文字列で返します：

use Illuminate\Support\Number;

$percentage = Number::percentage(10);

// 10%

$percentage = Number::percentage(10, precision: 2);

// 10.00%

$percentage = Number::percentage(10.123, maxPrecision: 2);

// 10.12%

$percentage = Number::percentage(10, precision: 2, locale: 'de');

// 10,00%

#`Number::spell()` {.collection-method}

Number::spell メソッドは、与えられた数値を単語の文字列に変換します：

use Illuminate\Support\Number;

$number = Number::spell(102);

// one hundred and two

$number = Number::spell(88, locale: 'fr');

// quatre-vingt-huit

after 引数は、指定した値以降の数値をすべて単語で表記するよう指定できます：

$number = Number::spell(10, after: 10);

// 10

$number = Number::spell(11, after: 10);

// eleven

until 引数は、指定した値までの数値をすべて単語で表記するよう指定できます：

$number = Number::spell(5, until: 10);

// five

$number = Number::spell(10, until: 10);

// 10

#`Number::useLocale()` {.collection-method}

Number::useLocale メソッドは、Number クラスのメソッドで数値や通貨のフォーマットに使うデフォルトのロケールをグローバルに設定します：

use Illuminate\Support\Number;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Number::useLocale('de');
}

#`Number::withLocale()` {.collection-method}

Number::withLocale メソッドは、指定したロケールでクロージャを実行し、実行後に元のロケールに戻します：

use Illuminate\Support\Number;

$number = Number::withLocale('de', function () {
    return Number::format(1500);
});

#Paths

#`app_path()` {.collection-method}

app_path 関数は、アプリケーションの app ディレクトリへの完全修飾パスを返します。app_path 関数を使用して、アプリケーションディレクトリからの相対パスにあるファイルへの完全修飾パスを生成することもできます:

$path = app_path();

$path = app_path('Http/Controllers/Controller.php');

#`base_path()` {.collection-method}

base_path 関数はアプリケーションのルートディレクトリへのフルパスを返します。base_path 関数は、プロジェクトのルートディレクトリからの相対パスを指定して特定のファイルへのフルパスを生成するためにも使用できます：

$path = base_path();

$path = base_path('vendor/bin');

#`config_path()` {.collection-method}

config_path 関数はアプリケーションの config ディレクトリへの完全なパスを返します。config_path 関数を使用して、アプリケーションの設定ディレクトリ内の特定のファイルへの完全なパスを生成することもできます：

$path = config_path();

$path = config_path('app.php');

#`database_path()` {.collection-method}

database_path 関数は、アプリケーションの database ディレクトリへの完全修飾パスを返します。database_path 関数は、データベースディレクトリ内の特定のファイルへの完全修飾パスを生成するためにも使用できます:

$path = database_path();

$path = database_path('factories/UserFactory.php');

#`lang_path()` {.collection-method}

lang_path 関数は、アプリケーションの lang ディレクトリへの絶対パスを返します。
また lang_path 関数を使用して、ディレクトリ内の特定のファイルへの絶対パスを生成できます:

$path = lang_path();

$path = lang_path('en/messages.php');

Примечание

デフォルトでは、Laravel のアプリケーションスケルトンには lang ディレクトリが含まれていません。Laravel の言語ファイルをカスタマイズしたい場合は、lang:publish Artisan コマンドで公開できます。

#`mix()` {.collection-method}

mix 関数は、バージョン管理された Mix ファイルへのパスを返します：

$path = mix('css/app.css');

#`public_path()` {.collection-method}

public_path 関数はアプリケーションの public ディレクトリへの絶対パスを返します。また、public_path 関数を使って public ディレクトリ内の特定のファイルへの絶対パスを生成できます:

$path = public_path();

$path = public_path('css/app.css');

#`resource_path()` {.collection-method}

resource_path 関数は、アプリケーションの resources ディレクトリへの完全修飾パスを返します。また、resource_path 関数を使用して、resources ディレクトリ内の特定のファイルへの完全修飾パスを生成することもできます：

$path = resource_path();

$path = resource_path('sass/app.scss');

#`storage_path()` {.collection-method}

storage_path 関数はアプリケーションの storage ディレクトリへの絶対パスを返します。storage_path 関数はまた、storage ディレクトリ内の指定したファイルへの絶対パスを生成するためにも使用できます:

$path = storage_path();

$path = storage_path('app/file.txt');

#URLs

#`action()` {.collection-method}

action 関数は、指定したコントローラーアクションの URL を生成します：

use App\Http\Controllers\HomeController;

$url = action([HomeController::class, 'index']);

メソッドがルートパラメータを受け取る場合は、第2引数に渡せます：

$url = action([UserController::class, 'profile'], ['id' => 1]);

#`asset()` {.collection-method}

asset 関数は、リクエストの現在のスキーム（HTTP または HTTPS）を使ってアセットの URL を生成します：

$url = asset('img/photo.jpg');

.env ファイルの ASSET_URL 変数を設定することで、アセット URL のホストを変更できます。Amazon S3 や他の CDN でアセットをホストする場合に便利です：

// ASSET_URL=http://example.com/assets

$url = asset('img/photo.jpg'); // http://example.com/assets/img/photo.jpg

#`route()` {.collection-method}

route 関数は、指定した名前付きルートの URL を生成します：

$url = route('route.name');

ルートがパラメータを受け取る場合は、第2引数に渡せます：

$url = route('route.name', ['id' => 1]);

デフォルトでは、route 関数は絶対URLを生成します。相対URLを生成したい場合は、関数の第3引数に false を渡せます。

$url = route('route.name', ['id' => 1], false);

#`secure_asset()` {.collection-method}

secure_asset 関数は、HTTPSを使ったアセットのURLを生成します。

$url = secure_asset('img/photo.jpg');

#`secure_url()` {.collection-method}

secure_url 関数は、指定したパスへの完全なHTTPS URLを生成します。追加のURLセグメントは第2引数で渡せます。

$url = secure_url('user/profile');

$url = secure_url('user/profile', [1]);

#`to_route()` {.collection-method}

to_route 関数は、指定した名前付きルートへのリダイレクトHTTPレスポンスを生成します。

return to_route('users.show', ['user' => 1]);

必要に応じて、リダイレクトに割り当てるHTTPステータスコードと任意の追加レスポンスヘッダーをto_routeメソッドの3番目および4番目の引数として渡すことができます:

return to_route('users.show', ['user' => 1], 302, ['X-Framework' => 'Laravel']);

#`url()` {.collection-method}

url 関数は、指定したパスへの完全なURLを生成します。

$url = url('user/profile');

$url = url('user/profile', [1]);

パスが指定されない場合は、Illuminate\Routing\UrlGenerator のインスタンスが返されます。

$current = url()->current();

$full = url()->full();

$previous = url()->previous();

#その他

#`abort()` {.collection-method}

abort 関数は HTTP例外をスローし、例外ハンドラーによってレンダリングされます。

abort(403);

例外のメッセージやブラウザに送信するカスタムHTTPレスポンスヘッダーも指定できます。

abort(403, 'Unauthorized.', $headers);

#`abort_if()` {.collection-method}

abort_if 関数は、指定したブール式が true の場合にHTTP例外をスローします。

abort_if(! Auth::user()->isAdmin(), 403);

abort と同様に、第3引数にレスポンステキスト、第4引数にカスタムレスポンスヘッダーの配列を渡せます。

#`abort_unless()` {.collection-method}

abort_unless 関数は、指定したブール式が false の場合にHTTP例外をスローします。

abort_unless(Auth::user()->isAdmin(), 403);

abort と同様に、第3引数にレスポンステキスト、第4引数にカスタムレスポンスヘッダーの配列を渡せます。

#`app()` {.collection-method}

app 関数はサービスコンテナのインスタンスを返します。

$container = app();

クラス名やインターフェイス名を渡して、コンテナから解決することもできます。

$api = app('HelpSpot\API');

#`auth()` {.collection-method}

auth 関数は認証インスタンスを返します。Auth ファサードの代わりに使えます。

$user = auth()->user();

必要に応じて、アクセスしたいガードインスタンスを指定できます。

$user = auth('admin')->user();

#`back()` {.collection-method}

back 関数は、ユーザーの直前の場所へのリダイレクトHTTPレスポンスを生成します。

return back($status = 302, $headers = [], $fallback = '/');

return back();

#`bcrypt()` {.collection-method}

bcrypt 関数は、与えられた値をBcryptでハッシュ化します。Hash ファサードの代わりに使えます。

$password = bcrypt('my-secret-password');

#`blank()` {.collection-method}

blank 関数は、与えられた値が「空」であるかどうかを判定します。

blank('');
blank('   ');
blank(null);
blank(collect());

// true

blank(0);
blank(true);
blank(false);

// false

blank の逆は filled メソッドを参照してください。

#`broadcast()` {.collection-method}

broadcast 関数は、指定したイベントをリスナーにブロードキャストします。

broadcast(new UserRegistered($user));

broadcast(new UserRegistered($user))->toOthers();

#`cache()` {.collection-method}

cache 関数は、キャッシュから値を取得できます。指定したキーが存在しない場合は、オプションのデフォルト値を返します。

$value = cache('key');

$value = cache('key', 'default');

キーと値のペアの配列を渡してキャッシュに値を追加できます。キャッシュの有効期間は秒数または期間で指定してください。

cache(['key' => 'value'], 300);

cache(['key' => 'value'], now()->addSeconds(10));

#`class_uses_recursive()` {.collection-method}

class_uses_recursive 関数は、クラスおよびその親クラスで使用されているすべてのトレイトを返します。

$traits = class_uses_recursive(App\Models\User::class);

#`collect()` {.collection-method}

collect 関数は、与えられた値からコレクションインスタンスを作成します。

$collection = collect(['taylor', 'abigail']);

#`config()` {.collection-method}

config 関数は、設定変数の値を取得します。設定値はファイル名とオプション名をドットでつなぐ「ドット記法」でアクセスできます。設定が存在しない場合はデフォルト値を返せます。

$value = config('app.timezone');

$value = config('app.timezone', $default);

キーと値のペアの配列を渡して、実行時に設定値を変更できます。ただし、この変更は現在のリクエストにのみ影響し、実際の設定ファイルは更新されません。

config(['app.debug' => true]);

#`cookie()` {.collection-method}

cookie 関数は、新しいクッキーインスタンスを作成します。

$cookie = cookie('name', 'value', $minutes);

#`csrf_field()` {.collection-method}

csrf_field 関数は、CSRFトークンの値を含むHTMLの hidden 入力フィールドを生成します。例えば、Blade構文での使用例：

{{ csrf_field() }}

#`csrf_token()` {.collection-method}

csrf_token 関数は、現在のCSRFトークンの値を取得します。

$token = csrf_token();

#`decrypt()` {.collection-method}

decrypt 関数は、与えられた値を復号します。Crypt ファサードの代わりに使えます。

$password = decrypt($value);

#`dd()` {.collection-method}

dd 関数は、与えられた変数をダンプしてスクリプトの実行を終了します。

dd($value);

dd($value1, $value2, $value3, ...);

スクリプトの実行を停止したくない場合は、代わりに dump 関数を使ってください。

#`dispatch()` {.collection-method}

dispatch 関数は、指定したジョブをLaravelのジョブキューにプッシュします。

dispatch(new App\Jobs\SendEmails);

#`dispatch_sync()` {.collection-method}

dispatch_sync 関数は、指定したジョブを同期キューにプッシュし、即座に処理します。

dispatch_sync(new App\Jobs\SendEmails);

#`dump()` {.collection-method}

dump 関数は、与えられた変数をダンプします。

dump($value);

dump($value1, $value2, $value3, ...);

変数をダンプした後にスクリプトの実行を停止したい場合は、dd 関数を使ってください。

#`encrypt()` {.collection-method}

encrypt 関数は、与えられた値を暗号化します。Crypt ファサードの代わりに使えます。

$secret = encrypt('my-secret-value');

#`env()` {.collection-method}

env 関数は、環境変数の値を取得するか、デフォルト値を返します。

$env = env('APP_ENV');

$env = env('APP_ENV', 'production');

Внимание

デプロイ時に config:cache コマンドを実行する場合、env 関数は設定ファイル内からのみ呼び出すようにしてください。設定がキャッシュされると .env ファイルは読み込まれず、env 関数はすべて null を返します。

#`event()` {.collection-method}

event 関数は、指定したイベントをリスナーにディスパッチします。

event(new UserRegistered($user));

#`fake()` {.collection-method}

fake 関数は、コンテナから Faker のシングルトンを解決します。モデルファクトリー、データベースシーディング、テスト、ビューのプロトタイピングでのフェイクデータ作成に便利です。

@for($i = 0; $i < 10; $i++)
    <dl>
        <dt>Name</dt>
        <dd>{{ fake()->name() }}</dd>

        <dt>Email</dt>
        <dd>{{ fake()->unique()->safeEmail() }}</dd>
    </dl>
@endfor

デフォルトでは、fake 関数は config/app.php の app.faker_locale 設定オプションを使用します。ただし、fake 関数にロケールを渡して明示的に指定することもできます。各ロケールはそれぞれ個別のシングルトンとして解決されます:

fake('nl_NL')->name()

#`filled()` {.collection-method}

filled 関数は、与えられた値が「空」でないかどうかを判定します。

filled(0);
filled(true);
filled(false);

// true

filled('');
filled('   ');
filled(null);
filled(collect());

// false

filled の逆は blank メソッドを参照してください。

#`info()` {.collection-method}

info 関数は、アプリケーションのログに情報を書き込みます。

info('Some helpful information!');

コンテキスト情報の配列も渡せます。

info('User login attempt failed.', ['id' => $user->id]);

#`logger()` {.collection-method}

logger 関数は、ログに debug レベルのメッセージを書き込むために使えます。

logger('Debug message');

コンテキスト情報の配列も渡せます。

logger('User has logged in.', ['id' => $user->id]);

値を渡さない場合は、logger インスタンスが返されます。

logger()->error('You are not allowed here.');

#`method_field()` {.collection-method}

method_field 関数は、フォームのHTTPメソッドを偽装するためのHTMLの hidden 入力フィールドを生成します。例えば、Blade構文での使用例：

<form method="POST">
    {{ method_field('DELETE') }}
</form>

#`now()` {.collection-method}

now 関数は、現在時刻の新しい Illuminate\Support\Carbon インスタンスを作成します。

$now = now();

#`old()` {.collection-method}

old 関数は、セッションにフラッシュされた以前の入力の値を取得します:

$value = old('value');

$value = old('value', 'default');

old 関数の第2引数として渡される「デフォルト値」はしばしば Eloquentモデルの属性であるため、Laravel では old 関数の第2引数に Eloquentモデル全体を渡すことができます。そうした場合、Laravel は old 関数の第1引数を「デフォルト値」と見なすべき Eloquent の属性名として扱います：

{{ old('name', $user->name) }}

// 以下と同じ意味です...

{{ old('name', $user) }}

#`optional()` {.collection-method}

optional 関数は任意の引数を受け取り、そのオブジェクトのプロパティやメソッドにアクセスできます。引数が null の場合は、エラーを起こさずに null を返します。

return optional($user->address)->street;

{!! old('name', optional($user)->name) !!}

optional 関数は、第2引数にクロージャも受け付けます。第1引数に渡された値が null でない場合にクロージャが呼び出されます。

return optional(User::find($id), function (User $user) {
    return $user->name;
});

#`policy()` {.collection-method}

policy メソッドは、指定したクラスのポリシーインスタンスを取得します。

$policy = policy(App\Models\User::class);

#`redirect()` {.collection-method}

redirect 関数は、リダイレクト HTTP レスポンスを返すか、引数なしで呼び出された場合はリダイレクターのインスタンスを返します。

return redirect($to = null, $status = 302, $headers = [], $https = null);

return redirect('/home');

return redirect()->route('route.name');

#`report()` {.collection-method}

report 関数は、例外ハンドラーを使って例外を報告します。

report($e);

report 関数は文字列も受け付けます。文字列が渡された場合、その文字列をメッセージとする例外を作成して報告します。

report('Something went wrong.');

#`report_if()` {.collection-method}

report_if 関数は、指定した条件が true の場合に例外ハンドラーを使って例外を報告します。

report_if($shouldReport, $e);

report_if($shouldReport, 'Something went wrong.');

#`report_unless()` {.collection-method}

report_unless 関数は、指定した条件が false の場合に例外ハンドラーを使って例外を報告します。

report_unless($reportingDisabled, $e);

report_unless($reportingDisabled, 'Something went wrong.');

#`request()` {.collection-method}

request 関数は現在のリクエストインスタンスを返すか、現在のリクエストから入力フィールドの値を取得します。

$request = request();

$value = request('key', $default);

#`rescue()` {.collection-method}

rescue 関数は指定したクロージャを実行し、その実行中に発生した例外をキャッチします。キャッチした例外はすべて例外ハンドラーに送られますが、リクエストの処理は継続されます。

return rescue(function () {
    return $this->method();
});

rescue 関数には第2引数を渡すこともできます。この引数は、クロージャの実行中に例外が発生した場合に返す「デフォルト」値になります。

return rescue(function () {
    return $this->method();
}, false);

return rescue(function () {
    return $this->method();
}, function () {
    return $this->failure();
});

rescue 関数には report 引数を渡すこともでき、例外を report 関数で報告するかどうかを制御できます。

return rescue(function () {
    return $this->method();
}, report: function (Throwable $throwable) {
    return $throwable instanceof InvalidArgumentException;
});

#`resolve()` {.collection-method}

resolve 関数は、サービスコンテナを使って指定したクラスまたはインターフェイス名のインスタンスを解決します。

$api = resolve('HelpSpot\API');

#`response()` {.collection-method}

response 関数は、レスポンスインスタンスを作成するか、レスポンスファクトリーのインスタンスを取得します。

return response('Hello World', 200, $headers);

return response()->json(['foo' => 'bar'], 200, $headers);

#`retry()` {.collection-method}

retry 関数は、指定した最大試行回数に達するまでコールバックの実行を試みます。コールバックが例外を投げなければ、その戻り値を返します。例外が投げられた場合は自動的に再試行します。最大試行回数を超えると例外がスローされます。

return retry(5, function () {
    // 5回試行し、試行間に100ms休止します...
}, 100);

試行間のスリープ時間（ミリ秒）を手動で計算したい場合は、retry 関数の第3引数にクロージャを渡せます:

use Exception;

return retry(5, function () {
    // ...
}, function (int $attempt, Exception $exception) {
    return $attempt * 100;
});

便宜上、retry 関数の最初の引数に配列を渡すことができます。この配列は、各試行間に何ミリ秒スリープするかを決定するために使用されます:

return retry([100, 200], function () {
    // 1回目の再試行で100ms、2回目で200msスリープします...
});

特定の条件でのみ再試行するには、retry 関数の4番目の引数にクロージャを渡せます。

use Exception;

return retry(5, function () {
    // ...
}, 100, function (Exception $exception) {
    return $exception instanceof RetryException;
});

#`session()` {.collection-method}

session 関数は、セッションの値を取得または設定するために使えます。

$value = session('key');

キーと値のペアを配列で渡すことで値を設定できます。

session(['chairs' => 7, 'instruments' => 3]);

引数を渡さない場合は、セッションストアのインスタンスが返されます。

$value = session()->get('key');

session()->put('key', $value);

#`tap()` {.collection-method}

tap 関数は任意の $value とクロージャという2つの引数を受け取ります。$value はクロージャに渡され、その後 tap 関数により返されます。クロージャの戻り値は無視されます：

$user = tap(User::first(), function (User $user) {
    $user->name = 'taylor';

    $user->save();
});

tap 関数にクロージャが渡されない場合、与えられた $value に対して任意のメソッドを呼び出すことができます。呼び出したメソッドの戻り値は、そのメソッドが定義上で本来何を返すかに関係なく、常に $value になります。たとえば、Eloquent の update メソッドは通常、整数を返します。しかし、tap 関数を介して update メソッドの呼び出しをチェーンすることで、そのメソッドにモデル自身を返させることができます：

$user = tap($user)->update([
    'name' => $name,
    'email' => $email,
]);

クラスに tap メソッドを追加するには、クラスに Illuminate\Support\Traits\Tappable トレイトを追加します。このトレイトの tap メソッドはクロージャを唯一の引数として受け取ります。オブジェクトのインスタンス自体がクロージャに渡され、その後 tap メソッドによって返されます：

return $user->tap(function (User $user) {
    // ...
});

#`throw_if()` {.collection-method}

throw_if 関数は、指定したブール式が true の場合に例外をスローします。

throw_if(! Auth::user()->isAdmin(), AuthorizationException::class);

throw_if(
    ! Auth::user()->isAdmin(),
    AuthorizationException::class,
    'You are not allowed to access this page.'
);

#`throw_unless()` {.collection-method}

throw_unless 関数は、指定したブール式が false の場合に例外をスローします。

throw_unless(Auth::user()->isAdmin(), AuthorizationException::class);

throw_unless(
    Auth::user()->isAdmin(),
    AuthorizationException::class,
    'You are not allowed to access this page.'
);

#`today()` {.collection-method}

today 関数は、現在の日付の新しい Illuminate\Support\Carbon インスタンスを作成します。

$today = today();

#`trait_uses_recursive()` {.collection-method}

trait_uses_recursive 関数は、指定したトレイトが使用しているすべてのトレイトを返します。

$traits = trait_uses_recursive(\Illuminate\Notifications\Notifiable::class);

#`transform()` {.collection-method}

transform 関数は、与えられた値が blank でなければクロージャを実行し、その戻り値を返します。

$callback = function (int $value) {
    return $value * 2;
};

$result = transform(5, $callback);

// 10

第3引数にデフォルト値またはクロージャを渡せます。値が blank の場合、この値が返されます。

$result = transform(null, $callback, 'The value is blank');

// The value is blank

#`validator()` {.collection-method}

validator 関数は、指定した引数で新しいバリデーターインスタンスを作成します。Validator ファサードの代わりに使えます。

$validator = validator($data, $rules, $messages);

#`value()` {.collection-method}

value 関数は渡された値を返します。ただし、クロージャを渡した場合はクロージャを実行し、その戻り値を返します。

$result = value(true);

// true

$result = value(function () {
    return false;
});

// false

value 関数には追加の引数を渡せます。最初の引数がクロージャの場合、追加の引数はクロージャに渡されます。それ以外の場合は無視されます。

$result = value(function (string $name) {
    return $name;
}, 'Taylor');

// 'Taylor'

#`view()` {.collection-method}

view 関数は、ビューインスタンスを取得します。

return view('auth.login');

#`with()` {.collection-method}

with 関数は渡された値を返します。第2引数にクロージャが渡された場合はクロージャを実行し、その戻り値を返します。

$callback = function (mixed $value) {
    return is_numeric($value) ? $value * 2 : 0;
};

$result = with(5, $callback);

// 10

$result = with(null, $callback);

// 0

$result = with(5, null);

// 5

#その他のユーティリティ

#ベンチマーク

アプリケーションの特定部分のパフォーマンスを素早くテストしたい場合があります。その際は、Benchmark サポートクラスを使って、指定したコールバックの実行にかかるミリ秒数を測定できます。

<?php

use App\Models\User;
use Illuminate\Support\Benchmark;

Benchmark::dd(fn () => User::find(1)); // 0.1 ms

Benchmark::dd([
    'Scenario 1' => fn () => User::count(), // 0.5 ms
    'Scenario 2' => fn () => User::all()->count(), // 20.0 ms
]);

デフォルトでは、指定したコールバックは1回だけ実行され、その実行時間がブラウザやコンソールに表示されます。

コールバックを複数回実行したい場合は、第2引数に実行回数を指定できます。複数回実行した場合、Benchmark クラスはすべての試行の平均実行時間を返します。

Benchmark::dd(fn () => User::count(), iterations: 10); // 0.5 ms

コールバックの実行時間を計測しつつ、コールバックの戻り値も取得したい場合は、value メソッドを使います。これは、コールバックの戻り値と実行時間（ミリ秒）を含むタプルを返します。

[$count, $duration] = Benchmark::value(fn () => User::count());

#日付

Laravel には強力な日付・時刻操作ライブラリである Carbon が含まれています。新しい Carbon インスタンスを作成するには、グローバルに利用可能な now 関数を呼び出せます。

$now = now();

または、Illuminate\Support\Carbon クラスを使って新しい Carbon インスタンスを作成できます。

use Illuminate\Support\Carbon;

$now = Carbon::now();

Carbon とその機能について詳しく知りたい場合は、公式 Carbon ドキュメントを参照してください。

#ロト

Laravel のロトクラスは、指定した確率に基づいてコールバックを実行できます。これは、受信リクエストの一部だけでコードを実行したい場合に便利です。

use Illuminate\Support\Lottery;

Lottery::odds(1, 20)
    ->winner(fn () => $user->won())
    ->loser(fn () => $user->lost())
    ->choose();

Laravelのlotteryクラスは他のLaravel機能と組み合わせて使えます。例えば、遅いクエリのうちごく一部だけを例外ハンドラーに報告したい場合などです。また、lotteryクラスは呼び出し可能なので、呼び出し可能なものを受け取る任意のメソッドにインスタンスを渡せます。

use Carbon\CarbonInterval;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Lottery;

DB::whenQueryingForLongerThan(
    CarbonInterval::seconds(2),
    Lottery::odds(1, 100)->winner(fn () => report('Querying > 2 seconds.')),
);

#ロトのテスト

Laravelはアプリケーションのlottery呼び出しを簡単にテストできるシンプルなメソッドを提供しています。

// Lotteryは常に当選します...
Lottery::alwaysWin();

// Lotteryは常に外れます...
Lottery::alwaysLose();

// Lotteryは当選と外れを繰り返し、最後に通常の動作に戻ります...
Lottery::fix([true, false]);

// Lotteryは通常の動作に戻ります...
Lottery::determineResultsNormally();

#パイプライン

LaravelのPipelineファサードは、与えられた入力を一連の呼び出し可能なクラスやクロージャ、コールバックに「パイプ」し、それぞれのクラスが入力を検査・変更しつつ次の呼び出し可能なものを呼べる便利な方法を提供します。

use Closure;
use App\Models\User;
use Illuminate\Support\Facades\Pipeline;

$user = Pipeline::send($user)
            ->through([
                function (User $user, Closure $next) {
                    // ...

                    return $next($user);
                },
                function (User $user, Closure $next) {
                    // ...

                    return $next($user);
                },
            ])
            ->then(fn (User $user) => $user);

ご覧の通り、パイプライン内の各呼び出し可能なクラスやクロージャには入力と$nextクロージャが渡されます。$nextを呼び出すとパイプラインの次の呼び出し可能なものが実行されます。これはミドルウェアに非常によく似ています。

パイプラインの最後の呼び出し可能が$nextを呼ぶと、thenメソッドに渡されたコールバックが実行されます。通常、このコールバックは単に入力を返します。

もちろん、前述の通りパイプラインにはクロージャだけでなく呼び出し可能なクラスも渡せます。クラス名を渡すと、Laravelのサービスコンテナを通じてインスタンス化され、依存性注入が可能になります。

$user = Pipeline::send($user)
            ->through([
                GenerateProfilePhoto::class,
                ActivateSubscription::class,
                SendWelcomeEmail::class,
            ])
            ->then(fn (User $user) => $user);

#Sleep

LaravelのSleepクラスはPHPのネイティブなsleepとusleep関数を軽量にラップし、テストしやすくしつつ時間操作のための開発者向けAPIを提供します。

use Illuminate\Support\Sleep;

$waiting = true;

while ($waiting) {
    Sleep::for(1)->second();

    $waiting = /* ... */;
}

Sleepクラスは様々な時間単位で操作できるメソッドを提供します。

// 90秒間処理を停止します...
Sleep::for(1.5)->minutes();

// 2秒間処理を停止します...
Sleep::for(2)->seconds();

// 500ミリ秒間処理を停止します...
Sleep::for(500)->milliseconds();

// 5,000マイクロ秒間処理を停止します...
Sleep::for(5000)->microseconds();

// 指定した時刻まで処理を停止します...
Sleep::until(now()->addMinute());

// PHPのネイティブな"sleep"関数のエイリアスです...
Sleep::sleep(2);

// PHPのネイティブな"usleep"関数のエイリアスです...
Sleep::usleep(5000);

時間単位を簡単に組み合わせるにはandメソッドを使えます。

Sleep::for(1)->second()->and(10)->milliseconds();

#Sleepのテスト

SleepクラスやPHPのネイティブなsleep関数を使うコードをテストすると、テストの実行が一時停止します。これによりテストスイートが大幅に遅くなります。例えば、以下のコードをテストするとします。

$waiting = /* ... */;

$seconds = 1;

while ($waiting) {
    Sleep::for($seconds++)->seconds();

    $waiting = /* ... */;
}

通常、このコードのテストは少なくとも1秒かかります。幸いなことに、Sleepクラスはスリープを「偽装」できるため、テストを高速に保てます。

public function test_it_waits_until_ready()
{
    Sleep::fake();

    // ...
}

Sleepクラスを偽装すると、実際の処理停止がスキップされ、テストが大幅に高速化します。

Sleepクラスを偽装した状態で、発生したはずの「スリープ」に対してアサーションを行えます。例えば、3回のスリープがそれぞれ1秒ずつ増加するコードをテストするとします。assertSequenceメソッドを使うと、テストを高速に保ちながら正しいスリープが行われたことを検証できます。

public function test_it_checks_if_ready_four_times()
{
    Sleep::fake();

    // ...

    Sleep::assertSequence([
        Sleep::for(1)->second(),
        Sleep::for(2)->seconds(),
        Sleep::for(3)->seconds(),
    ]);
}

もちろん、Sleepクラスは他にも様々なアサーションを提供しています。

use Carbon\CarbonInterval as Duration;
use Illuminate\Support\Sleep;

// スリープが3回呼ばれたことをアサートします...
Sleep::assertSleptTimes(3);

// スリープの継続時間に対してアサートします...
Sleep::assertSlept(function (Duration $duration): bool {
    return /* ... */;
}, times: 1);

// Sleepクラスが一度も呼ばれなかったことをアサートします...
Sleep::assertNeverSlept();

// Sleepが呼ばれても実際には処理停止がなかったことをアサートします...
Sleep::assertInsomniac();

アプリケーションコードで偽装スリープが発生した際に何か処理を行いたい場合、whenFakingSleepメソッドにコールバックを渡せます。以下の例ではLaravelの時間操作ヘルパーを使い、スリープ時間分だけ即座に時間を進めています。

use Carbon\CarbonInterval as Duration;

$this->freezeTime();

Sleep::fake();

Sleep::whenFakingSleep(function (Duration $duration) {
    // 偽装スリープ時に時間を進める...
    $this->travel($duration->totalMilliseconds)->milliseconds();
});

Laravelは内部で処理を一時停止する際にSleepクラスを使います。例えばretryヘルパーはスリープ時にSleepクラスを使うため、テストしやすくなっています。

#はじめに

#利用可能なメソッド

#配列とオブジェクト

#数値

#パス

#URL

#その他

#配列とオブジェクト

#Arr::accessible() {.collection-method .first-collection-method}

#Arr::add() {.collection-method}

#Arr::collapse() {.collection-method}

#Arr::crossJoin() {.collection-method}

#Arr::divide() {.collection-method}

#Arr::dot() {.collection-method}

#Arr::except() {.collection-method}

#Arr::exists() {.collection-method}

#Arr::first() {.collection-method}

#Arr::flatten() {.collection-method}

#Arr::forget() {.collection-method}

#Arr::get() {.collection-method}

#Arr::has() {.collection-method}

#Arr::hasAny() {.collection-method}

#Arr::isAssoc() {.collection-method}

#Arr::isList() {.collection-method}

#Arr::join() {.collection-method}

#Arr::keyBy() {.collection-method}

#Arr::last() {.collection-method}

#Arr::map() {.collection-method}

#Arr::mapWithKeys() {.collection-method}

#Arr::only() {.collection-method}

#Arr::pluck() {.collection-method}

#Arr::prepend() {.collection-method}

#Arr::prependKeysWith() {.collection-method}

#Arr::pull() {.collection-method}

#Arr::query() {.collection-method}

#Arr::random() {.collection-method}

#Arr::set() {.collection-method}

#Arr::shuffle() {.collection-method}

#Arr::sort() {.collection-method}

#Arr::sortDesc() {.collection-method}

#Arr::sortRecursive() {.collection-method}

#Arr::take() {.collection-method}

#Arr::toCssClasses() {.collection-method}

#Arr::toCssStyles() {.collection-method}

#Arr::undot() {.collection-method}

#Arr::where() {.collection-method}

#Arr::whereNotNull() {.collection-method}

#Arr::wrap() {.collection-method}

#data_fill() {.collection-method}

#data_get() {.collection-method}

#data_set() {.collection-method}

#data_forget() {.collection-method}

#head() {.collection-method}

#last() {.collection-method}

#Numbers

#Number::abbreviate() {.collection-method}

#Number::clamp() {.collection-method}

#Number::currency() {.collection-method}

#Number::fileSize() {.collection-method}

#Number::forHumans() {.collection-method}

#Number::format() {.collection-method}

#Number::ordinal() {.collection-method}

#Number::percentage() {.collection-method}

#Number::spell() {.collection-method}

#Number::useLocale() {.collection-method}

#Number::withLocale() {.collection-method}

#Paths

#app_path() {.collection-method}

#base_path() {.collection-method}

#config_path() {.collection-method}

#database_path() {.collection-method}

#lang_path() {.collection-method}

#mix() {.collection-method}

#public_path() {.collection-method}

#resource_path() {.collection-method}

#storage_path() {.collection-method}

#URLs

#action() {.collection-method}

#asset() {.collection-method}

#`Arr::accessible()` {.collection-method .first-collection-method}

#`Arr::add()` {.collection-method}

#`Arr::collapse()` {.collection-method}

#`Arr::crossJoin()` {.collection-method}

#`Arr::divide()` {.collection-method}

#`Arr::dot()` {.collection-method}

#`Arr::except()` {.collection-method}

#`Arr::exists()` {.collection-method}

#`Arr::first()` {.collection-method}

#`Arr::flatten()` {.collection-method}

#`Arr::forget()` {.collection-method}

#`Arr::get()` {.collection-method}

#`Arr::has()` {.collection-method}

#`Arr::hasAny()` {.collection-method}

#`Arr::isAssoc()` {.collection-method}

#`Arr::isList()` {.collection-method}

#`Arr::join()` {.collection-method}

#`Arr::keyBy()` {.collection-method}

#`Arr::last()` {.collection-method}

#`Arr::map()` {.collection-method}

#`Arr::mapWithKeys()` {.collection-method}

#`Arr::only()` {.collection-method}

#`Arr::pluck()` {.collection-method}

#`Arr::prepend()` {.collection-method}

#`Arr::prependKeysWith()` {.collection-method}

#`Arr::pull()` {.collection-method}

#`Arr::query()` {.collection-method}

#`Arr::random()` {.collection-method}

#`Arr::set()` {.collection-method}

#`Arr::shuffle()` {.collection-method}

#`Arr::sort()` {.collection-method}

#`Arr::sortDesc()` {.collection-method}

#`Arr::sortRecursive()` {.collection-method}

#`Arr::take()` {.collection-method}

#`Arr::toCssClasses()` {.collection-method}

#`Arr::toCssStyles()` {.collection-method}

#`Arr::undot()` {.collection-method}

#`Arr::where()` {.collection-method}

#`Arr::whereNotNull()` {.collection-method}

#`Arr::wrap()` {.collection-method}

#`data_fill()` {.collection-method}

#`data_get()` {.collection-method}

#`data_set()` {.collection-method}

#`data_forget()` {.collection-method}

#`head()` {.collection-method}

#`last()` {.collection-method}

#`Number::abbreviate()` {.collection-method}

#`Number::clamp()` {.collection-method}

#`Number::currency()` {.collection-method}

#`Number::fileSize()` {.collection-method}

#`Number::forHumans()` {.collection-method}

#`Number::format()` {.collection-method}

#`Number::ordinal()` {.collection-method}

#`Number::percentage()` {.collection-method}

#`Number::spell()` {.collection-method}

#`Number::useLocale()` {.collection-method}

#`Number::withLocale()` {.collection-method}

#`app_path()` {.collection-method}

#`base_path()` {.collection-method}

#`config_path()` {.collection-method}

#`database_path()` {.collection-method}

#`lang_path()` {.collection-method}

#`mix()` {.collection-method}

#`public_path()` {.collection-method}

#`resource_path()` {.collection-method}

#`storage_path()` {.collection-method}

#`action()` {.collection-method}

#`asset()` {.collection-method}

#`route()` {.collection-method}

#`secure_asset()` {.collection-method}

#`secure_url()` {.collection-method}

#`to_route()` {.collection-method}

#`url()` {.collection-method}

#`abort()` {.collection-method}

#`abort_if()` {.collection-method}

#`abort_unless()` {.collection-method}

#`app()` {.collection-method}

#`auth()` {.collection-method}

#`back()` {.collection-method}

#`bcrypt()` {.collection-method}