Laravel Folio

번역일: 2026년 6월 20일

Laravel Folio

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

소개

Laravel Folio는 파일 기반 라우팅을 제공하는 Laravel 패키지입니다. Folio를 사용하면 resources/views/pages 디렉터리에 Blade 템플릿 파일을 생성하는 것만으로 라우트가 자동으로 만들어집니다.

예를 들어, /greeting URL로 접근할 수 있는 페이지를 만들려면 resources/views/pages/greeting.blade.php 파일을 다음과 같이 생성하면 됩니다:

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

별도의 라우트 등록 없이 파일 하나로 페이지가 생성되는 것이 Folio의 핵심 개념입니다.

설치

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

composer require laravel/folio

설치 후 folio:install Artisan 명령을 실행하면, Folio의 서비스 프로바이더가 애플리케이션에 등록됩니다. 이 서비스 프로바이더는 Folio가 페이지를 탐색할 디렉터리를 지정합니다:

php artisan folio:install

페이지 경로 / URI

기본적으로 Folio는 resources/views/pages 디렉터리를 페이지 루트로 사용합니다. 필요에 따라 Folio 서비스 프로바이더의 boot 메서드에서 이 경로를 변경하거나 여러 경로를 등록할 수 있습니다.

예를 들어, 일반 사용자 페이지와 관리자 페이지를 별도의 디렉터리로 분리하고 싶다면 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 템플릿을 배치하기만 하면 라우트가 생성됩니다. 기본 마운트 디렉터리는 resources/views/pages이며, 서비스 프로바이더의 boot 메서드에서 변경할 수 있습니다.

파일을 배치한 즉시 브라우저에서 해당 URL로 접근할 수 있습니다. 예를 들어 pages/schedule.blade.php를 만들면 http://example.com/schedule로 바로 접근 가능합니다.

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

php artisan folio:list

중첩 라우트

디렉터리를 중첩하면 중첩된 URL 구조를 만들 수 있습니다. 예를 들어 /user/profile로 접근하는 페이지를 만들려면 pages/user 디렉터리 안에 profile.blade.php를 생성합니다:

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

인덱스 라우트

특정 디렉터리의 루트 URL에 응답하는 페이지가 필요하다면 해당 디렉터리에 index.blade.php를 생성합니다:

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

라우트 파라미터

URL의 특정 세그먼트 값을 페이지 내에서 사용하려면 파일명의 해당 부분을 대괄호([])로 감쌉니다. 예를 들어 사용자 ID를 URL에서 받으려면 다음과 같이 파일을 생성합니다:

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

캡처된 값은 Blade 템플릿 안에서 동일한 이름의 변수로 바로 사용할 수 있습니다:

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

여러 세그먼트를 한 번에 캡처하려면 변수명 앞에 ...을 붙입니다:

php artisan make:folio "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 make:folio "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 make:folio "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');

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 명령을 감지하여 페이지 정의와 라우트 이름을 함께 캐싱하므로, 프로덕션 환경에서 최적의 성능을 발휘합니다.