> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# laravel/ui에서 Fortify로의 마이그레이션 가이드

> laravel/ui의 인증 스캐폴드를 사용하는 기존 프로젝트를 대상으로, 인증 백엔드만을 Fortify로 마이그레이션하는 절차를 설명합니다.

## 왜 `laravel/ui`에서 마이그레이션하는가

`laravel/ui`는 Laravel 13에서도 동작합니다. 실제로 `laravel/ui`의 최신 릴리스는 Laravel 13 compatibility를 포함하고 있습니다.

다만 현행의 공식 스타터 킷은 Fortify 기반입니다. `laravel/ui` 그대로 운용을 계속하면, 공식의 현재 위치와 조금씩 어긋나 갑니다.\
여러분이 기존의 Bootstrap + Blade 구성을 유지하면서 장래의 유지보수성을 올리고 싶다면, 인증 백엔드를 Fortify로 이관하는 마이그레이션이 유효합니다.

## 마이그레이션의 전체 상

이 마이그레이션은 **인증 백엔드만**을 치환합니다. UI의 대규모 리뉴얼은 불필요합니다.

* Fortify에서 인증 라우트 · 인증 처리를 제공
* 기존의 Bootstrap + Blade 템플릿은 활용
* 필요한 범위에서 폼의 `action`이나 입력명을 조정

<Info>
  Fortify는 headless한 인증 백엔드입니다. Fortify 자체는 UI를 제공하지 않으므로, 기존의 Blade를 그대로 활용할 수 있습니다.
</Info>

## Fortify 설치 절차

<Steps>
  <Step title="Fortify 패키지 추가">
    ```bash theme={null}
    composer require laravel/fortify
    ```
  </Step>

  <Step title="Fortify의 리소스 공개">
    ```bash theme={null}
    php artisan fortify:install
    ```
  </Step>

  <Step title="마이그레이션 실행">
    ```bash theme={null}
    php artisan migrate
    ```
  </Step>

  <Step title="`laravel/ui`가 추가한 Auth 라우트 삭제">
    `routes/web.php`의 `Auth::routes();`나 `Auth::routes([...])`를 삭제합니다. Fortify가 `/login`, `/register`, `/forgot-password` 등의 라우트를 제공하므로, 중복을 피해야 합니다.
  </Step>
</Steps>

## `FortifyServiceProvider` 설정

`php artisan fortify:install`로 공개된 `app/Providers/FortifyServiceProvider.php`에서 뷰를 연결합니다.\
기존의 `resources/views/auth`를 그대로 사용하는 경우에는, 다음 설정이 마이그레이션의 포인트입니다.

```php theme={null}
use Laravel\Fortify\Fortify;

public function boot(): void
{
    Fortify::viewPrefix('auth.');
    Fortify::requestPasswordResetLinkView('auth.passwords.email');
    Fortify::resetPasswordView('auth.passwords.reset');
    Fortify::confirmPasswordView('auth.passwords.confirm');
    Fortify::verifyEmailView('auth.verify');
}
```

## Blade 템플릿을 최소 수정

마이그레이션 후, 기존 Blade에서 다음 점을 확인해 주세요.

* 폼의 `action`이 Fortify의 엔드포인트를 향하고 있는지 (예: `/login`, `/register`, `/forgot-password`). 대부분은 `route('login')`이나 `route('register')`의 라우트명 지정이므로 수정 부분은 적을 것입니다. `route(verification.resend')`만은 Fortify에서는 `route('verification.send')`이므로 수정이 필요합니다.

`auth/passwords/reset.balde.php`는 2군데 수정이 필요합니다.

```
<input type="hidden" name="token" value="{{ $token }}">
```

↓

```
<input type="hidden" name="token" value="{{ $request->route('token') }}">
```

```
{{ $email ?? old('email') }}
```

↓

```
{{ old('email', $request->email) }}
```

## 불필요한 기능 비활성화

`laravel/ui`에 없었던 기능은 사용할 수 없으므로 `config/fortify.php`에서 비활성화합니다. 새로 view 파일을 준비하면 활성화할 수 있습니다.

```php theme={null}
    'features' => [
        Features::registration(),
        Features::resetPasswords(),
        // Features::emailVerification(),
        // Features::updateProfileInformation(),
        // Features::updatePasswords(),
        // Features::twoFactorAuthentication([
        //     'confirm' => true,
        //     'confirmPassword' => true,
            // 'window' => 0,
        // ]),
        // Features::passkeys([
        //     'confirmPassword' => true,
        // ]),
    ],
```

## 동작 확인 체크리스트

마이그레이션 후에는 적어도 다음을 확인해 주세요.

<Steps>
  <Step title="로그인 / 로그아웃 확인">
    기존 사용자로 로그인하여, 세션이 올바르게 유지되는 것을 확인합니다.
  </Step>

  <Step title="회원가입 확인">
    신규 사용자 등록이 통과되고, 상정한 화면으로 리다이렉트되는 것을 확인합니다.
  </Step>

  <Step title="패스워드 리셋 확인">
    리셋 메일 송신, 토큰 부여 링크, 재설정 완료까지 일련의 흐름을 확인합니다.
  </Step>
</Steps>

## 마이그레이션 후의 이점

이 마이그레이션을 수행하면 여러분의 앱은 현행 스타터 킷과 같은 Fortify 기반에 가까워집니다.\
그 결과, 장래적으로 2FA나 패스키(Passkeys)를 활성화하기 쉬워집니다.

<Card title="Laravel Fortify와 스타터 킷" icon="shield-check" href="/ko/advanced/fortify">
  Fortify의 내부 설계, 2FA, Passkeys의 활성화까지 진행하고 싶은 경우에는 이 페이지를 참고하세요.
</Card>

## 참고 링크

* [Laravel Fortify 리포지토리](https://github.com/laravel/fortify)
* [Laravel 13.x Fortify 문서](https://github.com/laravel/docs/blob/13.x/fortify.md)
* [React Starter Kit의 FortifyServiceProvider](https://github.com/laravel/react-starter-kit/blob/main/app/Providers/FortifyServiceProvider.php)


## Related topics

- [Laravel 11에서 12로의 업그레이드 가이드](/ko/blog/upgrade-11-to-12.md)
- [Laravel 12에서 13으로의 업그레이드 가이드](/ko/blog/upgrade-12-to-13.md)
- [Laravel 8에서 9로의 업그레이드](/ko/blog/upgrade-8-to-9.md)
- [Laravel 10에서 11로의 업그레이드](/ko/blog/upgrade-10-to-11.md)
- [Laravel 9에서 10으로의 업그레이드](/ko/blog/upgrade-9-to-10.md)