Laravel Folio

업데이트됨

번역일: 2026년 9월 17일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 9월 17일
번역 갱신: 2026년 9월 17일

Laravel Folio

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

소개

Laravel Folio는 Laravel 애플리케이션의 라우팅을 단순하게 만들어주는 강력한 "페이지 기반" 라우터입니다. Folio를 사용하면 라우트를 만드는 일이 애플리케이션의 resources/views/pages 디렉터리에 Blade 템플릿 파일 하나를 만드는 것만큼 간단해집니다.

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

<div>
    Hello World
</div>

라우트 파일에 Route::get('/greeting', ...) 같은 코드를 작성할 필요가 전혀 없습니다. 파일 시스템 구조 자체가 곧 라우트 정의가 되는 방식입니다.

설치

먼저 Composer 패키지 매니저로 Folio를 프로젝트에 설치합니다.

composer require laravel/folio

설치가 끝나면 folio:install Artisan 명령어를 실행하세요. 이 명령어는 Folio의 서비스 프로바이더를 애플리케이션에 설치합니다. 이 서비스 프로바이더는 Folio가 라우트(페이지)를 탐색할 디렉터리를 등록하는 역할을 합니다.

php artisan folio:install

페이지 경로 / URI

기본적으로 Folio는 resources/views/pages 디렉터리에서 페이지를 서비스합니다. 이 디렉터리는 Folio 서비스 프로바이더의 boot 메서드에서 원하는 대로 커스터마이징할 수 있습니다.

예를 들어 하나의 Laravel 애플리케이션 안에서 여러 개의 Folio 경로를 지정하는 것이 편리한 경우가 있습니다. 애플리케이션의 "관리자" 영역을 위한 별도의 Folio 페이지 디렉터리를 두고, 나머지 페이지들은 다른 디렉터리에서 관리하고 싶을 수 있습니다.

이럴 때는 Folio::path와 Folio::uri 메서드를 사용합니다. path 메서드는 Folio가 들어오는 HTTP 요청을 라우팅할 때 스캔할 디렉터리를 등록하고, 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으로 들어온 요청을 나머지 Folio 페이지와 다른 디렉터리로 라우팅하고 싶다면, Folio::path 메서드를 호출한 후 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'));

가령 tenant1.example.com으로 요청이 들어오면 $account 변수에 tenant1이 담겨서 페이지에 전달되는 식입니다. 멀티 테넌트 애플리케이션을 구축할 때 유용하게 활용할 수 있습니다.

라우트 생성하기

Folio가 마운트하는 디렉터리 안에 Blade 템플릿을 두기만 하면 Folio 라우트가 생성됩니다. 기본적으로 Folio는 resources/views/pages 디렉터리를 마운트하지만, 이 디렉터리 역시 Folio 서비스 프로바이더의 boot 메서드에서 커스터마이징할 수 있습니다.

Folio가 마운트한 디렉터리에 Blade 템플릿을 두는 즉시 브라우저에서 바로 접근할 수 있습니다. 예를 들어 pages/schedule.blade.php에 파일을 두면 브라우저에서 http://example.com/schedule로 접근할 수 있습니다.

애플리케이션에 등록된 모든 Folio 페이지(라우트) 목록을 빠르게 확인하고 싶다면 folio:list Artisan 명령어를 사용하세요.

php artisan folio:list

중첩 라우트

Folio 디렉터리 안에 하위 디렉터리를 만들면 중첩된 라우트를 생성할 수 있습니다. 예를 들어 /user/profile로 접근 가능한 페이지를 만들려면 pages/user 디렉터리 안에 profile.blade.php 템플릿을 생성하면 됩니다.

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

인덱스 라우트

경우에 따라 특정 디렉터리의 "인덱스" 역할을 하는 페이지를 만들고 싶을 수 있습니다. Folio 디렉터리 안에 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"에 접근해야 할 수 있습니다. 이럴 때는 페이지 파일명의 특정 세그먼트를 대괄호로 감싸면 됩니다.

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

이렇게 캡처된 세그먼트는 Blade 템플릿 안에서 변수로 바로 사용할 수 있습니다.

<div>
    User {{ $id }}
</div>

여러 개의 세그먼트를 한 번에 캡처하고 싶다면, 대괄호 안의 이름 앞에 점 세 개(...)를 붙이면 됩니다.

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

이렇게 여러 세그먼트를 캡처하면, 캡처된 값들은 배열 형태로 페이지에 주입됩니다.

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

라우트 모델 바인딩

페이지 템플릿 파일명의 와일드카드 세그먼트가 애플리케이션의 Eloquent 모델 이름과 일치하면, Folio는 Laravel의 라우트 모델 바인딩 기능을 자동으로 활용해서 해석된 모델 인스턴스를 페이지에 주입해줍니다.

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

캡처된 모델은 Blade 템플릿 안에서 변수로 사용할 수 있으며, 변수명은 "카멜 케이스"로 자동 변환됩니다.

<div>
    User {{ $user->id }}
</div>

바인딩 키 커스터마이징

id 컬럼이 아닌 다른 컬럼으로 Eloquent 모델을 바인딩하고 싶을 때가 있습니다. 이 경우 페이지 파일명에 원하는 컬럼을 지정하면 됩니다. 예를 들어 [Post:slug].blade.php라는 파일명은 id 컬럼 대신 slug 컬럼을 기준으로 모델을 바인딩합니다.

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

소프트 삭제된 모델

기본적으로 암묵적 모델 바인딩은 소프트 삭제(soft delete)된 모델을 조회 대상에서 제외합니다. 하지만 필요하다면 페이지 템플릿에서 withTrashed 함수를 호출해 소프트 삭제된 모델도 함께 조회하도록 Folio에 지시할 수 있습니다.

<?php

use function Laravel\Folio\{withTrashed};

withTrashed();

?>

<div>
    User {{ $user->id }}
</div>

렌더 훅

기본적으로 Folio는 페이지의 Blade 템플릿 내용을 그대로 응답으로 반환합니다. 하지만 페이지 템플릿 안에서 render 함수를 호출하면 이 응답을 원하는 대로 커스터마이징할 수 있습니다.

render 함수는 클로저를 인자로 받으며, 이 클로저에는 Folio가 렌더링 중인 View 인스턴스가 전달됩니다. 이를 통해 뷰에 추가 데이터를 넘기거나 응답 전체를 원하는 대로 바꿀 수 있습니다. View 인스턴스뿐만 아니라 라우트 파라미터나 모델 바인딩 값도 함께 render 클로저에 전달됩니다.

<?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('Unauthorized', 403);
    }

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

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

<div>
    This author has also taken {{ count($photos) }} photos.
</div>

이름이 지정된 라우트

특정 페이지의 라우트에 이름을 지정하고 싶다면 name 함수를 사용하면 됩니다.

<?php

use function Laravel\Folio\name;

name('users.index');

일반 Laravel의 이름이 지정된 라우트와 마찬가지로, 이름이 부여된 Folio 페이지로 향하는 URL은 route 함수로 생성할 수 있습니다.

<a href="{{ route('users.index') }}">
    All Users
</a>

페이지에 파라미터가 있다면 값을 route 함수에 그대로 전달하면 됩니다.

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

미들웨어

특정 페이지에 미들웨어를 적용하고 싶다면 페이지 템플릿 안에서 middleware 함수를 호출하면 됩니다.

<?php

use function Laravel\Folio\{middleware};

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

?>

<div>
    Dashboard
</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 명령어를 감지해서, Folio 페이지 정의와 라우트 이름이 최고의 성능을 위해 올바르게 캐시되도록 처리합니다.

NOTE

페이지 파일을 추가하거나 수정한 뒤에는 반드시 php artisan route:cache를 다시 실행해서 캐시를 갱신해야 변경 사항이 프로덕션 환경에 반영됩니다. 캐시를 재생성하지 않으면 새로 추가한 페이지가 404로 응답될 수 있습니다.