> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# ヘルパー関数

> Laravelが提供するグローバルヘルパー関数と Arr・Number クラスを実用例とともに解説します。

## ヘルパー関数とは

Laravelは多数のグローバルPHP関数（ヘルパー）を提供しています。フレームワーク自体が内部で使用しているものがほとんどですが、アプリケーション内でも自由に利用できます。

ヘルパーは大きく以下のカテゴリに分かれています。

* **配列・オブジェクト** — `Arr::` クラスと `data_get()` などの関数
* **数値** — `Number::` クラス
* **パス** — `app_path()`, `storage_path()` などのパス取得関数
* **URL** — `route()`, `url()`, `asset()` などのURL生成関数
* **その他** — `config()`, `collect()`, `auth()` などよく使うユーティリティ

<Info>
  ヘルパー関数は `use` 宣言不要でどこからでも呼び出せます。`Arr` や `Number` クラスを使う場合は `use Illuminate\Support\Arr;` などのインポートが必要です。
</Info>

## 配列ヘルパー（Arr クラス）

### `Arr::get()` — ドット記法でネストした値を取得

多次元配列からドット記法（`foo.bar.baz`）でネストした値を安全に取得します。キーが存在しない場合はデフォルト値を返します。

```php theme={null}
use Illuminate\Support\Arr;

$config = [
    'database' => [
        'connections' => [
            'mysql' => ['host' => '127.0.0.1', 'port' => 3306],
        ],
    ],
];

$host = Arr::get($config, 'database.connections.mysql.host');
// '127.0.0.1'

// キーが存在しない場合のデフォルト値
$charset = Arr::get($config, 'database.connections.mysql.charset', 'utf8mb4');
// 'utf8mb4'
```

<Tip>
  `data_get()` グローバル関数も同じ機能を持ちます。Eloquentのリレーションのような`Arrayable`なオブジェクトにも対応しているため、より汎用的な場面で使えます。
</Tip>

### `Arr::set()` — ネストした配列に値を設定

```php theme={null}
use Illuminate\Support\Arr;

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

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

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

### `Arr::has()` — キーの存在を確認

```php theme={null}
use Illuminate\Support\Arr;

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

$hasName = Arr::has($array, 'product.name');
// true

// 複数キーをすべて持つか確認
$hasAll = Arr::has($array, ['product.name', 'product.price']);
// true
```

### `Arr::only()` / `Arr::except()` — キーを絞り込む・除外する

リクエストデータや設定配列から必要なキーだけを取り出したり、不要なキーを除外したりするときに便利です。

```php theme={null}
use Illuminate\Support\Arr;

$user = [
    'id' => 1,
    'name' => '山田太郎',
    'email' => 'yamada@example.com',
    'password' => 'secret',
    'role' => 'admin',
];

// 必要なキーだけ取り出す
$safe = Arr::only($user, ['id', 'name', 'email']);
// ['id' => 1, 'name' => '山田太郎', 'email' => 'yamada@example.com']

// password だけ除外する
$public = Arr::except($user, ['password']);
// ['id' => 1, 'name' => '山田太郎', 'email' => '...', 'role' => 'admin']
```

### `Arr::pluck()` — ネストした配列から特定キーを抜き出す

```php theme={null}
use Illuminate\Support\Arr;

$records = [
    ['user' => ['id' => 1, 'name' => '山田太郎']],
    ['user' => ['id' => 2, 'name' => '鈴木花子']],
];

$names = Arr::pluck($records, 'user.name');
// ['山田太郎', '鈴木花子']

// 第3引数でキーを指定
$nameById = Arr::pluck($records, 'user.name', 'user.id');
// [1 => '山田太郎', 2 => '鈴木花子']
```

### `Arr::first()` / `Arr::last()` — 条件を満たす最初・最後の要素

```php theme={null}
use Illuminate\Support\Arr;

$prices = [150, 80, 200, 50, 120];

// 100以上の最初の価格
$first = Arr::first($prices, fn ($price) => $price >= 100);
// 150

// 条件を満たさない場合のデフォルト値
$first = Arr::first($prices, fn ($price) => $price >= 500, 0);
// 0

// 最後の要素（条件なし）
$last = Arr::last($prices);
// 120
```

### `Arr::flatten()` — 多次元配列を1次元に平坦化

```php theme={null}
use Illuminate\Support\Arr;

$tags = [
    'frontend' => ['html', 'css', 'javascript'],
    'backend'  => ['php', 'laravel', 'mysql'],
];

$allTags = Arr::flatten($tags);
// ['html', 'css', 'javascript', 'php', 'laravel', 'mysql']
```

### `Arr::wrap()` — 値を確実に配列にする

値が配列でない場合に配列でラップします。`null` は空配列になります。関数の引数を柔軟に受け付ける際に役立ちます。

```php theme={null}
use Illuminate\Support\Arr;

Arr::wrap('Laravel');
// ['Laravel']

Arr::wrap(['Laravel', 'PHP']);
// ['Laravel', 'PHP']

Arr::wrap(null);
// []
```

### `Arr::sort()` — 値でソート

```php theme={null}
use Illuminate\Support\Arr;

$fruits = ['banana', 'apple', 'cherry'];
$sorted = Arr::sort($fruits);
// ['apple', 'banana', 'cherry']

// クロージャでソートキーを指定
$products = [
    ['name' => 'ノートPC', 'price' => 120000],
    ['name' => 'マウス', 'price' => 3500],
    ['name' => 'キーボード', 'price' => 8000],
];

$byPrice = Arr::sort($products, fn ($product) => $product['price']);
// マウス, キーボード, ノートPC の順
```

### `Arr::dot()` / `Arr::undot()` — ドット記法に変換・復元

```php theme={null}
use Illuminate\Support\Arr;

$nested = [
    'user' => [
        'profile' => ['name' => '山田太郎', 'age' => 28],
    ],
];

$dotted = Arr::dot($nested);
// ['user.profile.name' => '山田太郎', 'user.profile.age' => 28]

// 元の構造に戻す
$restored = Arr::undot($dotted);
// ['user' => ['profile' => ['name' => '山田太郎', 'age' => 28]]]
```

### `Arr::join()` — 配列を文字列に結合

```php theme={null}
use Illuminate\Support\Arr;

$items = ['PHP', 'Laravel', 'MySQL'];

Arr::join($items, ', ');
// 'PHP, Laravel, MySQL'

// 最後の要素の前だけ別の文字列を使う
Arr::join($items, ', ', ' と ');
// 'PHP, Laravel と MySQL'
```

## `data_get()` — ネストしたデータへのアクセス

`Arr::get()` の汎用版です。配列だけでなく、オブジェクトやEloquentモデル、コレクションにも対応しています。

```php theme={null}
$users = [
    ['name' => '山田太郎', 'address' => ['city' => '東京']],
    ['name' => '鈴木花子', 'address' => ['city' => '大阪']],
];

// ドット記法でアクセス
$city = data_get($users, '0.address.city');
// '東京'

// ワイルドカードで全要素から取得
$cities = data_get($users, '*.address.city');
// ['東京', '大阪']
```

## 数値ヘルパー（Number クラス）

### `Number::format()` — 数値を読みやすい形式に

```php theme={null}
use Illuminate\Support\Number;

Number::format(1234567.89);
// '1,234,567.89'

Number::format(1234567.89, precision: 0, locale: 'ja');
// '1,234,568'
```

### `Number::currency()` — 通貨フォーマット

```php theme={null}
use Illuminate\Support\Number;

Number::currency(10000, 'JPY', locale: 'ja');
// '￥10,000'

Number::currency(29.99, 'USD');
// '$29.99'
```

### `Number::fileSize()` — ファイルサイズを人間が読める形式に

```php theme={null}
use Illuminate\Support\Number;

Number::fileSize(1024);
// '1 KB'

Number::fileSize(1024 * 1024 * 2.5);
// '2.5 MB'
```

### `Number::abbreviate()` — 大きな数を省略表記に

```php theme={null}
use Illuminate\Support\Number;

Number::abbreviate(1000);
// '1K'

Number::abbreviate(1500000);
// '1.5M'
```

### `Number::percentage()` — パーセント表示

```php theme={null}
use Illuminate\Support\Number;

Number::percentage(75.5, precision: 1);
// '75.5%'
```

## パスヘルパー

アプリケーション内のディレクトリパスを取得します。環境やデプロイ先が変わっても正しいパスを返します。

```php theme={null}
// app ディレクトリの絶対パス
app_path();
// /var/www/html/app

// app/Http/Controllers/UserController.php のパス
app_path('Http/Controllers/UserController.php');

// プロジェクトルートからの相対パス
base_path('composer.json');

// config ディレクトリ
config_path('database.php');

// database ディレクトリ
database_path('migrations');

// storage ディレクトリ
storage_path('app/uploads');

// public ディレクトリ
public_path('css/app.css');

// resources ディレクトリ
resource_path('views/welcome.blade.php');
```

## URLヘルパー

### `route()` — 名前付きルートのURL生成

```php theme={null}
// ルート定義
// Route::get('/users/{user}', [UserController::class, 'show'])->name('users.show');

// 絶対URL（デフォルト）
$url = route('users.show', ['user' => 1]);
// 'https://example.com/users/1'

// 相対URL
$url = route('users.show', ['user' => 1], false);
// '/users/1'
```

### `url()` — 任意パスの絶対URL生成

```php theme={null}
$url = url('user/profile');
// 'https://example.com/user/profile'

// URLジェネレーターインスタンスを取得
$current  = url()->current();   // 現在のURL
$full     = url()->full();      // クエリ文字列を含む現在のURL
$previous = url()->previous();  // 直前のURL
```

### `asset()` — 静的アセットのURL生成

```php theme={null}
$url = asset('img/logo.png');
// 'https://example.com/img/logo.png'
```

### `to_route()` — 名前付きルートへのリダイレクト

```php theme={null}
return to_route('users.show', ['user' => 1]);

// HTTPステータスとヘッダーも指定可能
return to_route('users.show', ['user' => 1], 302, ['X-Custom' => 'value']);
```

## その他のよく使うヘルパー

### `config()` — 設定値の取得・設定

```php theme={null}
// ドット記法で設定値を取得
$timezone = config('app.timezone');
// 'Asia/Tokyo'

// デフォルト値付き
$debug = config('app.debug', false);

// 実行時に設定を変更（その処理内限定）
config(['app.locale' => 'ja']);
```

### `collect()` — コレクションの作成

```php theme={null}
$collection = collect([1, 2, 3, 4, 5]);

$sum = collect([1, 2, 3])->sum(); // 6
```

<Tip>
  `collect()` はコレクションへの入り口となる最重要ヘルパーです。詳しくは[コレクション](/jp/collections)を参照してください。
</Tip>

### `auth()` — 認証ユーザーの取得

```php theme={null}
// 現在のユーザーを取得
$user = auth()->user();

// ログイン中か確認
if (auth()->check()) {
    // ログイン済み処理
}

// 特定のガードを使う
$admin = auth('admin')->user();
```

### `blank()` / `filled()` — 空チェック

`blank()` は `null`, 空文字, 空白のみ, 空のコレクション・配列を `true` とみなします。`filled()` はその逆です。

```php theme={null}
blank('');         // true
blank('   ');      // true
blank(null);       // true
blank(collect()); // true

blank(0);      // false（0は「空」ではない）
blank(false);  // false

filled('hello'); // true
filled(0);       // true
```

### `abort()` / `abort_if()` / `abort_unless()` — HTTP例外

```php theme={null}
// 直接HTTPエラーを投げる
abort(404);
abort(403, 'このページにアクセスする権限がありません。');

// 条件が true のときエラー
abort_if(! auth()->user()->isAdmin(), 403);

// 条件が false のときエラー
abort_unless(auth()->check(), 401);
```

### `dd()` / `dump()` — デバッグ

```php theme={null}
// 変数を出力してスクリプトを終了
dd($user);
dd($user, $orders, $config);

// スクリプトを終了せずに出力
dump($query);
```

### `dispatch()` — ジョブをキューに投入

```php theme={null}
dispatch(new App\Jobs\SendWelcomeEmail($user));

// 即時実行（同期）
dispatch_sync(new App\Jobs\GenerateReport($data));
```

### `encrypt()` / `decrypt()` — 暗号化

```php theme={null}
$encrypted = encrypt('sensitive-value');
$decrypted = decrypt($encrypted);
```

### `env()` — 環境変数の取得

```php theme={null}
$debug = env('APP_DEBUG', false);
$dbHost = env('DB_HOST', '127.0.0.1');
```

<Warning>
  `env()` はコントローラーやサービスクラスで直接呼ぶのではなく、`config/` ファイル内で呼び出して `config()` 経由でアクセスするのがベストプラクティスです。設定値のキャッシュ（`php artisan config:cache`）が有効な場合、`env()` が意図した値を返さないことがあります。
</Warning>

## collect() との使い分け

`Arr::` クラスは通常のPHP配列を対象にした操作、`collect()` はコレクションオブジェクトを返す操作です。

```php theme={null}
use Illuminate\Support\Arr;

// 配列のままで操作したい場合 → Arr クラス
$filtered = Arr::where($items, fn ($v) => $v > 0);
// 結果は配列

// メソッドチェーンで複数の操作をしたい場合 → collect()
$result = collect($items)
    ->filter(fn ($v) => $v > 0)
    ->map(fn ($v) => $v * 2)
    ->values()
    ->all();
// 結果は配列（all() で取り出す）
```

<Info>
  Eloquentの結果は自動的にコレクションとして返るため、`collect()` で包む必要はありません。単純な配列操作で十分な場合は `Arr::` を使うとシンプルに書けます。
</Info>

## まとめ

<AccordionGroup>
  <Accordion title="よく使うヘルパー一覧">
    | ヘルパー                                  | 用途             |
    | ------------------------------------- | -------------- |
    | `Arr::get($array, 'a.b.c', $default)` | ネストした配列から安全に取得 |
    | `Arr::only($array, $keys)`            | 指定キーだけ残す       |
    | `Arr::except($array, $keys)`          | 指定キーを除外する      |
    | `Arr::pluck($array, 'key')`           | 特定キーの値一覧を取得    |
    | `Arr::flatten($array)`                | 多次元配列を1次元に     |
    | `Arr::wrap($value)`                   | 確実に配列にする       |
    | `data_get($target, 'a.*.b')`          | ワイルドカードでの取得    |
    | `Number::format($n)`                  | 数値を読みやすくフォーマット |
    | `Number::currency($n, 'JPY')`         | 通貨表示           |
    | `Number::fileSize($bytes)`            | ファイルサイズ表示      |
    | `route('name', $params)`              | 名前付きルートのURL    |
    | `url('path')`                         | 絶対URL生成        |
    | `asset('path')`                       | 静的アセットURL      |
    | `config('key', $default)`             | 設定値の取得         |
    | `collect($array)`                     | コレクション作成       |
    | `auth()->user()`                      | 現在のユーザー取得      |
    | `blank($value)`                       | 空チェック          |
    | `filled($value)`                      | 空でないか確認        |
    | `abort(403)`                          | HTTP例外を投げる     |
    | `dispatch($job)`                      | ジョブをキューに投入     |
    | `env('KEY', $default)`                | 環境変数の取得        |
  </Accordion>

  <Accordion title="Arr クラス vs collect()">
    **`Arr::` クラスを使う場面**:

    * 単純な配列操作（ネストしたキーへのアクセス、キーの絞り込みなど）
    * コレクションオブジェクトのオーバーヘッドが不要な場合
    * 結果を配列のまま扱いたい場合

    **`collect()` を使う場面**:

    * 複数の操作をメソッドチェーンで表現したい場合
    * Eloquentの結果をさらに加工する場合（既にコレクション）
    * `map`, `filter`, `groupBy` などコレクション固有のメソッドを使いたい場合
  </Accordion>
</AccordionGroup>