Laravel Folio

번역일: 2026년 6월 20일

Laravel Folio

소개
설치
- 페이지 경로 / URI
- 서브도메인 라우팅
라우트 만들기
- 중첩 라우트
- 인덱스 라우트
라우트 파라미터
라우트 모델 바인딩
- 소프트 삭제된 모델
렌더 훅
이름 있는 라우트
미들웨어
라우트 캐싱

소개

Laravel Folio는 파일 기반 라우팅을 지원하는 Laravel 패키지입니다. resources/views/pages 디렉터리에 Blade 템플릿 파일을 만드는 것만으로 라우트가 자동으로 생성됩니다. 별도의 라우트 파일(web.php)을 수정하지 않아도 됩니다.

예를 들어 /greeting URL로 접근 가능한 페이지를 만들고 싶다면, resources/views/pages/greeting.blade.php 파일을 생성하기만 하면 됩니다:

<div>
    안녕하세요!
</div>

설치

Composer로 Folio 패키지를 설치합니다:

composer require laravel/folio

설치 후 folio:install Artisan 명령어를 실행합니다. 이 명령어는 Folio의 서비스 프로바이더를 애플리케이션에 등록하며, Folio가 라우트를 찾을 디렉터리를 설정합니다:

php artisan folio:install

페이지 경로 / URI

기본적으로 Folio는 resources/views/pages 디렉터리에서 페이지를 제공합니다. 이 경로는 Folio 서비스 프로바이더의 boot 메서드에서 자유롭게 변경할 수 있습니다.

예를 들어 하나의 Laravel 애플리케이션에서 일반 페이지와 관리자 페이지를 디렉터리로 분리하고 싶을 때는 Folio::path와 Folio::uri 메서드를 조합하면 됩니다. path는 Folio가 페이지를 탐색할 디렉터리를, uri는 해당 디렉터리의 기본 URI를 지정합니다:

use Laravel\Folio\Folio;

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

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

            // ...
        ],
    ]);

서브도메인 라우팅

요청의 서브도메인에 따라 다른 페이지 디렉터리로 라우팅하는 것도 가능합니다. 예를 들어 admin.example.com으로 들어오는 요청을 별도의 디렉터리로 연결하려면 domain 메서드를 사용합니다:

use Laravel\Folio\Folio;

Folio::domain('admin.example.com')
    ->path(resource_path('views/pages/admin'));

domain 메서드는 도메인이나 서브도메인의 일부를 파라미터로 캡처하는 기능도 지원합니다. 캡처된 값은 페이지 템플릿에 자동으로 주입됩니다:

use Laravel\Folio\Folio;

Folio::domain('{account}.example.com')
    ->path(resource_path('views/pages/admin'));

라우트 만들기

Folio가 마운트한 디렉터리에 Blade 템플릿 파일을 생성하면 즉시 해당 URL로 접근할 수 있습니다. 예를 들어 pages/schedule.blade.php 파일을 만들면 http://example.com/schedule로 접근 가능합니다.

현재 등록된 모든 Folio 페이지와 라우트 목록을 확인하려면 다음 명령어를 사용합니다:

php artisan folio:list

중첩 라우트

하위 디렉터리를 만들면 중첩된 URL 구조를 그대로 표현할 수 있습니다. 예를 들어 /user/profile에 해당하는 페이지는 pages/user/profile.blade.php로 만들면 됩니다:

php artisan folio:page user/profile# pages/user/profile.blade.php → /user/profile

인덱스 라우트

디렉터리의 루트 URL에 해당하는 기본 페이지를 만들고 싶다면 index.blade.php 파일을 사용합니다:

php artisan folio:page index# pages/index.blade.php → /php artisan folio:page users/index# pages/users/index.blade.php → /users

라우트 파라미터

URL의 특정 세그먼트를 동적으로 캡처하려면 파일명에서 해당 부분을 대괄호([])로 감싸면 됩니다. 예를 들어 사용자 ID를 URL에서 받아오는 페이지는 다음과 같이 만듭니다:

php artisan folio:page "users/[id]"# pages/users/[id].blade.php → /users/1

캡처된 값은 Blade 템플릿에서 변수로 바로 사용할 수 있습니다:

<div>
    사용자 ID: {{ $id }}
</div>

여러 세그먼트를 한 번에 캡처하려면 ...(스프레드) 접두사를 사용합니다:

php artisan folio:page "users/[...ids]"# pages/users/[...ids].blade.php → /users/1/2/3

이 경우 캡처된 값들은 배열로 주입됩니다:

<ul>
    @foreach ($ids as $id)
        <li>사용자 {{ $id }}</li>
    @endforeach
</ul>

라우트 모델 바인딩

파일명의 와일드카드 세그먼트가 Eloquent 모델 이름과 일치하면, Folio는 Laravel의 라우트 모델 바인딩을 자동으로 활용하여 해당 모델 인스턴스를 페이지에 주입합니다:

php artisan folio:page "users/[User]"# pages/users/[User].blade.php → /users/1

주입된 모델은 Blade 템플릿에서 카멜 케이스 변수명으로 사용할 수 있습니다:

<div>
    사용자 ID: {{ $user->id }}
</div>

바인딩 키 커스터마이징

기본적으로 Folio는 id 컬럼으로 모델을 조회하지만, 다른 컬럼을 사용하고 싶다면 파일명에 컬럼명을 지정할 수 있습니다. 예를 들어 [Post:slug].blade.php라는 파일명은 id 대신 slug 컬럼으로 모델을 조회합니다.

NOTE

Windows 환경에서는 모델 이름과 키 구분에 -를 사용합니다: [Post-slug].blade.php

모델 위치 지정

Folio는 기본적으로 app/Models 디렉터리에서 모델을 찾습니다. 모델이 다른 위치에 있다면 파일명에 완전한 클래스 경로를 지정할 수 있습니다(.으로 네임스페이스를 구분):

php artisan folio:page "users/[.App.Models.User]"# pages/users/[.App.Models.User].blade.php → /users/1

소프트 삭제된 모델

암묵적 모델 바인딩 시 소프트 삭제된 레코드는 기본적으로 조회되지 않습니다. 소프트 삭제된 모델도 함께 조회하려면 페이지 템플릿 상단에서 withTrashed 함수를 호출합니다:

<?php

use function Laravel\Folio\{withTrashed};

withTrashed();

?>

<div>
    사용자 ID: {{ $user->id }}
</div>

렌더 훅

Folio는 기본적으로 Blade 템플릿의 내용을 그대로 응답으로 반환합니다. 하지만 응답을 세밀하게 제어해야 한다면 render 함수를 사용할 수 있습니다.

render 함수는 클로저를 받으며, 해당 클로저는 Folio가 렌더링하는 View 인스턴스와 함께 라우트 파라미터 및 모델 바인딩 값도 함께 전달받습니다. 뷰에 추가 데이터를 넘기거나, 인가 처리 후 에러 응답을 반환하는 등 다양한 용도로 활용할 수 있습니다:

<?php

use App\Models\Post;
use Illuminate\Support\Facades\Auth;
use Illuminate\View\View;

use function Laravel\Folio\render;

render(function (View $view, Post $post) {
    if (! Auth::user()->can('view', $post)) {
        return response('권한이 없습니다.', 403);
    }

    return $view->with('photos', $post->author->photos);
}); ?>

<div>
    {{ $post->content }}
</div>

<div>
    이 작성자는 사진을 {{ count($photos) }}장 등록했습니다.
</div>

이름 있는 라우트

페이지 템플릿에서 name 함수를 호출하면 해당 라우트에 이름을 부여할 수 있습니다:

<?php

use function Laravel\Folio\name;

name('users.index');

이름이 지정된 Folio 페이지는 Laravel의 route 헬퍼로 URL을 생성할 수 있습니다:

<a href="{{ route('users.index') }}">
    전체 사용자 목록
</a>

파라미터가 있는 페이지라면 값을 배열로 전달합니다:

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

미들웨어

특정 페이지에 미들웨어를 적용하려면 페이지 템플릿 상단에서 middleware 함수를 호출합니다:

<?php

use function Laravel\Folio\{middleware};

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

?>

<div>
    대시보드
</div>

여러 페이지에 미들웨어를 일괄 적용하려면 Folio::path 체인에 middleware 메서드를 추가합니다. URL 패턴을 키로 사용하여 적용 범위를 지정할 수 있으며, *는 와일드카드로 사용됩니다:

use Laravel\Folio\Folio;

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

        // ...
    ],
]);

미들웨어 배열 안에 클로저를 포함하면 인라인 익명 미들웨어를 정의할 수도 있습니다:

use Closure;
use Illuminate\Http\Request;
use Laravel\Folio\Folio;

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

        function (Request $request, Closure $next) {
            // ...

            return $next($request);
        },
    ],
]);

라우트 캐싱

Folio를 사용할 때도 Laravel의 라우트 캐싱 기능을 적극 활용하는 것이 좋습니다. Folio는 route:cache Artisan 명령어를 감지하여 페이지 정의와 라우트 이름을 올바르게 캐싱하므로, 프로덕션 환경에서 성능을 최대화할 수 있습니다.