> ## 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');
// ['山田太郎', '鈴木花子']

// 세 번째 인수로 키를 지정
$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()`는 컬렉션에의 입구가 되는 가장 중요한 헬퍼입니다. 자세한 내용은 [컬렉션](/ko/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>


## Related topics

- [파사드](/ko/facades.md)
- [Fluent 클래스](/ko/advanced/fluent.md)
- [로깅](/ko/logging.md)
- [캐시](/ko/cache.md)
- [세션](/ko/session.md)