헬퍼 함수 - Knowledge of Laravel

헬퍼 함수란

Laravel은 다수의 글로벌 PHP 함수(헬퍼)를 제공하고 있습니다. 프레임워크 자체가 내부에서 사용하고 있는 것이 대부분이지만, 애플리케이션 내에서도 자유롭게 이용할 수 있습니다. 헬퍼는 크게 다음의 카테고리로 나누어져 있습니다.

배열·객체 — Arr:: 클래스와 data_get() 등의 함수
숫자 — Number:: 클래스
경로 — app_path(), storage_path() 등의 경로 취득 함수
URL — route(), url(), asset() 등의 URL 생성 함수
기타 — config(), collect(), auth() 등 자주 사용하는 유틸리티

헬퍼 함수는 use 선언이 불필요하며 어디에서도 호출할 수 있습니다. Arr나 Number 클래스를 사용하는 경우는 use Illuminate\Support\Arr; 등의 임포트가 필요합니다.

배열 헬퍼(Arr 클래스)

`Arr::get()` — 도트 표기법으로 중첩된 값을 취득

다차원 배열에서 도트 표기법(foo.bar.baz)으로 중첩된 값을 안전하게 취득합니다. 키가 존재하지 않는 경우 기본값을 반환합니다.

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'

data_get() 글로벌 함수도 같은 기능을 갖습니다. Eloquent의 릴레이션과 같은 Arrayable한 객체에도 대응하고 있어, 더 범용적인 장면에서 사용할 수 있습니다.

`Arr::set()` — 중첩된 배열에 값을 설정

use Illuminate\Support\Arr;

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

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

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

`Arr::has()` — 키의 존재를 확인

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()` — 키를 좁히기·제외

요청 데이터나 설정 배열에서 필요한 키만 꺼내거나, 불필요한 키를 제외할 때 편리합니다.

use Illuminate\Support\Arr;

$user = [
    'id' => 1,
    'name' => '山田太郎',
    'email' => '[email protected]',
    'password' => 'secret',
    'role' => 'admin',
];

// 필요한 키만 꺼내기
$safe = Arr::only($user, ['id', 'name', 'email']);
// ['id' => 1, 'name' => '山田太郎', 'email' => '[email protected]']

// password 만 제외
$public = Arr::except($user, ['password']);
// ['id' => 1, 'name' => '山田太郎', 'email' => '...', 'role' => 'admin']

`Arr::pluck()` — 중첩된 배열에서 특정 키를 뽑아냄

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()` — 조건을 만족하는 최초·마지막 요소

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차원으로 평탄화

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은 빈 배열이 됩니다. 함수의 인수를 유연하게 받아들일 때 도움이 됩니다.

use Illuminate\Support\Arr;

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

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

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

`Arr::sort()` — 값으로 정렬

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()` — 도트 표기법으로 변환·복원

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()` — 배열을 문자열로 결합

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 모델, 컬렉션에도 대응하고 있습니다.

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

// 도트 표기법으로 접근
$city = data_get($users, '0.address.city');
// '東京'

// 와일드카드로 전체 요소에서 취득
$cities = data_get($users, '*.address.city');
// ['東京', '大阪']

숫자 헬퍼(Number 클래스)

`Number::format()` — 숫자를 읽기 쉬운 형식으로

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()` — 통화 포맷

use Illuminate\Support\Number;

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

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

`Number::fileSize()` — 파일 사이즈를 사람이 읽을 수 있는 형식으로

use Illuminate\Support\Number;

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

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

`Number::abbreviate()` — 큰 수를 생략 표기로

use Illuminate\Support\Number;

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

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

`Number::percentage()` — 퍼센트 표시

use Illuminate\Support\Number;

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

경로 헬퍼

애플리케이션 내의 디렉터리 경로를 취득합니다. 환경이나 배포 대상이 바뀌어도 올바른 경로를 반환합니다.

// 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 생성

// 라우트 정의
// 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 생성

$url = url('user/profile');
// 'https://example.com/user/profile'

// URL 제너레이터 인스턴스를 취득
$current  = url()->current();   // 현재의 URL
$full     = url()->full();      // 쿼리 문자열을 포함하는 현재의 URL
$previous = url()->previous();  // 직전의 URL

`asset()` — 정적 애셋의 URL 생성

$url = asset('img/logo.png');
// 'https://example.com/img/logo.png'

`to_route()` — 이름이 있는 라우트에의 리다이렉트

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

// HTTP 스테이터스와 헤더도 지정 가능
return to_route('users.show', ['user' => 1], 302, ['X-Custom' => 'value']);

기타 자주 사용하는 헬퍼

`config()` — 설정값의 취득·설정

// 도트 표기법으로 설정값을 취득
$timezone = config('app.timezone');
// 'Asia/Tokyo'

// 기본값 포함
$debug = config('app.debug', false);

// 실행 시에 설정을 변경(그 처리 내로 한정)
config(['app.locale' => 'ja']);

`collect()` — 컬렉션의 작성

$collection = collect([1, 2, 3, 4, 5]);

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

collect()는 컬렉션에의 입구가 되는 가장 중요한 헬퍼입니다. 자세한 내용은 컬렉션을 참조해 주십시오.

`auth()` — 인증 사용자의 취득

// 현재 사용자를 취득
$user = auth()->user();

// 로그인 중인지 확인
if (auth()->check()) {
    // 로그인 완료 처리
}

// 특정 가드를 사용
$admin = auth('admin')->user();

`blank()` / `filled()` — 빈 상태 체크

blank()는 null, 빈 문자열, 공백만, 빈 컬렉션·배열을 true로 간주합니다. filled()는 그 반대입니다.

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 예외

// 직접 HTTP 에러를 던짐
abort(404);
abort(403, '이 페이지에 접근할 권한이 없습니다.');

// 조건이 true 일 때 에러
abort_if(! auth()->user()->isAdmin(), 403);

// 조건이 false 일 때 에러
abort_unless(auth()->check(), 401);

`dd()` / `dump()` — 디버그

// 변수를 출력하고 스크립트를 종료
dd($user);
dd($user, $orders, $config);

// 스크립트를 종료하지 않고 출력
dump($query);

`dispatch()` — 잡을 큐에 투입

dispatch(new App\Jobs\SendWelcomeEmail($user));

// 즉시 실행(동기)
dispatch_sync(new App\Jobs\GenerateReport($data));

`encrypt()` / `decrypt()` — 암호화

$encrypted = encrypt('sensitive-value');
$decrypted = decrypt($encrypted);

`env()` — 환경 변수의 취득

$debug = env('APP_DEBUG', false);
$dbHost = env('DB_HOST', '127.0.0.1');

env()는 컨트롤러나 서비스 클래스에서 직접 호출하는 것이 아니라, config/ 파일 내에서 호출해 config() 경유로 접근하는 것이 모범 사례입니다. 설정값의 캐시(php artisan config:cache)가 유효한 경우, env()가 의도한 값을 반환하지 않는 경우가 있습니다.

collect() 와의 사용 구분

Arr:: 클래스는 일반 PHP 배열을 대상으로 한 조작, collect()는 컬렉션 객체를 반환하는 조작입니다.

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() 로 꺼냄)

Eloquent의 결과는 자동으로 컬렉션으로서 반환되므로, collect()로 감쌀 필요는 없습니다. 단순한 배열 조작으로 충분한 경우는 Arr::를 사용하면 단순하게 쓸 수 있습니다.

정리

자주 사용하는 헬퍼 목록

헬퍼	용도
`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)`	환경 변수의 취득

Arr 클래스 vs collect()

Arr:: 클래스를 사용할 장면:

단순한 배열 조작(중첩된 키에의 접근, 키의 좁히기 등)
컬렉션 객체의 오버헤드가 불필요한 경우
결과를 배열인 채로 다루고 싶은 경우

collect()를 사용할 장면:

여러 조작을 메서드 체인으로 표현하고 싶은 경우
Eloquent의 결과를 추가로 가공하는 경우(이미 컬렉션)
map, filter, groupBy 등 컬렉션 고유의 메서드를 사용하고 싶은 경우

마지막 수정일 2026년 7월 13일

​헬퍼 함수란

​배열 헬퍼(Arr 클래스)

​Arr::get() — 도트 표기법으로 중첩된 값을 취득

​Arr::set() — 중첩된 배열에 값을 설정

​Arr::has() — 키의 존재를 확인

​Arr::only() / Arr::except() — 키를 좁히기·제외

​Arr::pluck() — 중첩된 배열에서 특정 키를 뽑아냄

​Arr::first() / Arr::last() — 조건을 만족하는 최초·마지막 요소

​Arr::flatten() — 다차원 배열을 1차원으로 평탄화

​Arr::wrap() — 값을 확실하게 배열로

​Arr::sort() — 값으로 정렬

​Arr::dot() / Arr::undot() — 도트 표기법으로 변환·복원

​Arr::join() — 배열을 문자열로 결합

​data_get() — 중첩된 데이터에의 접근

​숫자 헬퍼(Number 클래스)

​Number::format() — 숫자를 읽기 쉬운 형식으로

​Number::currency() — 통화 포맷

​Number::fileSize() — 파일 사이즈를 사람이 읽을 수 있는 형식으로

​Number::abbreviate() — 큰 수를 생략 표기로

​Number::percentage() — 퍼센트 표시

​경로 헬퍼

​URL 헬퍼

​route() — 이름이 있는 라우트의 URL 생성

​url() — 임의 경로의 절대 URL 생성

​asset() — 정적 애셋의 URL 생성

​to_route() — 이름이 있는 라우트에의 리다이렉트

​기타 자주 사용하는 헬퍼

​config() — 설정값의 취득·설정

​collect() — 컬렉션의 작성

​auth() — 인증 사용자의 취득

​blank() / filled() — 빈 상태 체크

​abort() / abort_if() / abort_unless() — HTTP 예외

​dd() / dump() — 디버그

​dispatch() — 잡을 큐에 투입

​encrypt() / decrypt() — 암호화

​env() — 환경 변수의 취득

​collect() 와의 사용 구분

​정리

헬퍼 함수란

배열 헬퍼(Arr 클래스)

`Arr::get()` — 도트 표기법으로 중첩된 값을 취득

`Arr::set()` — 중첩된 배열에 값을 설정

`Arr::has()` — 키의 존재를 확인

`Arr::only()` / `Arr::except()` — 키를 좁히기·제외

`Arr::pluck()` — 중첩된 배열에서 특정 키를 뽑아냄

`Arr::first()` / `Arr::last()` — 조건을 만족하는 최초·마지막 요소

`Arr::flatten()` — 다차원 배열을 1차원으로 평탄화

`Arr::wrap()` — 값을 확실하게 배열로

`Arr::sort()` — 값으로 정렬

`Arr::dot()` / `Arr::undot()` — 도트 표기법으로 변환·복원

`Arr::join()` — 배열을 문자열로 결합

`data_get()` — 중첩된 데이터에의 접근

숫자 헬퍼(Number 클래스)

`Number::format()` — 숫자를 읽기 쉬운 형식으로

`Number::currency()` — 통화 포맷

`Number::fileSize()` — 파일 사이즈를 사람이 읽을 수 있는 형식으로

`Number::abbreviate()` — 큰 수를 생략 표기로

`Number::percentage()` — 퍼센트 표시

경로 헬퍼

URL 헬퍼

`route()` — 이름이 있는 라우트의 URL 생성

`url()` — 임의 경로의 절대 URL 생성

`asset()` — 정적 애셋의 URL 생성

`to_route()` — 이름이 있는 라우트에의 리다이렉트

기타 자주 사용하는 헬퍼

`config()` — 설정값의 취득·설정

`collect()` — 컬렉션의 작성

`auth()` — 인증 사용자의 취득

`blank()` / `filled()` — 빈 상태 체크

`abort()` / `abort_if()` / `abort_unless()` — HTTP 예외

`dd()` / `dump()` — 디버그

`dispatch()` — 잡을 큐에 투입

`encrypt()` / `decrypt()` — 암호화

`env()` — 환경 변수의 취득

collect() 와의 사용 구분

정리