# 콘솔 yes/no 프롬프트 (ConsoleConfirm)

> **관련 문서**: [README.md](README.md) | [docs/extension/upgrade-step-guide.md](../extension/upgrade-step-guide.md)

---

## TL;DR (5초 요약)

```text
1. 콘솔 커맨드의 yes/no 프롬프트는 $this->unifiedConfirm() 사용 — Laravel $this->confirm() 직접 호출 금지
2. trait: App\Console\Commands\Traits\HasUnifiedConfirm
3. 입력 규칙: empty=default, yes/y=true, no/n=false, 그 외=재질문 루프
4. --no-interaction 모드: default 즉시 반환
5. upgrade step / Symfony 외부 환경: \App\Console\Helpers\ConsoleConfirm::ask() FQN 직접 호출
```

---

## 목차

1. [왜 통일 헬퍼가 필요한가](#왜-통일-헬퍼가-필요한가)
2. [HasUnifiedConfirm trait (Laravel Command)](#hasunifiedconfirm-trait-laravel-command)
3. [ConsoleConfirm helper (Symfony 비의존)](#consoleconfirm-helper-symfony-비의존)
4. [입력 처리 규칙](#입력-처리-규칙)
5. [테스트 작성 방법](#테스트-작성-방법)
6. [안티 패턴 vs 모범 사례](#안티-패턴-vs-모범-사례)
7. [체크리스트](#체크리스트)

---

## 왜 통일 헬퍼가 필요한가

Laravel `Command::confirm()` (Symfony `ConfirmationQuestion`) 의 기본 동작은 입력 검증이 느슨하다:

- `/^y/i` 만 true 로 처리 → `yell_no`, `yummy` 도 true 로 인식
- empty 입력만 default 사용, 잘못된 입력은 묵묵히 false
- 사용자 피드백 없음 (재질문 없이 false 처리)

본 헬퍼는 다음을 표준화한다:

- 입력을 trim + 소문자 정규화
- `yes`/`y` 만 true, `no`/`n` 만 false
- empty → default
- 그 외 입력 → "yes, y, no, n 중 하나로 입력해 주세요." 출력 후 재질문 루프
- `--no-interaction` 또는 비TTY 환경 → default 즉시 반환

---

## HasUnifiedConfirm trait (Laravel Command)

### 사용법

```php
use App\Console\Commands\Traits\HasUnifiedConfirm;
use Illuminate\Console\Command;

class UninstallFooCommand extends Command
{
    use HasUnifiedConfirm;

    public function handle(): int
    {
        if (! $this->unifiedConfirm('Foo 를 삭제하시겠습니까?', false)) {
            $this->info('취소되었습니다.');

            return self::SUCCESS;
        }

        // 삭제 로직
        return self::SUCCESS;
    }
}
```

### 시그니처

```php
protected function unifiedConfirm(string $question, bool $default = false): bool
```

| 파라미터 | 설명 |
|---------|------|
| `$question` | 질문 메시지 (말미 `(yes/no) [yes\|no]:` 자동 부여) |
| `$default` | 기본값 — true=`[yes]` 표시 / false=`[no]` 표시 |

### 동작

| 환경 | 동작 |
|------|------|
| `--no-interaction` 옵션 | `$default` 즉시 반환 |
| 대화형 + 유효 입력 | 정규화 후 즉시 반환 |
| 대화형 + 잘못된 입력 | "yes, y, no, n 중 하나로 입력해 주세요." 출력 후 재질문 |
| 대화형 + empty 입력 | `$default` 반환 |

---

## ConsoleConfirm helper (Symfony 비의존)

`HasUnifiedConfirm` 은 Symfony QuestionHelper 를 거치므로 Laravel Command 외부 (예: upgrade step, 단순 PHP CLI 스크립트) 에서는 사용할 수 없다. 그런 경우 `ConsoleConfirm::ask()` 를 직접 호출한다.

### 사용법

```php
$confirmed = \App\Console\Helpers\ConsoleConfirm::ask(
    '진행하시겠습니까?',
    true, // default = yes
);
```

### 시그니처

```php
public static function ask(
    string $question,
    bool $default = false,
    $stdin = null,        // 테스트용 STDIN 주입
    ?callable $writer = null, // 테스트용 출력 콜백
): bool
```

### upgrade step 에서 사용 시 주의

`upgrades/Upgrade_X_Y_Z.php` 는 **이전 버전 PHP 메모리에서 실행**된다. 신규 클래스 호출은 PHP autoloader 가 lazy load 하므로 안전하지만, **FQN 직접 호출** 권장 (use 문 의존 회피).

```php
$confirmed = \App\Console\Helpers\ConsoleConfirm::ask(
    '번들 일괄 업데이트를 진행하시겠습니까?',
    true,
);
```

> **상세**: [docs/extension/upgrade-step-guide.md](../extension/upgrade-step-guide.md) "사용자 입력" 섹션

---

## 입력 처리 규칙

### 정규화 단계

1. `trim()` — 좌우 공백/개행 제거
2. `strtolower()` — 대소문자 무시

### 결정 매트릭스

| 정규화된 입력 | default 무관 | 결과 |
|--------------|-------------|------|
| `''` (empty) | true | true |
| `''` (empty) | false | false |
| `yes`, `y` | - | true |
| `no`, `n` | - | false |
| `yell_no`, `nope`, `1`, `true`, `예`, `네` 등 | - | **재질문** |

### EOF / 비TTY

| 환경 | 결과 |
|------|------|
| `STDIN` 닫힘 (EOF) | `default` |
| TTY 미연결 (CI, spawn) | `default` |
| `--no-interaction` 옵션 | `default` |

---

## 테스트 작성 방법

### Unit — 입력 정규화 (`ConsoleConfirm::parse`)

```php
use App\Console\Helpers\ConsoleConfirm;

public function test_parse(): void
{
    $this->assertTrue(ConsoleConfirm::parse('YES', false));
    $this->assertFalse(ConsoleConfirm::parse('  no  ', true));
    $this->assertNull(ConsoleConfirm::parse('yell_no', false)); // 재질문
    $this->assertTrue(ConsoleConfirm::parse('', true));         // empty → default
}
```

### Unit — STDIN 루프 (`ConsoleConfirm::ask`)

테스트용 stream 주입:

```php
$stream = fopen('php://memory', 'r+');
fwrite($stream, "abc\ny\n");
rewind($stream);

$result = ConsoleConfirm::ask('Q?', false, $stream, fn (string $t) => null);
$this->assertTrue($result);
```

### Feature — Laravel Artisan (`unifiedConfirm`)

`expectsQuestion()` 사용 — 질문 텍스트는 `'{question} (yes/no) [no]'` 형식:

```php
$this->artisan('foo:bar')
    ->expectsQuestion('진행하시겠습니까? (yes/no) [no]', 'yes')
    ->assertExitCode(0);
```

`--no-interaction` 또는 `--force` 시 default 동작 회귀:

```php
$this->artisan('foo:bar --no-interaction')->assertExitCode(0);
```

### 주의

- `expectsConfirmation()` (Laravel 헬퍼) 는 Symfony `ConfirmationQuestion` 전용이므로 신규 trait 와 호환되지 않는다 → **`expectsQuestion()` 사용**

---

## 안티 패턴 vs 모범 사례

### ❌ 안티 패턴

```php
// 1. Laravel 기본 confirm 직접 호출 (입력 검증 느슨)
if (! $this->confirm('정말 삭제하시겠습니까?')) { ... }

// 2. fgets(STDIN) 직접 호출 (TTY 가드 없음, 재질문 없음)
echo "진행할까요? (y/n): ";
$answer = trim(fgets(STDIN));
if (strtolower($answer) === 'y') { ... }

// 3. ask() 로 yes/no 받기 (자유 텍스트 입력에 적합, 정규화 없음)
$answer = $this->ask('진행할까요? (y/n)');
```

### ✅ 모범 사례

```php
// 1. Laravel Command — trait 사용
class FooCommand extends Command
{
    use HasUnifiedConfirm;

    public function handle(): int
    {
        if (! $this->unifiedConfirm('정말 삭제하시겠습니까?', false)) {
            return self::SUCCESS;
        }
    }
}

// 2. upgrade step 또는 외부 환경 — FQN 직접 호출
$confirmed = \App\Console\Helpers\ConsoleConfirm::ask('진행할까요?', true);
```

---

## 체크리스트

```text
□ Laravel Command 에서 yes/no 입력이 필요한가?
   → use HasUnifiedConfirm + $this->unifiedConfirm($question, $default)

□ upgrade step 또는 단순 PHP CLI 에서 yes/no 입력이 필요한가?
   → \App\Console\Helpers\ConsoleConfirm::ask($question, $default) FQN 호출

□ 자유 텍스트 입력이 필요한가?
   → $this->ask() 그대로 사용 (yes/no 정규화 불필요)

□ 다중 옵션 선택이 필요한가?
   → $this->choice() 사용 (yes/no 정규화 불필요)

□ 테스트는 expectsQuestion('{question} (yes/no) [default]', 'yes/no') 형식으로 작성했는가?
   → expectsConfirmation() 은 신규 trait 와 호환되지 않음
```

---

## 참고 파일

- **ConsoleConfirm**: `app/Console/Helpers/ConsoleConfirm.php`
- **HasUnifiedConfirm**: `app/Console/Commands/Traits/HasUnifiedConfirm.php`
- **단위 테스트**: `tests/Unit/Console/Helpers/ConsoleConfirmTest.php`, `tests/Unit/Console/Commands/Traits/HasUnifiedConfirmTest.php`
- **회귀 테스트**: `tests/Feature/Console/UnifiedConfirmRegressionTest.php`