프롬프트 (Prompts)

번역일: 2026년 6월 21일

프롬프트 (Prompts)

소개
설치
사용 가능한 프롬프트
- Text
- Password
- Confirm
- Select
- Multi-select
- Suggest
- Search
- Multi-search
- Pause
정보 메시지
테이블
스피너
진행률 표시줄
터미널 고려 사항
미지원 환경 및 폴백

소개

Laravel Prompts는 커맨드라인 애플리케이션에 아름답고 사용하기 편한 입력 폼을 추가해 주는 PHP 패키지입니다. 플레이스홀더 텍스트, 유효성 검증 등 브라우저 폼과 유사한 기능을 터미널에서 그대로 사용할 수 있습니다.

Laravel Prompts는 Artisan 콘솔 커맨드에서 사용자 입력을 받을 때 특히 유용하며, Laravel 프레임워크 외의 순수 PHP 커맨드라인 프로젝트에서도 독립적으로 사용할 수 있습니다.

NOTE

Laravel Prompts는 macOS, Linux, 그리고 WSL이 설치된 Windows를 지원합니다. 자세한 내용은 미지원 환경 및 폴백 섹션을 참고하세요.

설치

Laravel Prompts는 최신 Laravel 릴리스에 기본으로 포함되어 있습니다.

Laravel 프레임워크 외의 PHP 프로젝트에서 사용하려면 Composer로 설치하세요:

composer require laravel/prompts

사용 가능한 프롬프트

Text

text 함수는 사용자에게 질문을 표시하고, 입력 값을 받아 반환합니다:

use function Laravel\Prompts\text;

$name = text('이름이 무엇인가요?');

플레이스홀더 텍스트, 기본값, 안내 힌트를 함께 지정할 수도 있습니다:

$name = text(
    label: '이름이 무엇인가요?',
    placeholder: '예: 홍길동',
    default: $user?->name,
    hint: '이 이름은 프로필에 표시됩니다.'
);

필수 입력

값 입력을 필수로 지정하려면 required 인수를 전달하세요:

$name = text(
    label: '이름이 무엇인가요?',
    required: true
);

유효성 검증 메시지를 직접 지정하고 싶다면 문자열을 전달할 수도 있습니다:

$name = text(
    label: '이름이 무엇인가요?',
    required: '이름은 필수 입력 항목입니다.'
);

추가 유효성 검증

추가적인 유효성 검증 로직이 필요하다면 validate 인수에 클로저를 전달하세요:

$name = text(
    label: '이름이 무엇인가요?',
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => '이름은 3자 이상이어야 합니다.',
        strlen($value) > 255 => '이름은 255자를 초과할 수 없습니다.',
        default => null
    }
);

클로저는 입력된 값을 받아 오류 메시지를 반환하거나, 유효성 검증을 통과한 경우 null을 반환해야 합니다.

Password

password 함수는 text 함수와 유사하지만, 사용자가 입력하는 내용이 터미널에 표시되지 않고 마스킹됩니다. 비밀번호와 같은 민감한 정보를 입력받을 때 적합합니다:

use function Laravel\Prompts\password;

$password = password('비밀번호를 입력하세요.');

플레이스홀더 텍스트와 안내 힌트도 지정할 수 있습니다:

$password = password(
    label: '비밀번호를 입력하세요.',
    placeholder: '비밀번호',
    hint: '최소 8자 이상이어야 합니다.'
);

필수 입력

값 입력을 필수로 지정하려면 required 인수를 전달하세요:

$password = password(
    label: '비밀번호를 입력하세요.',
    required: true
);

유효성 검증 메시지를 직접 지정하고 싶다면 문자열을 전달할 수도 있습니다:

$password = password(
    label: '비밀번호를 입력하세요.',
    required: '비밀번호는 필수 입력 항목입니다.'
);

추가 유효성 검증

추가적인 유효성 검증 로직이 필요하다면 validate 인수에 클로저를 전달하세요:

$password = password(
    label: '비밀번호를 입력하세요.',
    validate: fn (string $value) => match (true) {
        strlen($value) < 8 => '비밀번호는 8자 이상이어야 합니다.',
        default => null
    }
);

클로저는 입력된 값을 받아 오류 메시지를 반환하거나, 유효성 검증을 통과한 경우 null을 반환해야 합니다.

Confirm

사용자에게 "예/아니오" 형태의 확인을 받아야 할 때는 confirm 함수를 사용하세요. 방향키 또는 y, n 키로 선택할 수 있으며, true 또는 false 값을 반환합니다:

use function Laravel\Prompts\confirm;

$confirmed = confirm('이용 약관에 동의하시겠습니까?');

기본값, "예"/"아니오" 레이블 텍스트, 안내 힌트도 지정할 수 있습니다:

$confirmed = confirm(
    label: '이용 약관에 동의하시겠습니까?',
    default: false,
    yes: '동의합니다',
    no: '거절합니다',
    hint: '계속 진행하려면 약관에 동의해야 합니다.'
);

"예" 선택 강제

반드시 "예"를 선택해야 하는 경우 required 인수를 전달하세요:

$confirmed = confirm(
    label: '이용 약관에 동의하시겠습니까?',
    required: true
);

유효성 검증 메시지를 직접 지정하고 싶다면 문자열을 전달할 수도 있습니다:

$confirmed = confirm(
    label: '이용 약관에 동의하시겠습니까?',
    required: '계속 진행하려면 약관에 동의해야 합니다.'
);

Select

미리 정의된 선택지 중 하나를 선택하게 하려면 select 함수를 사용하세요:

use function Laravel\Prompts\select;

$role = select(
    '사용자에게 어떤 역할을 부여할까요?',
    ['일반 회원', '기여자', '관리자'],
);

기본 선택지와 안내 힌트도 지정할 수 있습니다:

$role = select(
    label: '사용자에게 어떤 역할을 부여할까요?',
    options: ['일반 회원', '기여자', '관리자'],
    default: '관리자',
    hint: '역할은 언제든지 변경할 수 있습니다.'
);

연관 배열을 options에 전달하면 선택된 항목의 값이 아닌 키가 반환됩니다:

$role = select(
    label: '사용자에게 어떤 역할을 부여할까요?',
    options: [
        'member' => '일반 회원',
        'contributor' => '기여자',
        'owner' => '관리자'
    ],
    default: 'owner'
);

기본적으로 최대 5개의 선택지가 표시되며, 그 이상은 스크롤됩니다. scroll 인수로 이 값을 변경할 수 있습니다:

$role = select(
    label: '카테고리를 선택하세요.',
    options: Category::pluck('name', 'id'),
    scroll: 10
);

유효성 검증

select 함수는 선택지가 항상 존재하므로 required 인수를 지원하지 않습니다. 단, 특정 선택지를 표시하되 선택은 막고 싶을 때 validate 인수에 클로저를 전달할 수 있습니다:

$role = select(
    label: '사용자에게 어떤 역할을 부여할까요?',
    options: [
        'member' => '일반 회원',
        'contributor' => '기여자',
        'owner' => '관리자'
    ],
    validate: fn (string $value) =>
        $value === 'owner' && User::where('role', 'owner')->exists()
            ? '관리자는 이미 존재합니다.'
            : null
);

options가 연관 배열이면 클로저는 선택된 키를 받고, 일반 배열이면 선택된 값을 받습니다. 클로저는 오류 메시지를 반환하거나, 유효성 검증을 통과한 경우 null을 반환해야 합니다.

Multi-select

여러 항목을 동시에 선택할 수 있게 하려면 multiselect 함수를 사용하세요:

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    '부여할 권한을 선택하세요.',
    ['읽기', '생성', '수정', '삭제']
);

기본 선택값과 안내 힌트도 지정할 수 있습니다:

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: '부여할 권한을 선택하세요.',
    options: ['읽기', '생성', '수정', '삭제'],
    default: ['읽기', '생성'],
    hint: '권한은 언제든지 변경할 수 있습니다.'
);

연관 배열을 options에 전달하면 선택된 항목의 값 대신 키가 반환됩니다:

$permissions = multiselect(
    label: '부여할 권한을 선택하세요.',
    options: [
        'read' => '읽기',
        'create' => '생성',
        'update' => '수정',
        'delete' => '삭제'
    ],
    default: ['read', 'create']
);

기본적으로 최대 5개의 선택지가 표시되며, 그 이상은 스크롤됩니다. scroll 인수로 이 값을 변경할 수 있습니다:

$categories = multiselect(
    label: '카테고리를 선택하세요.',
    options: Category::pluck('name', 'id'),
    scroll: 10
);

필수 선택

기본적으로 사용자는 아무것도 선택하지 않을 수 있습니다. 하나 이상을 반드시 선택하도록 강제하려면 required 인수를 전달하세요:

$categories = multiselect(
    label: '카테고리를 선택하세요.',
    options: Category::pluck('name', 'id'),
    required: true,
);

유효성 검증 메시지를 직접 지정하고 싶다면 문자열을 전달할 수도 있습니다:

$categories = multiselect(
    label: '카테고리를 선택하세요.',
    options: Category::pluck('name', 'id'),
    required: '카테고리를 최소 한 개 이상 선택해야 합니다.',
);

유효성 검증

특정 선택지를 표시하되 선택은 막고 싶을 때 validate 인수에 클로저를 전달할 수 있습니다:

$permissions = multiselect(
    label: '사용자에게 부여할 권한을 선택하세요.',
    options: [
        'read' => '읽기',
        'create' => '생성',
        'update' => '수정',
        'delete' => '삭제'
    ],
    validate: fn (array $values) => ! in_array('read', $values)
        ? '모든 사용자에게는 읽기 권한이 필요합니다.'
        : null
);

options가 연관 배열이면 클로저는 선택된 키 배열을 받고, 일반 배열이면 선택된 값 배열을 받습니다. 클로저는 오류 메시지를 반환하거나, 유효성 검증을 통과한 경우 null을 반환해야 합니다.

Suggest

suggest 함수는 자동 완성 후보를 제공하지만, 사용자가 목록에 없는 값도 자유롭게 입력할 수 있습니다:

use function Laravel\Prompts\suggest;

$name = suggest('이름이 무엇인가요?', ['홍길동', '김철수']);

두 번째 인수로 클로저를 전달할 수도 있습니다. 클로저는 사용자가 키를 입력할 때마다 호출되며, 지금까지 입력된 문자열을 받아 자동 완성 후보 배열을 반환해야 합니다:

$name = suggest(
    '이름이 무엇인가요?',
    fn ($value) => collect(['홍길동', '김철수'])
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
)

플레이스홀더 텍스트, 기본값, 안내 힌트도 함께 지정할 수 있습니다:

$name = suggest(
    label: '이름이 무엇인가요?',
    options: ['홍길동', '김철수'],
    placeholder: '예: 홍길동',
    default: $user?->name,
    hint: '이 이름은 프로필에 표시됩니다.'
);

필수 입력

값 입력을 필수로 지정하려면 required 인수를 전달하세요:

$name = suggest(
    label: '이름이 무엇인가요?',
    options: ['홍길동', '김철수'],
    required: true
);

유효성 검증 메시지를 직접 지정하고 싶다면 문자열을 전달할 수도 있습니다:

$name = suggest(
    label: '이름이 무엇인가요?',
    options: ['홍길동', '김철수'],
    required: '이름은 필수 입력 항목입니다.'
);

추가 유효성 검증

추가적인 유효성 검증 로직이 필요하다면 validate 인수에 클로저를 전달하세요:

$name = suggest(
    label: '이름이 무엇인가요?',
    options: ['홍길동', '김철수'],
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => '이름은 3자 이상이어야 합니다.',
        strlen($value) > 255 => '이름은 255자를 초과할 수 없습니다.',
        default => null
    }
);

클로저는 입력된 값을 받아 오류 메시지를 반환하거나, 유효성 검증을 통과한 경우 null을 반환해야 합니다.

Search

선택지가 매우 많을 때는 search 함수를 사용하세요. 사용자가 검색어를 입력하면 결과가 필터링되고, 방향키로 원하는 항목을 선택할 수 있습니다:

use function Laravel\Prompts\search;

$id = search(
    '메일을 받을 사용자를 검색하세요.',
    fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

클로저는 현재까지 입력된 텍스트를 받아 선택지 배열을 반환해야 합니다. 연관 배열을 반환하면 선택된 항목의 키가 반환되고, 일반 배열을 반환하면 선택된 값이 반환됩니다.

플레이스홀더 텍스트와 안내 힌트도 지정할 수 있습니다:

$id = search(
    label: '메일을 받을 사용자를 검색하세요.',
    placeholder: '예: 홍길동',
    options: fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: '선택된 사용자에게 즉시 이메일이 발송됩니다.'
);

기본적으로 최대 5개의 결과가 표시되며, scroll 인수로 변경할 수 있습니다:

$id = search(
    label: '메일을 받을 사용자를 검색하세요.',
    options: fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    scroll: 10
);

유효성 검증

추가적인 유효성 검증 로직이 필요하다면 validate 인수에 클로저를 전달하세요:

$id = search(
    label: '메일을 받을 사용자를 검색하세요.',
    options: fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    validate: function (int|string $value) {
        $user = User::findOrFail($value);

        if ($user->opted_out) {
            return '이 사용자는 메일 수신을 거부했습니다.';
        }
    }
);

options 클로저가 연관 배열을 반환하면 validate 클로저는 선택된 키를 받고, 일반 배열을 반환하면 선택된 값을 받습니다. 클로저는 오류 메시지를 반환하거나, 유효성 검증을 통과한 경우 null을 반환해야 합니다.

Multi-search

검색 가능한 선택지가 많고, 여러 항목을 동시에 선택해야 할 때는 multisearch 함수를 사용하세요. 검색어로 결과를 필터링하고, 방향키와 스페이스바로 여러 항목을 선택할 수 있습니다:

use function Laravel\Prompts\multisearch;

$ids = multisearch(
    '메일을 받을 사용자를 검색하세요.',
    fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

클로저는 현재까지 입력된 텍스트를 받아 선택지 배열을 반환해야 합니다. 연관 배열을 반환하면 선택된 항목들의 키 배열이 반환되고, 일반 배열을 반환하면 선택된 값 배열이 반환됩니다.

플레이스홀더 텍스트와 안내 힌트도 지정할 수 있습니다:

$ids = multisearch(
    label: '메일을 받을 사용자를 검색하세요.',
    placeholder: '예: 홍길동',
    options: fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: '선택된 사용자에게 즉시 이메일이 발송됩니다.'
);

기본적으로 최대 5개의 결과가 표시되며, scroll 인수로 변경할 수 있습니다:

$ids = multisearch(
    label: '메일을 받을 사용자를 검색하세요.',
    options: fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    scroll: 10
);

필수 선택

기본적으로 사용자는 아무것도 선택하지 않을 수 있습니다. 하나 이상을 반드시 선택하도록 강제하려면 required 인수를 전달하세요:

$ids = multisearch(
    '메일을 받을 사용자를 검색하세요.',
    fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    required: true,
);

유효성 검증 메시지를 직접 지정하고 싶다면 문자열을 전달할 수도 있습니다:

$ids = multisearch(
    '메일을 받을 사용자를 검색하세요.',
    fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    required: '최소 한 명의 사용자를 선택해야 합니다.'
);

유효성 검증

추가적인 유효성 검증 로직이 필요하다면 validate 인수에 클로저를 전달하세요:

$ids = multisearch(
    label: '메일을 받을 사용자를 검색하세요.',
    options: fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    validate: function (array $values) {
        $optedOut = User::where('name', 'like', '%a%')->findMany($values);

        if ($optedOut->isNotEmpty()) {
            return $optedOut->pluck('name')->join(', ', ', and ').' have opted out.';
        }
    }
);

options 클로저가 연관 배열을 반환하면 validate 클로저는 선택된 키 배열을 받고, 일반 배열을 반환하면 선택된 값 배열을 받습니다. 클로저는 오류 메시지를 반환하거나, 유효성 검증을 통과한 경우 null을 반환해야 합니다.

Pause

pause 함수는 안내 메시지를 표시하고, 사용자가 Enter 키를 눌러 계속 진행할 때까지 실행을 일시 중단합니다:

use function Laravel\Prompts\pause;

pause('계속하려면 ENTER 키를 누르세요.');

정보 메시지

note, info, warning, error, alert 함수를 사용해 다양한 형태의 안내 메시지를 출력할 수 있습니다:

use function Laravel\Prompts\info;

info('패키지가 성공적으로 설치되었습니다.');

테이블

table 함수를 사용하면 여러 행과 열로 구성된 데이터를 보기 좋게 출력할 수 있습니다. 열 이름과 데이터를 전달하기만 하면 됩니다:

use function Laravel\Prompts\table;

table(
    ['이름', '이메일'],
    User::all(['name', 'email'])
);

스피너

spin 함수는 지정된 콜백이 실행되는 동안 스피너 애니메이션과 선택적 메시지를 표시합니다. 처리가 진행 중임을 사용자에게 시각적으로 알려 주며, 콜백의 반환값을 그대로 반환합니다:

use function Laravel\Prompts\spin;

$response = spin(
    fn () => Http::get('http://example.com'),
    '응답을 가져오는 중...'
);

WARNING

spin 함수는 스피너 애니메이션을 위해 PHP pcntl 확장 모듈이 필요합니다. 이 모듈이 설치되어 있지 않으면 애니메이션 없이 정적 스피너가 표시됩니다.

진행률 표시줄

오랜 시간이 걸리는 작업을 처리할 때는 progress