헬퍼

업데이트됨

번역일: 2026년 9월 17일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 9월 17일
번역 갱신: 2026년 9월 17일

헬퍼

소개

라라벨은 다양한 전역 "헬퍼" PHP 함수를 제공합니다. 이 중 상당수는 프레임워크 자체 내부에서도 사용되지만, 여러분의 애플리케이션에서도 편리하게 사용할 수 있습니다. 배열이나 객체를 다루거나, 경로를 조작하거나, 문자열을 가공하거나, 날짜를 처리하는 등의 반복적인 작업을 훨씬 간결하게 처리할 수 있습니다.

NOTE

헬퍼 함수는 클래스를 매번 use로 임포트하지 않고도 전역적으로 호출할 수 있다는 장점이 있습니다. 다만 팀 규모가 커지거나 코드 추적이 중요해지는 상황이라면, 헬퍼 대신 명시적으로 클래스를 사용하는 편이 가독성 면에서 더 나을 수도 있습니다. 상황에 맞게 적절히 선택해서 사용하세요.

이어지는 섹션들에서는 라라벨이 제공하는 다양한 헬퍼 함수와 유틸리티 클래스들을 하나씩 살펴보겠습니다.

헬퍼

사용 가능한 메서드

소개

Laravel은 전역으로 사용할 수 있는 다양한 "헬퍼" PHP 함수를 제공합니다. 이 함수들 중 상당수는 프레임워크 자체에서 내부적으로 사용되고 있지만, 여러분의 애플리케이션 코드에서도 편리하다고 느낀다면 자유롭게 사용할 수 있습니다.

NOTE

헬퍼 함수는 전역 네임스페이스에 정의되어 있어 어디서든 별도의 use 구문 없이 바로 호출할 수 있습니다. 다만 프로젝트 규모가 커질수록 헬퍼 함수의 남용은 코드의 의존 관계를 파악하기 어렵게 만들 수 있으니, 서비스 컨테이너를 통한 의존성 주입이 더 적합한 상황인지 함께 고려해보시길 권장합니다.

헬퍼

사용 가능한 메서드

배열 & 객체

숫자

경로

app_path base_path config_path database_path lang_path public_path resource_path storage_path

URL

action asset route secure_asset secure_url to_action to_route uri url

기타

배열 & 객체

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

Arr::accessible 메서드는 주어진 값이 배열처럼 접근 가능한지(array-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::array()` {.collection-method}

Arr::array 메서드는 Arr::get()와 마찬가지로 "dot" 표기법을 사용해 중첩된 배열에서 값을 가져오지만, 요청한 값이 array가 아니면 InvalidArgumentException을 발생시킵니다:

use Illuminate\Support\Arr;

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

$value = Arr::array($array, 'languages');

// ['PHP', 'Ruby']

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

// InvalidArgumentException 발생

`Arr::boolean()` {.collection-method}

Arr::boolean 메서드는 Arr::get()와 마찬가지로 "dot" 표기법을 사용해 중첩된 배열에서 값을 가져오지만, 요청한 값이 boolean이 아니면 InvalidArgumentException을 발생시킵니다:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'available' => true];

$value = Arr::boolean($array, 'available');

// true

$value = Arr::boolean($array, 'name');

// InvalidArgumentException 발생

`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 메서드는 주어진 배열들을 교차 조인(cross join)하여 가능한 모든 조합, 즉 카티션 곱(Cartesian product)을 반환합니다:

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 메서드는 다차원 배열을 "dot" 표기법으로 깊이를 나타내는 1차원 배열로 평탄화합니다:

use Illuminate\Support\Arr;

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

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

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

`Arr::every()` {.collection-method}

Arr::every 메서드는 배열의 모든 값이 주어진 조건(참/거짓 테스트)을 통과하는지 확인합니다:

use Illuminate\Support\Arr;

$array = [1, 2, 3];

Arr::every($array, fn ($i) => $i > 0);

// true

Arr::every($array, fn ($i) => $i > 2);

// false

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

Arr::except 메서드는 배열에서 지정한 키/값 쌍을 제외한 나머지를 반환합니다:

use Illuminate\Support\Arr;

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

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

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

`Arr::exceptValues()` {.collection-method}

Arr::exceptValues 메서드는 배열에서 지정한 값들을 제거합니다:

use Illuminate\Support\Arr;

$array = ['foo', 'bar', 'baz', 'qux'];

$filtered = Arr::exceptValues($array, ['foo', 'baz']);

// ['bar', 'qux']

strict 인자에 true를 전달하면 필터링 시 엄격한 타입 비교를 사용할 수 있습니다:

use Illuminate\Support\Arr;

$array = [1, '1', 2, '2'];

$filtered = Arr::exceptValues($array, [1, 2], strict: true);

// ['1', '2']

`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

세 번째 인자로 기본값을 전달할 수도 있습니다. 조건을 통과하는 값이 없을 경우 이 기본값이 반환됩니다:

use Illuminate\Support\Arr;

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

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

Arr::flatten 메서드는 다차원 배열을 1차원 배열로 평탄화합니다:

use Illuminate\Support\Arr;

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

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

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

`Arr::float()` {.collection-method}

Arr::float 메서드는 Arr::get()와 마찬가지로 "dot" 표기법을 사용해 중첩된 배열에서 값을 가져오지만, 요청한 값이 float가 아니면 InvalidArgumentException을 발생시킵니다:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'balance' => 123.45];

$value = Arr::float($array, 'balance');

// 123.45

$value = Arr::float($array, 'name');

// InvalidArgumentException 발생

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

Arr::forget 메서드는 "dot" 표기법을 사용해 중첩된 배열에서 지정한 키/값 쌍을 제거합니다:

use Illuminate\Support\Arr;

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

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

// ['products' => []]

`Arr::from()` {.collection-method}

Arr::from 메서드는 다양한 타입의 입력값을 순수 PHP 배열로 변환합니다. 배열, 객체는 물론 Arrayable, Enumerable, Jsonable, JsonSerializable 등 라라벨에서 자주 쓰이는 여러 인터페이스를 지원하며, Traversable과 WeakMap 인스턴스도 처리할 수 있습니다:

use Illuminate\Support\Arr;

Arr::from((object) ['foo' => 'bar']); // ['foo' => 'bar']

class TestJsonableObject implements Jsonable
{
    public function toJson($options = 0)
    {
        return json_encode(['foo' => 'bar']);
    }
}

Arr::from(new TestJsonableObject); // ['foo' => 'bar']

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

Arr::get 메서드는 "dot" 표기법을 사용해 중첩된 배열에서 값을 가져옵니다:

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 메서드는 "dot" 표기법을 사용해 주어진 항목(들)이 배열에 존재하는지 확인합니다:

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::hasAll()` {.collection-method}

Arr::hasAll 메서드는 "dot" 표기법을 사용해 지정한 키들이 모두 배열에 존재하는지 확인합니다:

use Illuminate\Support\Arr;

$array = ['name' => 'Taylor', 'language' => 'PHP'];

Arr::hasAll($array, ['name']); // true
Arr::hasAll($array, ['name', 'language']); // true
Arr::hasAll($array, ['name', 'IDE']); // false

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

Arr::hasAny 메서드는 "dot" 표기법을 사용해 주어진 항목들 중 하나라도 배열에 존재하는지 확인합니다:

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::integer()` {.collection-method}

Arr::integer 메서드는 Arr::get()와 마찬가지로 "dot" 표기법을 사용해 중첩된 배열에서 값을 가져오지만, 요청한 값이 int가 아니면 InvalidArgumentException을 발생시킵니다:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'age' => 42];

$value = Arr::integer($array, 'age');

// 42

$value = Arr::integer($array, 'name');

// InvalidArgumentException 발생

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

Arr::isAssoc 메서드는 주어진 배열이 연관 배열(associative array)이면 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 메서드는 배열 요소들을 문자열로 연결합니다. 세 번째 인자를 사용하면 배열의 마지막 요소를 연결할 때 사용할 별도의 구분 문자열을 지정할 수 있습니다:

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

세 번째 인자로 기본값을 전달할 수도 있습니다. 조건을 통과하는 값이 없을 경우 이 기본값이 반환됩니다:

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::mapSpread()` {.collection-method}

Arr::mapSpread 메서드는 배열을 순회하면서 중첩된 각 항목의 값을 주어진 클로저에 전달합니다. 클로저는 항목을 자유롭게 수정하여 반환할 수 있으며, 그 결과로 수정된 항목들로 이루어진 새 배열이 생성됩니다:

use Illuminate\Support\Arr;

$array = [
    [0, 1],
    [2, 3],
    [4, 5],
    [6, 7],
    [8, 9],
];

$mapped = Arr::mapSpread($array, function (int $even, int $odd) {
    return $even + $odd;
});

/*
    [1, 5, 9, 13, 17]
*/

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

Arr::mapWithKeys 메서드는 배열을 순회하면서 각 값을 주어진 콜백에 전달합니다. 콜백은 단일 키/값 쌍을 담은 연관 배열을 반환해야 합니다:

use Illuminate\Support\Arr;

$array = [
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => 'john@example.com',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => 'jane@example.com',
    ]
];

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

/*
    [
        'john@example.com' => 'John',
        'jane@example.com' => '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::onlyValues()` {.collection-method}

Arr::onlyValues 메서드는 배열에서 지정한 값만 반환합니다:

use Illuminate\Support\Arr;

$array = ['foo', 'bar', 'baz', 'qux'];

$filtered = Arr::onlyValues($array, ['foo', 'baz']);

// ['foo', 'baz']

strict 인자에 true를 전달하면 필터링 시 엄격한 타입 비교를 사용할 수 있습니다:

use Illuminate\Support\Arr;

$array = [1, '1', 2, '2'];

$filtered = Arr::onlyValues($array, [1, 2], strict: true);

// [1, 2]

`Arr::partition()` {.collection-method}

Arr::partition 메서드는 PHP의 배열 구조 분해(destructuring)와 함께 사용하여, 주어진 조건을 통과하는 요소와 통과하지 못하는 요소를 분리할 수 있습니다:

<?php

use Illuminate\Support\Arr;

$numbers = [1, 2, 3, 4, 5, 6];

[$underThree, $equalOrAboveThree] = Arr::partition($numbers, function (int $i) {
    return $i < 3;
});

dump($underThree);

// [1, 2]

dump($equalOrAboveThree);

// [3, 4, 5, 6]

`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]

세 번째 인자로 기본값을 전달할 수 있으며, 키가 존재하지 않을 경우 이 기본값이 반환됩니다:

use Illuminate\Support\Arr;

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

`Arr::push()` {.collection-method}

Arr::push 메서드는 "dot" 표기법을 사용해 배열에 항목을 추가합니다. 지정한 키에 배열이 존재하지 않으면 새로 생성됩니다:

use Illuminate\Support\Arr;

$array = [];

Arr::push($array, 'office.furniture', 'Desk');

// $array: ['office' => ['furniture' => ['Desk']]]

`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 - (무작위로 선택됨)

두 번째 인자로 반환할 항목의 개수를 지정할 수도 있습니다. 이 인자를 전달하면 항목이 하나만 필요한 경우라도 배열 형태로 반환된다는 점에 주의하세요:

use Illuminate\Support\Arr;

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

// [2, 5] - (무작위로 선택됨)

`Arr::reject()` {.collection-method}

Arr::reject 메서드는 주어진 클로저를 사용해 배열에서 항목을 제거합니다:

use Illuminate\Support\Arr;

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

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

// [0 => 100, 2 => 300, 4 => 500]

`Arr::select()` {.collection-method}

Arr::select 메서드는 배열에서 지정한 값들만 선택하여 새로운 배열을 만듭니다:

use Illuminate\Support\Arr;

$array = [
    ['id' => 1, 'name' => 'Desk', 'price' => 200],
    ['id' => 2, 'name' => 'Table', 'price' => 150],
    ['id' => 3, 'name' => 'Chair', 'price' => 300],
];

Arr::select($array, ['name', 'price']);

// [['name' => 'Desk', 'price' => 200], ['name' => 'Table', 'price' => 150], ['name' => 'Chair', 'price' => 300]]

`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::sole()` {.collection-method}

Arr::sole 메서드는 주어진 클로저를 사용해 배열에서 값을 하나만 가져옵니다. 조건을 통과하는 값이 두 개 이상이면 Illuminate\Support\MultipleItemsFoundException 예외가 발생하며, 조건을 통과하는 값이 하나도 없으면 Illuminate\Support\ItemNotFoundException 예외가 발생합니다:

use Illuminate\Support\Arr;

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

$value = Arr::sole($array, fn (string $value) => $value === 'Desk');

// 'Desk'

`Arr::some()` {.collection-method}

Arr::some 메서드는 배열의 값 중 적어도 하나가 주어진 조건을 통과하는지 확인합니다:

use Illuminate\Support\Arr;

$array = [1, 2, 3];

Arr::some($array, fn ($i) => $i > 2);

// true

`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::string()` {.collection-method}

Arr::string 메서드는 Arr::get()와 마찬가지로 "dot" 표기법을 사용해 중첩된 배열에서 값을 가져오지만, 요청한 값이 string이 아니면 InvalidArgumentException을 발생시킵니다:

use Illuminate\Support\Arr;

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

$value = Arr::string($array, 'name');

// Joe

$value = Arr::string($array, 'languages');

// InvalidArgumentException 발생

`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 스타일 문자열을 조합합니다. 이 메서드는 배열을 인자로 받는데, 배열의 키에는 추가하고 싶은 CSS 선언을, 값에는 불리언 표현식을 지정합니다. 배열 요소의 키가 숫자인 경우 해당 선언은 항상 결과 문자열에 포함됩니다:

use Illuminate\Support\Arr;

$hasColor = true;

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

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

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

이 메서드는 Blade 컴포넌트의 속성 백(attribute bag)에 클래스를 병합하는 기능과 @class Blade 디렉티브의 내부 동작을 담당합니다.

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

Arr::undot 메서드는 "dot" 표기법을 사용하는 1차원 배열을 다차원 배열로 확장합니다:

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]]]

NOTE

이미 값이 있는 위치는 덮어쓰지 않고, 값이 없을 때만 채워 넣는다는 점이 data_set과의 차이입니다.

이 함수는 별표(*)를 와일드카드로도 지원하여, 조건에 맞는 모든 대상을 한 번에 채울 수 있습니다:

$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 함수는 "dot" 표기법을 사용해 중첩된 배열이나 객체에서 값을 가져옵니다:

$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'];

{first}와 {last} 플레이스홀더를 사용하면 배열의 첫 번째 또는 마지막 항목을 가져올 수 있습니다:

$flight = [
    'segments' => [
        ['from' => 'LHR', 'departure' => '9:00', 'to' => 'IST', 'arrival' => '15:00'],
        ['from' => 'IST', 'departure' => '16:00', 'to' => 'PKX', 'arrival' => '20:00'],
    ],
];

data_get($flight, 'segments.{first}.arrival');

// 15:00

`data_set()` {.collection-method}

data_set 함수는 "dot" 표기법을 사용해 중첩된 배열이나 객체 안에 값을 설정합니다:

$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],
        ],
    ]
*/

기본적으로 기존 값은 모두 덮어써집니다. 값이 존재하지 않을 때만 설정하고 싶다면, 네 번째 인자로 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 함수는 "dot" 표기법을 사용해 중첩된 배열이나 객체에서 값을 제거합니다:

$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 함수는 주어진 배열의 첫 번째 요소를 반환합니다. 배열이 비어 있으면 false가 반환됩니다:

$array = [100, 200, 300];

$first = head($array);

// 100

`last()` {.collection-method}

last 함수는 주어진 배열의 마지막 요소를 반환합니다. 배열이 비어 있으면 false가 반환됩니다:

$array = [100, 200, 300];

$last = last($array);

// 300

##숫자

`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.00

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

// €1,000.00

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

// 1.000,00 €

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

// 1.000 €

`Number::defaultCurrency()` {.collection-method}

Number::defaultCurrency 메서드는 Number 클래스가 현재 사용 중인 기본 통화를 반환합니다:

use Illuminate\Support\Number;

$currency = Number::defaultCurrency();

// USD

`Number::defaultLocale()` {.collection-method}

Number::defaultLocale 메서드는 Number 클래스가 현재 사용 중인 기본 로케일을 반환합니다:

use Illuminate\Support\Number;

$locale = Number::defaultLocale();

// en

`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

NOTE

forHumans와 abbreviate는 비슷해 보이지만 결과 형식이 다릅니다. abbreviate는 1K처럼 단위를 붙인 축약형을, forHumans는 1 thousand처럼 자연어에 가까운 형태를 반환합니다. 화면에 노출할 문구의 톤에 맞게 선택하세요.

`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 메서드는 숫자의 서수(ordinal) 표현을 반환합니다:

use Illuminate\Support\Number;

$number = Number::ordinal(1);

// 1st

$number = Number::ordinal(2);

// 2nd

$number = Number::ordinal(21);

// 21st

`Number::pairs()` {.collection-method}

Number::pairs 메서드는 지정한 범위와 간격(step) 값을 기준으로 숫자 쌍(하위 범위)의 배열을 생성합니다. 큰 범위를 페이지네이션이나 배치 작업 단위로 나눌 때 유용합니다. pairs 메서드는 배열의 배열을 반환하며, 각 내부 배열은 숫자 쌍(하위 범위)을 나타냅니다:

use Illuminate\Support\Number;

$result = Number::pairs(25, 10);

// [[0, 9], [10, 19], [20, 25]]

$result = Number::pairs(25, 10, offset: 0);

// [[0, 10], [10, 20], [20, 25]]

`Number::parse()` {.collection-method}

Number::parse 메서드는 PHP의 NumberFormatter를 이용해 로케일이 적용된 숫자 문자열을 파싱합니다:

use Illuminate\Support\Number;

$result = Number::parse('10,123', locale: 'en');

// 10123.0

$result = Number::parse('10,123', locale: 'fr');

// 10.123

`Number::parseInt()` {.collection-method}

Number::parseInt 메서드는 지정된 로케일에 맞춰 문자열을 정수로 파싱합니다:

use Illuminate\Support\Number;

$result = Number::parseInt('10.123');

// (int) 10

$result = Number::parseInt('10,123', locale: 'fr');

// (int) 10

`Number::parseFloat()` {.collection-method}

Number::parseFloat 메서드는 지정된 로케일에 맞춰 문자열을 실수(float)로 파싱합니다:

use Illuminate\Support\Number;

$result = Number::parseFloat('10');

// (float) 10.0

$result = Number::parseFloat('10', locale: 'fr');

// (float) 10.0

`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::spellOrdinal()` {.collection-method}

Number::spellOrdinal 메서드는 숫자의 서수 표현을 문자(단어)로 풀어 쓴 문자열로 반환합니다:

use Illuminate\Support\Number;

$number = Number::spellOrdinal(1);

// first

$number = Number::spellOrdinal(2);

// second

$number = Number::spellOrdinal(21);

// twenty-first

`Number::trim()` {.collection-method}

Number::trim 메서드는 주어진 숫자의 소수점 뒤에 붙는 불필요한 0을 제거합니다:

use Illuminate\Support\Number;

$number = Number::trim(12.0);

// 12

$number = Number::trim(12.30);

// 12.3

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

Number::useLocale 메서드는 애플리케이션 전역의 기본 숫자 로케일을 설정합니다. 이후 호출되는 Number 클래스의 메서드들은 여기서 지정한 로케일을 기준으로 숫자와 통화를 포맷합니다:

use Illuminate\Support\Number;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Number::useLocale('de');
}

일반적으로 서비스 프로바이더의 boot 메서드에서 애플리케이션 전체에 적용할 로케일을 한 번 설정해두는 방식으로 사용합니다.

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

Number::withLocale 메서드는 지정한 로케일을 사용해 클로저를 실행한 뒤, 콜백 실행이 끝나면 원래 로케일로 되돌립니다:

use Illuminate\Support\Number;

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

`Number::useCurrency()` {.collection-method}

Number::useCurrency 메서드는 애플리케이션 전역의 기본 통화를 설정합니다. 이후 호출되는 Number 클래스의 메서드들은 여기서 지정한 통화를 기준으로 값을 포맷합니다:

use Illuminate\Support\Number;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Number::useCurrency('GBP');
}

`Number::withCurrency()` {.collection-method}

Number::withCurrency 메서드는 지정한 통화를 사용해 클로저를 실행한 뒤, 콜백 실행이 끝나면 원래 통화로 되돌립니다:

use Illuminate\Support\Number;

$number = Number::withCurrency('GBP', function () {
    // ...
});

경로(Paths)

`app_path()` {.collection-method}

app_path 함수는 애플리케이션의 app 디렉터리에 대한 절대 경로를 반환합니다. app 디렉터리를 기준으로 특정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = app_path();

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

`base_path()` {.collection-method}

base_path 함수는 애플리케이션의 루트 디렉터리에 대한 절대 경로를 반환합니다. 프로젝트 루트를 기준으로 특정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = base_path();

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

`config_path()` {.collection-method}

config_path 함수는 애플리케이션의 config 디렉터리에 대한 절대 경로를 반환합니다. config 디렉터리를 기준으로 특정 설정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = config_path();

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

`database_path()` {.collection-method}

database_path 함수는 애플리케이션의 database 디렉터리에 대한 절대 경로를 반환합니다. database 디렉터리를 기준으로 특정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = database_path();

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

`lang_path()` {.collection-method}

lang_path 함수는 애플리케이션의 lang 디렉터리에 대한 절대 경로를 반환합니다. lang 디렉터리를 기준으로 특정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = lang_path();

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

NOTE

Laravel 애플리케이션 기본 스켈레톤에는 lang 디렉터리가 기본으로 포함되어 있지 않습니다. Laravel의 언어 파일을 직접 수정하고 싶다면 lang:publish Artisan 명령어로 파일을 퍼블리시(publish)한 뒤 사용하면 됩니다.

`public_path()` {.collection-method}

public_path 함수는 애플리케이션의 public 디렉터리에 대한 절대 경로를 반환합니다. public 디렉터리를 기준으로 특정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = public_path();

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

`resource_path()` {.collection-method}

resource_path 함수는 애플리케이션의 resources 디렉터리에 대한 절대 경로를 반환합니다. resources 디렉터리를 기준으로 특정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = resource_path();

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

`storage_path()` {.collection-method}

storage_path 함수는 애플리케이션의 storage 디렉터리에 대한 절대 경로를 반환합니다. storage 디렉터리를 기준으로 특정 파일의 절대 경로를 생성할 때도 사용할 수 있습니다:

$path = storage_path();

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

헬퍼

URL

`action()` {.collection-method}

action 함수는 주어진 컨트롤러 액션에 대한 URL을 생성합니다:

use App\Http\Controllers\HomeController;

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

컨트롤러 메서드가 라우트 파라미터를 받는다면, 두 번째 인자로 파라미터 배열을 전달하면 됩니다:

$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');

라우트가 파라미터를 받는다면, 두 번째 인자로 파라미터를 전달할 수 있습니다:

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

route 함수는 기본적으로 절대 URL을 생성합니다. 상대 URL을 생성하고 싶다면 세 번째 인자로 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 세그먼트는 함수의 두 번째 인자로 전달할 수 있습니다:

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

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

`to_action()` {.collection-method}

to_action 함수는 주어진 컨트롤러 액션에 대한 리다이렉트 HTTP 응답을 생성합니다:

use App\Http\Controllers\UserController;

return to_action([UserController::class, 'show'], ['user' => 1]);

필요하다면 세 번째 인자로 리다이렉트에 사용할 HTTP 상태 코드를, 네 번째 인자로 추가 응답 헤더를 전달할 수 있습니다:

return to_action(
    [UserController::class, 'show'],
    ['user' => 1],
    302,
    ['X-Framework' => 'Laravel']
);

`to_route()` {.collection-method}

to_route 함수는 이름이 지정된 라우트에 대한 리다이렉트 HTTP 응답을 생성합니다:

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

필요하다면 세 번째 인자로 리다이렉트에 사용할 HTTP 상태 코드를, 네 번째 인자로 추가 응답 헤더를 전달할 수 있습니다:

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

`uri()` {.collection-method}

uri 함수는 주어진 URI에 대한 플루언트 URI 인스턴스를 생성합니다:

$uri = uri('https://example.com')
    ->withPath('/users')
    ->withQuery(['page' => 1]);

uri 함수에 호출 가능한 컨트롤러와 메서드 쌍을 배열로 전달하면, 해당 컨트롤러 메서드의 라우트 경로에 대한 Uri 인스턴스를 생성합니다:

use App\Http\Controllers\UserController;

$uri = uri([UserController::class, 'show'], ['user' => $user]);

컨트롤러가 인보커블(invokable) 컨트롤러라면 클래스 이름만 전달해도 됩니다:

use App\Http\Controllers\UserIndexController;

$uri = uri(UserIndexController::class);

uri 함수에 전달한 값이 이름이 지정된 라우트의 이름과 일치하면, 해당 라우트 경로에 대한 Uri 인스턴스가 생성됩니다:

$uri = uri('users.show', ['user' => $user]);

`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();

url 함수 사용법에 대한 자세한 내용은 URL 생성 문서를 참고하세요.

헬퍼

기타

`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 함수와 마찬가지로, 세 번째 인수로 예외 응답 텍스트를, 네 번째 인수로 커스텀 응답 헤더 배열을 전달할 수 있습니다.

`abort_unless()` {.collection-method}

abort_unless 함수는 주어진 불리언 표현식이 false로 평가될 때 HTTP 예외를 발생시킵니다:

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

abort 함수와 마찬가지로, 세 번째 인수로 예외 응답 텍스트를, 네 번째 인수로 커스텀 응답 헤더 배열을 전달할 수 있습니다.

`app()` {.collection-method}

app 함수는 서비스 컨테이너 인스턴스를 반환합니다:

$container = app();

클래스나 인터페이스 이름을 전달하면 컨테이너로부터 해당 인스턴스를 가져올 수 있습니다:

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

`auth()` {.collection-method}

auth 함수는 인증자(authenticator) 인스턴스를 반환합니다. 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('   ');
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();

`broadcast_if()` {.collection-method}

broadcast_if 함수는 주어진 불리언 표현식이 true로 평가될 때 이벤트를 리스너들에게 브로드캐스트합니다:

broadcast_if($user->isActive(), new UserRegistered($user));

broadcast_if($user->isActive(), new UserRegistered($user))->toOthers();

`broadcast_unless()` {.collection-method}

broadcast_unless 함수는 주어진 불리언 표현식이 false로 평가될 때 이벤트를 리스너들에게 브로드캐스트합니다:

broadcast_unless($user->isBanned(), new UserRegistered($user));

broadcast_unless($user->isBanned(), new UserRegistered($user))->toOthers();

cache 함수는 캐시에서 값을 가져올 때 사용할 수 있습니다. 주어진 키가 캐시에 존재하지 않으면 선택적으로 지정한 기본값이 반환됩니다:

$value = cache('key');

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

키/값 쌍의 배열을 함수에 전달하면 캐시에 항목을 추가할 수 있습니다. 이때 캐시된 값이 유효하다고 간주될 시간(초 단위 또는 기간)도 함께 전달해야 합니다:

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

cache(['key' => 'value'], now()->plus(seconds: 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 함수는 설정 변수의 값을 가져옵니다. 설정 값은 파일 이름과 접근하려는 옵션 이름을 포함한 "점(dot) 표기법"으로 접근할 수 있습니다. 설정 옵션이 존재하지 않을 때 반환할 기본값도 지정할 수 있습니다:

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

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

키/값 쌍의 배열을 전달하면 런타임에 설정 변수를 지정할 수 있습니다. 다만 이 방식은 현재 요청 동안에만 설정 값을 변경하며, 실제 설정 파일의 값을 변경하지는 않는다는 점에 유의하세요:

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

`context()` {.collection-method}

context 함수는 현재 컨텍스트에서 값을 가져옵니다. 컨텍스트 키가 존재하지 않을 때 반환할 기본값도 지정할 수 있습니다:

$value = context('trace_id');

$value = context('trace_id', $default);

키/값 쌍의 배열을 전달하면 컨텍스트 값을 설정할 수 있습니다:

use Illuminate\Support\Str;

context(['trace_id' => Str::uuid()->toString()]);

`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);

decrypt의 반대 동작이 필요하다면 encrypt 함수를 참고하세요.

`dd()` {.collection-method}

dd 함수는 주어진 변수들을 출력(덤프)한 뒤 스크립트 실행을 종료합니다:

dd($value);

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

스크립트 실행을 멈추고 싶지 않다면 dump 함수를 대신 사용하세요.

`dispatch()` {.collection-method}

dispatch 함수는 주어진 Job을 라라벨 큐에 등록합니다:

dispatch(new App\Jobs\SendEmails);

`dispatch_sync()` {.collection-method}

dispatch_sync 함수는 주어진 Job을 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');

encrypt의 반대 동작이 필요하다면 decrypt 함수를 참고하세요.

`env()` {.collection-method}

env 함수는 환경 변수의 값을 조회하거나, 값이 없을 경우 기본값을 반환합니다:

$env = env('APP_ENV');

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

WARNING

배포 과정에서 config:cache 명령어를 실행한다면, env 함수는 오직 설정 파일 안에서만 호출해야 합니다. 설정이 캐시되고 나면 .env 파일은 더 이상 로드되지 않으며, 이후 env 함수를 호출하면 서버나 시스템 레벨의 외부 환경 변수 값이 반환되거나 null이 반환됩니다.

`event()` {.collection-method}

event 함수는 주어진 이벤트를 리스너들에게 전달(dispatch)합니다:

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 옵션을 사용합니다. 이 옵션은 보통 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]);

`literal()` {.collection-method}

literal 함수는 전달된 이름 있는 인수(named arguments)를 속성으로 갖는 새로운 stdClass 인스턴스를 생성합니다:

$obj = literal(
    name: 'Joe',
    languages: ['PHP', 'Ruby'],
);

$obj->name; // 'Joe'
$obj->languages; // ['PHP', 'Ruby']

`logger()` {.collection-method}

logger 함수는 로그에 debug 레벨 메시지를 기록할 때 사용합니다:

logger('Debug message');

컨텍스트 데이터를 배열 형태로 함께 전달할 수도 있습니다:

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

함수에 아무 값도 전달하지 않으면 로거 인스턴스가 반환됩니다:

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

`method_field()` {.collection-method}

method_field 함수는 폼의 HTTP 메서드를 위장(spoofing)하는 값을 담은 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 함수의 두 번째 인수로 전달하는 "기본값"은 대부분 Eloquent 모델의 속성인 경우가 많기 때문에, 라라벨에서는 Eloquent 모델 전체를 두 번째 인수로 전달할 수 있도록 지원합니다. 이렇게 하면 라라벨은 첫 번째 인수로 전달된 값을 "기본값"으로 사용할 Eloquent 속성의 이름으로 간주합니다:

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

// 다음과 동일합니다...

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

`once()` {.collection-method}

once 함수는 주어진 콜백을 실행하고 그 결과를 요청이 처리되는 동안 메모리에 캐시합니다. 이후 동일한 콜백으로 once 함수를 다시 호출하면 이전에 캐시된 결과가 그대로 반환됩니다:

function random(): int
{
    return once(function () {
        return random_int(1, 1000);
    });
}

random(); // 123
random(); // 123 (캐시된 결과)
random(); // 123 (캐시된 결과)

once 함수가 객체 인스턴스 내부에서 실행되면, 캐시된 결과는 해당 객체 인스턴스에 한정하여 유지됩니다:

<?php

class NumberService
{
    public function all(): array
    {
        return once(fn () => [1, 2, 3]);
    }
}

$service = new NumberService;

$service->all();
$service->all(); // (캐시된 결과)

$secondService = new NumberService;

$secondService->all();
$secondService->all(); // (캐시된 결과)

NOTE

once 함수는 인스턴스마다 결과를 독립적으로 캐시하므로, 같은 클래스의 여러 객체에서 각각 다른 계산 결과를 캐시해야 할 때 특히 유용합니다.

`optional()` {.collection-method}

optional 함수는 어떤 값이든 인수로 받아 그 객체의 속성에 접근하거나 메서드를 호출할 수 있게 해줍니다. 만약 주어진 객체가 null이라면, 오류를 발생시키는 대신 속성과 메서드 호출 모두 null을 반환합니다:

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

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

optional 함수는 두 번째 인수로 클로저를 받을 수도 있습니다. 이 클로저는 첫 번째 인수로 전달된 값이 null이 아닐 때만 실행됩니다:

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

`policy()` {.collection-method}

policy 메서드는 주어진 클래스에 대한 정책(policy) 인스턴스를 조회합니다:

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

`redirect()` {.collection-method}

redirect 함수는 리다이렉트 HTTP 응답을 반환하거나, 인수 없이 호출하면 리다이렉터 인스턴스를 반환합니다:

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

return redirect('/home');

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

`report()` {.collection-method}

report 함수는 예외 핸들러를 통해 예외를 보고(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 함수에 두 번째 인수를 전달할 수도 있습니다. 이 인수는 클로저 실행 중 예외가 발생했을 때 반환할 "기본값"입니다:

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

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

report 인수를 전달하면 rescue 함수가 잡은 예외를 report 함수를 통해 보고할지 여부를 결정할 수 있습니다:

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

`resolve()` {.collection-method}

resolve 함수는 서비스 컨테이너를 사용해 주어진 클래스나 인터페이스 이름을 인스턴스로 해석(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 () {
    // 시도 사이에 100ms씩 쉬면서 최대 5번 시도합니다...
}, 100);

대기 시간은 CarbonInterval 인스턴스로도 지정할 수 있습니다:

use function Illuminate\Support\seconds;

return retry(5, function () {
    // 시도 사이에 5초씩 쉬면서 최대 5번 시도합니다...
}, seconds(5));

시도 사이의 대기 시간(밀리초)을 직접 계산하고 싶다면, retry 함수의 세 번째 인수로 클로저를 전달할 수 있습니다:

use Exception;

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

편의를 위해 retry 함수의 첫 번째 인수로 배열을 전달할 수도 있습니다. 이 배열은 각 재시도 사이에 대기할 밀리초 값을 순서대로 지정합니다:

return retry([100, 200], function () {
    // 첫 번째 재시도 전 100ms, 두 번째 재시도 전 200ms 대기합니다...
});

특정 조건에서만 재시도하도록 하려면, retry 함수의 네 번째 인수로 클로저를 전달할 수 있습니다:

use App\Exceptions\TemporaryException;
use Exception;

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

`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와 클로저 두 가지를 인수로 받습니다. $value는 클로저에 전달되며, 클로저 실행 후에는 tap 함수가 그대로 $value를 반환합니다. 클로저의 반환값 자체는 무시됩니다:

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

    $user->save();
});

tap 함수에 클로저를 전달하지 않으면, 주어진 $value에 대해 임의의 메서드를 체이닝하여 호출할 수 있습니다. 이렇게 호출한 메서드의 실제 반환값이 무엇이든 관계없이, 결과적으로는 항상 $value가 반환됩니다. 예를 들어 Eloquent의 update 메서드는 보통 정수를 반환하지만, tap 함수를 통해 체이닝하면 모델 자신을 반환하도록 만들 수 있습니다:

$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

세 번째 인수로 기본값이나 클로저를 전달할 수 있습니다. 주어진 값이 blank일 경우 이 기본값이 반환됩니다:

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

// The value is blank

`validator()` {.collection-method}

validator 함수는 주어진 인수들로 새로운 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 함수는 전달받은 값을 그대로 반환합니다. 두 번째 인수로 클로저가 전달되면 그 클로저를 실행하고 반환값을 돌려줍니다:

$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

`when()` {.collection-method}

when 함수는 주어진 조건이 true로 평가될 때 전달받은 값을 반환합니다. 조건이 false라면 null이 반환됩니다. 두 번째 인수로 클로저가 전달되면 그 클로저를 실행하고 반환값을 돌려줍니다:

$value = when(true, 'Hello World');

$value = when(true, fn () => 'Hello World');

when 함수는 주로 HTML 속성을 조건에 따라 렌더링할 때 유용합니다:

<div {!! when($condition, 'wire:poll="calculate"') !!}>
    ...
</div>

헬퍼

벤치마킹

애플리케이션의 특정 부분이 얼마나 빠르게 동작하는지 빠르게 확인하고 싶을 때가 있습니다. 이럴 때는 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
]);

기본적으로 전달한 콜백은 한 번만 실행되며, 실행 시간이 브라우저 또는 콘솔에 출력됩니다.

콜백을 여러 번 실행하고 싶다면 두 번째 인수로 반복 횟수를 지정하면 됩니다. 이 경우 Benchmark 클래스는 전체 반복에 걸친 평균 실행 시간(밀리초)을 반환합니다.

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

콜백의 실행 시간을 측정하면서 동시에 콜백이 반환하는 값도 얻고 싶다면 value 메서드를 사용할 수 있습니다. 이 메서드는 콜백의 반환값과 실행 시간(밀리초)을 튜플 형태로 반환합니다.

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

날짜와 시간

Laravel에는 강력한 날짜/시간 조작 라이브러리인 Carbon이 포함되어 있습니다. now 함수를 호출하면 새로운 Carbon 인스턴스를 생성할 수 있으며, 이 함수는 Laravel 애플리케이션 어디에서든 전역적으로 사용할 수 있습니다.

$now = now();

또는 Illuminate\Support\Carbon 클래스를 사용해서 새로운 Carbon 인스턴스를 만들 수도 있습니다.

use Illuminate\Support\Carbon;

$now = Carbon::now();

Laravel은 Carbon 인스턴스에 plus와 minus 메서드를 추가하여 날짜와 시간을 쉽게 계산할 수 있도록 해줍니다.

return now()->plus(minutes: 5);
return now()->plus(hours: 8);
return now()->plus(weeks: 4);

return now()->minus(minutes: 5);
return now()->minus(hours: 8);
return now()->minus(weeks: 4);

Carbon과 그 다양한 기능에 대해 더 자세히 알고 싶다면 공식 Carbon 문서를 참고하세요.

간격(Interval) 함수

Laravel은 milliseconds, seconds, minutes, hours, days, weeks, months, years 함수도 제공하는데, 이 함수들은 PHP의 DateInterval 클래스를 확장한 CarbonInterval 인스턴스를 반환합니다. 이 함수들은 Laravel이 DateInterval 인스턴스를 받아들이는 모든 곳에서 사용할 수 있습니다.

use Illuminate\Support\Facades\Cache;

use function Illuminate\Support\{minutes};

Cache::put('metrics', $metrics, minutes(10));

지연 함수 (Deferred Functions)

Laravel의 큐 작업(queued jobs)을 사용하면 작업을 백그라운드에서 처리하도록 큐에 넣을 수 있지만, 별도의 큐 워커를 구성하고 유지하지 않고도 간단한 작업을 뒤로 미루고 싶은 경우가 있습니다.

지연 함수(Deferred Function)를 사용하면 HTTP 응답이 사용자에게 전송된 이후로 클로저의 실행을 미룰 수 있어, 애플리케이션이 더 빠르고 반응성 있게 느껴지도록 만들 수 있습니다. 클로저 실행을 지연시키려면 Illuminate\Support\defer 함수에 클로저를 전달하기만 하면 됩니다.

use App\Services\Metrics;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use function Illuminate\Support\defer;

Route::post('/orders', function (Request $request) {
    // 주문 생성...

    defer(fn () => Metrics::reportOrder($order));

    return $order;
});

기본적으로 지연 함수는 Illuminate\Support\defer를 호출한 HTTP 응답, Artisan 명령어, 또는 큐 작업이 성공적으로 완료되었을 때만 실행됩니다. 즉, 요청이 4xx나 5xx HTTP 응답으로 끝난 경우에는 지연 함수가 실행되지 않습니다. 항상 실행되도록 하고 싶다면 지연 함수에 always 메서드를 체이닝하면 됩니다.

defer(fn () => Metrics::reportOrder($order))->always();

WARNING

Swoole PHP 확장이 설치되어 있는 경우, Laravel의 defer 함수가 Swoole 자체의 전역 defer 함수와 충돌하여 웹 서버 오류가 발생할 수 있습니다. 이 경우 use function Illuminate\Support\defer;로 네임스페이스를 명시하여 Laravel의 defer 헬퍼를 호출하도록 해야 합니다.

지연 함수 취소하기

실행되기 전에 지연 함수를 취소해야 한다면 forget 메서드를 사용하여 이름으로 함수를 취소할 수 있습니다. 지연 함수에 이름을 지정하려면 Illuminate\Support\defer 함수의 두 번째 인수로 이름을 전달하면 됩니다.

defer(fn () => Metrics::report(), 'reportMetrics');

defer()->forget('reportMetrics');

테스트에서 지연 함수 비활성화하기

테스트를 작성할 때는 지연 함수를 비활성화하는 것이 유용할 수 있습니다. 테스트에서 withoutDefer를 호출하면 Laravel이 모든 지연 함수를 즉시 실행하도록 지시할 수 있습니다.

Pest

test('without defer', function () {
    $this->withoutDefer();

    // ...
});

PHPUnit

use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_without_defer(): void
    {
        $this->withoutDefer();

        // ...
    }
}

테스트 케이스 내 모든 테스트에서 지연 함수를 비활성화하고 싶다면, 베이스 TestCase 클래스의 setUp 메서드에서 withoutDefer 메서드를 호출하면 됩니다.

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void// [tl! add:start]
    {
        parent::setUp();

        $this->withoutDefer();
    }// [tl! add:end]
}

로터리 (Lottery)

Laravel의 lottery 클래스는 주어진 확률에 따라 콜백을 실행할 때 사용할 수 있습니다. 예를 들어, 들어오는 요청 중 일정 비율에만 특정 코드를 실행하고 싶을 때 특히 유용합니다.

use Illuminate\Support\Lottery;

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

lottery 클래스는 Laravel의 다른 기능과 함께 사용할 수 있습니다. 예를 들어, 느린 쿼리 중 일부만 예외 핸들러에 보고하고 싶은 경우가 있을 수 있습니다. lottery 클래스는 호출 가능한(callable) 객체이므로, callable을 인수로 받는 어떤 메서드에도 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();

파이프라인 (Pipeline)

Laravel의 Pipeline 파사드는 주어진 입력값을 일련의 invokable 클래스, 클로저 또는 callable을 통과시키면서, 각 단계마다 입력값을 검사하거나 수정하고 파이프라인의 다음 callable을 호출할 수 있는 편리한 방법을 제공합니다.

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);

보시다시피 파이프라인 안의 각 invokable 클래스나 클로저는 입력값과 $next 클로저를 전달받습니다. $next 클로저를 호출하면 파이프라인의 다음 callable이 실행됩니다. 이는 미들웨어와 매우 유사한 구조입니다.

파이프라인의 마지막 callable이 $next 클로저를 호출하면, then 메서드에 전달한 callable이 실행됩니다. 일반적으로 이 callable은 전달받은 입력값을 그대로 반환합니다. 처리가 끝난 입력값을 단순히 그대로 반환하고 싶다면 thenReturn 메서드를 사용하면 편리합니다.

앞서 살펴본 것처럼, 파이프라인에는 클로저뿐만 아니라 invokable 클래스도 전달할 수 있습니다. 클래스 이름을 전달하면 해당 클래스는 Laravel의 서비스 컨테이너를 통해 인스턴스화되므로, invokable 클래스에 의존성을 주입할 수 있습니다.

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

파이프라인에서 withinTransaction 메서드를 호출하면 파이프라인의 모든 단계를 하나의 데이터베이스 트랜잭션으로 자동으로 감쌀 수 있습니다.

$user = Pipeline::send($user)
    ->withinTransaction()
    ->through([
        ProcessOrder::class,
        TransferFunds::class,
        UpdateInventory::class,
    ])
    ->thenReturn();

NOTE

파이프라인은 결제 처리, 회원가입 온보딩처럼 "여러 단계를 순서대로, 각 단계를 독립적으로 테스트 가능하게" 처리하고 싶을 때 특히 유용합니다. 미들웨어와 개념은 같지만, HTTP 요청/응답이 아닌 임의의 값(예: User, Order 모델)을 대상으로 동작한다는 점이 다릅니다.

Sleep

Laravel의 Sleep 클래스는 PHP 네이티브 sleep, usleep 함수를 감싼 가벼운 래퍼로, 테스트하기 쉬우면서도 시간 관련 작업을 다루기 편한 개발자 친화적인 API를 제공합니다.

use Illuminate\Support\Sleep;

$waiting = true;

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

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

Sleep 클래스는 다양한 시간 단위를 다룰 수 있는 여러 메서드를 제공합니다.

// 대기 후 값을 반환...
$result = Sleep::for(1)->second()->then(fn () => 1 + 1);

// 주어진 조건이 참인 동안 대기...
Sleep::for(1)->second()->while(fn () => shouldKeepSleeping());

// 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()->plus(minutes: 1));

// 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 클래스는 실제 대기를 "가짜(fake)"로 처리해 테스트 스위트가 빠르게 실행되도록 해줍니다.

Pest

it('waits until ready', function () {
    Sleep::fake();

    // ...
});

PHPUnit

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

    // ...
}

Sleep 클래스를 fake로 설정하면 실제 대기 시간은 건너뛰게 되어 테스트가 훨씬 빨라집니다.

Sleep 클래스를 fake로 설정한 뒤에는 예상되는 "sleep" 호출에 대해 검증(assertion)을 수행할 수 있습니다. 예를 들어, 실행을 세 번 일시 정지하며 매번 대기 시간이 1초씩 늘어나는 코드를 테스트한다고 가정해봅시다. assertSequence 메서드를 사용하면 테스트를 빠르게 유지하면서도 코드가 올바른 시간만큼 "sleep"했는지 검증할 수 있습니다.

Pest

it('checks if ready three times', function () {
    Sleep::fake();

    // ...

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

PHPUnit

public function test_it_checks_if_ready_three_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;

// sleep이 3번 호출되었는지 검증...
Sleep::assertSleptTimes(3);

// sleep의 대기 시간에 대해 검증...
Sleep::assertSlept(function (Duration $duration): bool {
    return /* ... */;
}, times: 1);

// Sleep 클래스가 한 번도 호출되지 않았는지 검증...
Sleep::assertNeverSlept();

// Sleep이 호출되었더라도 실제 실행 일시 정지는 없었는지 검증...
Sleep::assertInsomniac();

가짜(fake) sleep이 발생할 때마다 특정 동작을 수행하고 싶은 경우가 있을 수 있습니다. 이럴 때는 whenFakingSleep 메서드에 콜백을 전달하면 됩니다. 아래 예제에서는 Laravel의 시간 조작 헬퍼를 사용해 각 sleep의 대기 시간만큼 시간을 즉시 앞당깁니다.

use Carbon\CarbonInterval as Duration;

$this->freezeTime();

Sleep::fake();

Sleep::whenFakingSleep(function (Duration $duration) {
    // fake sleep 발생 시 시간을 진행시킴...
    $this->travel($duration->totalMilliseconds)->milliseconds();
});

시간을 진행시키는 것은 흔히 필요한 작업이므로, fake 메서드는 테스트 중 sleep이 발생할 때 Carbon의 시간과 동기화할 수 있도록 syncWithCarbon 인수를 지원합니다.

Sleep::fake(syncWithCarbon: true);

$start = now();

Sleep::for(1)->second();

$start->diffForHumans(); // 1 second ago

Laravel은 내부적으로 실행을 일시 정지해야 할 때마다 Sleep 클래스를 사용합니다. 예를 들어 retry 헬퍼는 대기할 때 Sleep 클래스를 사용하므로, 이 헬퍼를 사용하는 코드의 테스트 용이성도 함께 향상됩니다.

Timebox

Laravel의 Timebox 클래스는 실제 실행이 더 빨리 끝나더라도 주어진 콜백이 항상 고정된 시간만큼 실행되도록 보장합니다. 이는 암호화 연산이나 사용자 인증 검사처럼, 공격자가 실행 시간의 차이를 이용해 민감한 정보를 추론할 수 있는 상황에서 특히 유용합니다.

실제 실행 시간이 지정한 고정 시간을 초과하면 Timebox는 아무런 효과가 없습니다. 최악의 시나리오까지 고려한 충분히 긴 고정 시간을 선택하는 것은 개발자의 몫입니다.

call 메서드는 클로저와 마이크로초 단위의 시간 제한을 인수로 받아 클로저를 실행한 뒤, 지정한 시간 제한에 도달할 때까지 대기합니다.

use Illuminate\Support\Timebox;

(new Timebox)->call(function ($timebox) {
    // ...
}, microseconds: 10000);

클로저 내부에서 예외가 발생하더라도 이 클래스는 정의된 지연 시간을 그대로 지키며, 지연 시간이 지난 후에 예외를 다시 던집니다.

URI

Laravel의 Uri 클래스는 URI를 생성하고 조작할 수 있는 편리하고 유연한 인터페이스를 제공합니다. 이 클래스는 내부적으로 League URI 패키지의 기능을 감싸고 있으며, Laravel의 라우팅 시스템과도 자연스럽게 통합됩니다.

정적 메서드를 사용하면 손쉽게 Uri 인스턴스를 생성할 수 있습니다.

use App\Http\Controllers\UserController;
use App\Http\Controllers\InvokableController;
use Illuminate\Support\Uri;

// 주어진 문자열로부터 URI 인스턴스 생성...
$uri = Uri::of('https://example.com/path');

// 경로, 네임드 라우트, 컨트롤러 액션으로부터 URI 인스턴스 생성...
$uri = Uri::to('/dashboard');
$uri = Uri::route('users.show', ['user' => 1]);
$uri = Uri::signedRoute('users.show', ['user' => 1]);
$uri = Uri::temporarySignedRoute('user.index', now()->plus(minutes: 5));
$uri = Uri::action([UserController::class, 'index']);
$uri = Uri::action(InvokableController::class);

// 현재 요청 URL로부터 URI 인스턴스 생성...
$uri = $request->uri();

Uri 인스턴스를 얻은 후에는 다음과 같이 유연하게 수정할 수 있습니다.

$uri = Uri::of('https://example.com')
    ->withScheme('http')
    ->withHost('test.com')
    ->withPort(8000)
    ->withPath('/users')
    ->withQuery(['page' => 2])
    ->withFragment('section-1');

URI 구성 요소 확인하기

Uri 클래스를 사용하면 URI를 구성하는 다양한 요소를 손쉽게 확인할 수 있습니다.

$scheme = $uri->scheme();
$authority = $uri->authority();
$host = $uri->host();
$port = $uri->port();
$path = $uri->path();
$segments = $uri->pathSegments();
$query = $uri->query();
$fragment = $uri->fragment();

쿼리 스트링 조작하기

Uri 클래스는 URI의 쿼리 스트링을 조작할 수 있는 다양한 메서드를 제공합니다. withQuery 메서드는 기존 쿼리 스트링에 추가 파라미터를 병합할 때 사용합니다.

$uri = $uri->withQuery(['sort' => 'name']);

withQueryIfMissing 메서드는 주어진 키가 기존 쿼리 스트링에 아직 존재하지 않는 경우에만 추가 파라미터를 병합할 때 사용합니다.

$uri = $uri->withQueryIfMissing(['page' => 1]);

replaceQuery 메서드는 기존 쿼리 스트링을 완전히 새로운 쿼리 스트링으로 대체할 때 사용합니다.

$uri = $uri->replaceQuery(['page' => 1]);

pushOntoQuery 메서드는 배열 값을 가지는 쿼리 스트링 파라미터에 추가 항목을 push할 때 사용합니다.

$uri = $uri->pushOntoQuery('filter', ['active', 'pending']);

withoutQuery 메서드는 쿼리 스트링에서 특정 파라미터를 제거할 때 사용합니다.

$uri = $uri->withoutQuery(['page']);

URI로부터 응답 생성하기

redirect 메서드는 주어진 URI로 리다이렉트하는 RedirectResponse 인스턴스를 생성할 때 사용합니다.

$uri = Uri::of('https://example.com');

return $uri->redirect();

또는 라우트나 컨트롤러 액션에서 Uri 인스턴스를 그대로 반환하기만 해도, 반환된 URI로 자동으로 리다이렉트 응답이 생성됩니다.

use Illuminate\Support\Facades\Route;
use Illuminate\Support\Uri;

Route::get('/redirect', function () {
    return Uri::to('/index')
        ->withQuery(['sort' => 'name']);
});