> ## 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 Folio

> Laravel Folio로 파일 기반 라우팅을 구현하는 방법을 설치부터 라우트 모델 바인딩까지 설명합니다.

## 소개

Laravel Folio는 Blade 파일을 배치하는 것만으로 라우트를 정의할 수 있는 페이지 기반 라우터입니다.
기존 `routes/web.php` 중심의 정의와 달리 파일 시스템 구조를 그대로 URL에 반영할 수 있습니다.

콘텐츠 중심의 사이트나 화면마다 빠르게 페이지를 추가하고 싶은 관리 화면에서 특히 효과적입니다.
API처럼 세밀한 HTTP 제어가 필요한 영역은 일반 라우팅과 병용하는 것이 실용적입니다.

## 설치

먼저 Composer로 Folio를 추가합니다.

```bash theme={null}
composer require laravel/folio
php artisan folio:install
```

`folio:install`은 Folio의 서비스 프로바이더를 등록합니다.
기본적으로 `resources/views/pages/`가 페이지 디렉터리가 됩니다.
여러 페이지 디렉터리나 베이스 URI를 구분해서 사용하는 경우, 서비스 프로바이더의 `boot`에서 `Folio::path()`와 `uri()`를 설정합니다.

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

Folio::path(resource_path('views/pages/guest'))->uri('/');

Folio::path(resource_path('views/pages/admin'))
    ->uri('/admin');
```

## 라우트 생성

Folio는 마운트된 디렉터리 아래의 Blade 파일명에서 URL을 자동으로 생성합니다.

```text theme={null}
resources/views/pages/schedule.blade.php -> /schedule
```

```bash theme={null}
php artisan folio:list
```

### 중첩된 라우트

디렉터리를 중첩하면 URL도 같은 구조로 중첩됩니다.

```bash theme={null}
php artisan folio:page user/profile
# pages/user/profile.blade.php -> /user/profile
```

### 인덱스 라우트

`index.blade.php`는 해당 디렉터리의 루트에 매핑됩니다.

```bash theme={null}
php artisan folio:page index
# pages/index.blade.php -> /

php artisan folio:page users/index
# pages/users/index.blade.php -> /users
```

## 라우트 파라미터

파일명의 `[]`로 URL 세그먼트를 받을 수 있습니다.

```bash theme={null}
php artisan folio:page "users/[id]"
# pages/users/[id].blade.php -> /users/1
```

```blade theme={null}
<div>User {{ $id }}</div>
```

여러 세그먼트를 받는 경우에는 `...`을 사용합니다.

```bash theme={null}
php artisan folio:page "users/[...ids]"
# pages/users/[...ids].blade.php -> /users/1/2/3
```

```blade theme={null}
@foreach ($ids as $id)
    <li>User {{ $id }}</li>
@endforeach
```

## 라우트 모델 바인딩

`[User].blade.php`처럼 모델명을 사용하면 자동으로 모델 해석됩니다.

```bash theme={null}
php artisan folio:page "users/[User]"
# pages/users/[User].blade.php -> /users/1
```

```blade theme={null}
<div>User {{ $user->id }}</div>
```

소프트 삭제된 모델도 다루는 경우, 페이지 안에서 `withTrashed()`를 호출합니다.

```php theme={null}
<?php

use function Laravel\Folio\withTrashed;

withTrashed();
```

<Info>
  `[Post:slug].blade.php`처럼 작성하면 `id` 이외의 키(예: `slug`)로도 모델 해석이 가능합니다.
</Info>

## 미들웨어

특정 페이지에만 적용하는 경우, 페이지 템플릿 안에서 `middleware()`를 사용합니다.

```php theme={null}
<?php

use function Laravel\Folio\middleware;

middleware(['auth', 'verified']);
```

여러 페이지에 일괄 적용하는 경우에는 `Folio::path(...)->middleware()`를 사용합니다.

```php theme={null}
<?php

use Laravel\Folio\Folio;

Folio::path(resource_path('views/pages'))->middleware([
    'admin/*' => ['auth', 'verified'],
]);
```

## 이름 지정 라우트

Folio 페이지에도 `name()`으로 라우트 이름을 붙일 수 있습니다.

```php theme={null}
<?php

use function Laravel\Folio\name;

name('users.index');
```

<Info>
  `users/[User].blade.php`처럼 개별 페이지 쪽에서 `name('users.show')`를 정의하면, 파라미터가 포함된 URL을 `route('users.show', ['user' => $user])`로 생성할 수 있습니다.
</Info>

부여한 라우트 이름은 `route()` 헬퍼로 URL을 생성할 수 있습니다.

```php theme={null}
route('users.index');
route('users.show', ['user' => $user]);
```

## 파일과 URL의 대응

```mermaid theme={null}
graph LR
  A["pages/index.blade.php"] --> B["/"]
  C["pages/about.blade.php"] --> D["/about"]
  E["pages/users/[User].blade.php"] --> F["/users/1"]
```

## 기존 라우팅과의 비교

| 특징     | 일반 라우팅                | Folio          |
| ------ | --------------------- | -------------- |
| 라우트 정의 | `routes/web.php`      | 파일명으로 자동       |
| 컨트롤러   | 필요(또는 클로저)            | 불필요(Blade에 직접) |
| 적합한 사례 | API나 SPA, 복잡한 HTTP 제어 | 콘텐츠 사이트, 관리 화면 |

<Tip>
  Folio를 사용하는 경우에도 `php artisan route:cache`로 라우트 캐시를 활성화하면 프로덕션 성능을 최적화할 수 있습니다.
</Tip>


## Related topics

- [Laravel 11 이후의 애플리케이션 구조](/ko/advanced/app-structure.md)
- [Laravel Boost](/ko/boost.md)
- [Laravel Telescope](/ko/telescope.md)
- [Laravel Bluesky](/ko/packages/laravel-bluesky/index.md)
- [Laravel이란](/ko/introduction.md)