Blade 템플릿
업데이트됨번역일: 2026년 11월 15일
이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.
- 원문 수정
- 2026년 11월 17일
- 번역 갱신
- 2026년 11월 15일
Blade 템플릿
소개
Blade는 Laravel에 기본으로 포함된 간결하면서도 강력한 템플릿 엔진입니다. 일부 PHP 템플릿 엔진과 달리 Blade는 템플릿 안에서 순수 PHP 코드를 사용하는 것을 제한하지 않습니다. 사실 모든 Blade 템플릿은 순수 PHP 코드로 컴파일된 뒤 수정되기 전까지 캐시되므로, Blade가 애플리케이션에 추가하는 오버헤드는 사실상 없다고 보셔도 됩니다. Blade 템플릿 파일은 .blade.php 확장자를 사용하며, 보통 resources/views 디렉토리에 저장합니다.
Blade 뷰는 전역 view 헬퍼를 사용해 라우트나 컨트롤러에서 반환할 수 있습니다. 뷰 문서에서 설명한 것처럼, view 헬퍼의 두 번째 인자로 Blade 뷰에 데이터를 전달할 수 있습니다.
Route::get('/', function () {
return view('greeting', ['name' => 'Finn']);
});Livewire로 Blade 강화하기
Blade 템플릿을 한 단계 끌어올려 동적인 인터페이스를 손쉽게 만들고 싶으신가요? Laravel Livewire를 살펴보세요. Livewire를 사용하면 React, Svelte, Vue 같은 프론트엔드 프레임워크로만 가능했던 동적인 기능을 Blade 컴포넌트에 더할 수 있습니다. 많은 JavaScript 프레임워크가 요구하는 복잡함, 클라이언트 사이드 렌더링, 빌드 과정 없이도 모던하고 반응성 있는 프론트엔드를 만들 수 있는 좋은 방법입니다.
데이터 출력
Blade 뷰에 전달된 데이터는 변수를 중괄호로 감싸서 출력할 수 있습니다. 예를 들어 다음과 같은 라우트가 있다고 해보겠습니다.
Route::get('/', function () {
return view('welcome', ['name' => 'Samantha']);
});name 변수의 내용은 다음과 같이 출력할 수 있습니다.
Hello, {{ $name }}.NOTE
Blade의 {{ }} echo 구문은 XSS 공격을 방지하기 위해 PHP의 htmlspecialchars 함수를 자동으로 거쳐 출력됩니다.
뷰에 전달된 변수의 내용만 출력할 수 있는 것은 아닙니다. 어떤 PHP 함수의 결과든 echo로 출력할 수 있습니다. 사실 Blade echo 구문 안에는 원하는 PHP 코드를 무엇이든 넣을 수 있습니다.
The current UNIX timestamp is {{ time() }}.HTML 엔티티 인코딩
기본적으로 Blade(그리고 Laravel의 e 함수)는 HTML 엔티티를 이중 인코딩(double encode)합니다. 이중 인코딩을 끄고 싶다면 AppServiceProvider의 boot 메서드에서 Blade::withoutDoubleEncoding 메서드를 호출하세요.
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::withoutDoubleEncoding();
}
}이스케이프되지 않은 데이터 출력
기본적으로 Blade {{ }} 구문은 XSS 공격을 방지하기 위해 PHP의 htmlspecialchars 함수를 자동으로 거칩니다. 데이터를 이스케이프하고 싶지 않다면 다음 구문을 사용하면 됩니다.
Hello, {!! $name !!}.또는 문자열을 Illuminate\Support\HtmlString 인스턴스로 감쌀 수도 있습니다. Blade는 이 인스턴스를 {{ }} 구문으로 출력하더라도 이스케이프하지 않습니다.
use Illuminate\Support\HtmlString;
$name = new HtmlString('<strong>Taylor</strong>');Hello, {{ $name }}.WARNING
애플리케이션 사용자가 입력한 내용을 echo로 출력할 때는 각별히 주의하세요. 사용자가 제공한 데이터를 표시할 때는 XSS 공격을 방지하기 위해 일반적으로 이스케이프되는 이중 중괄호 구문을 사용해야 합니다.
Blade와 JavaScript 프레임워크
많은 JavaScript 프레임워크 역시 브라우저에 표현식을 출력한다는 의미로 "중괄호"를 사용합니다. 이럴 때는 @ 기호를 붙여 Blade 렌더링 엔진에게 해당 표현식을 건드리지 말라고 알려줄 수 있습니다. 예를 들면 다음과 같습니다.
<h1>Laravel</h1>
Hello, @{{ name }}.이 예제에서 @ 기호는 Blade가 제거하지만, {{ name }} 표현식은 Blade 엔진이 건드리지 않고 그대로 남습니다. 따라서 JavaScript 프레임워크가 이를 렌더링할 수 있습니다.
@ 기호는 Blade 디렉티브를 이스케이프하는 데에도 사용할 수 있습니다.
{{-- Blade template --}}
@@if()
<!-- HTML output -->
@if()JSON 렌더링
JavaScript 변수를 초기화하려는 목적으로 배열을 뷰에 전달해 JSON으로 렌더링해야 할 때가 있습니다. 예를 들면 다음과 같습니다.
<script>
var app = <?php echo json_encode($array); ?>;
</script>하지만 json_encode를 직접 호출하는 대신 Illuminate\Support\Js::from 메서드를 사용할 수 있습니다. from 메서드는 PHP의 json_encode 함수와 동일한 인자를 받으면서, 결과 JSON이 HTML 따옴표 안에 안전하게 들어갈 수 있도록 올바르게 이스케이프되도록 보장합니다. from 메서드는 주어진 객체나 배열을 유효한 JavaScript 객체로 변환하는 JSON.parse JavaScript 구문을 문자열로 반환합니다.
<script>
var app = {{ Illuminate\Support\Js::from($array) }};
</script>최신 버전의 Laravel 애플리케이션 스켈레톤에는 Js 파사드가 포함되어 있어, Blade 템플릿 안에서 이 기능을 더 편리하게 사용할 수 있습니다.
<script>
var app = {{ Js::from($array) }};
</script>WARNING
Js::from 메서드는 이미 존재하는 변수를 JSON으로 렌더링할 때만 사용해야 합니다. Blade 템플릿은 정규 표현식을 기반으로 동작하므로, 복잡한 표현식을 이 디렉티브에 전달하면 예기치 않은 오류가 발생할 수 있습니다.
`@verbatim` 디렉티브
템플릿의 상당 부분에서 JavaScript 변수를 표시한다면, HTML을 @verbatim 디렉티브로 감싸 보세요. 그러면 각 Blade echo 구문마다 @ 기호를 일일이 붙이지 않아도 됩니다.
@verbatim
<div class="container">
Hello, {{ name }}.
</div>
@endverbatimBlade 디렉티브
Blade는 템플릿 상속과 데이터 출력 외에도, 조건문과 반복문 같은 PHP의 일반적인 제어 구조를 위한 편리한 단축 구문을 제공합니다. 이 단축 구문을 사용하면 PHP 제어 구조를 아주 깔끔하고 간결하게 다룰 수 있으며, 기존 PHP 구문과 비슷해서 익숙하게 사용할 수 있습니다.
If 문
@if, @elseif, @else, @endif 디렉티브를 사용해 if 문을 작성할 수 있습니다. 이 디렉티브들은 PHP의 if 문과 동일하게 동작합니다.
@if (count($records) === 1)
I have one record!
@elseif (count($records) > 1)
I have multiple records!
@else
I don't have any records!
@endif편의를 위해 Blade는 @unless 디렉티브도 제공합니다.
@unless (Auth::check())
You are not signed in.
@endunless지금까지 설명한 조건 디렉티브 외에도, @isset과 @empty 디렉티브를 각각 대응하는 PHP 함수의 단축 구문으로 사용할 수 있습니다.
@isset($records)
// $records is defined and is not null...
@endisset
@empty($records)
// $records is "empty"...
@endempty인증 디렉티브
@auth와 @guest 디렉티브를 사용하면 현재 사용자가 인증된 사용자인지 게스트인지 빠르게 판단할 수 있습니다.
@auth
// The user is authenticated...
@endauth
@guest
// The user is not authenticated...
@endguest필요하다면 @auth와 @guest 디렉티브를 사용할 때 확인할 인증 가드를 지정할 수도 있습니다.
@auth('admin')
// The user is authenticated...
@endauth
@guest('admin')
// The user is not authenticated...
@endguest환경 디렉티브
@production 디렉티브를 사용하면 애플리케이션이 프로덕션 환경에서 실행 중인지 확인할 수 있습니다.
@production
// Production specific content...
@endproduction또는 @env 디렉티브를 사용해 애플리케이션이 특정 환경에서 실행 중인지 확인할 수도 있습니다.
@env('staging')
// The application is running in "staging"...
@endenv
@env(['staging', 'production'])
// The application is running in "staging" or "production"...
@endenv섹션 디렉티브
@hasSection 디렉티브를 사용하면 템플릿 상속의 섹션에 내용이 있는지 확인할 수 있습니다.
@hasSection('navigation')
<div class="pull-right">
@yield('navigation')
</div>
<div class="clearfix"></div>
@endifsectionMissing 디렉티브를 사용하면 섹션에 내용이 없는지 확인할 수 있습니다.
@sectionMissing('navigation')
<div class="pull-right">
@include('default-navigation')
</div>
@endif세션 디렉티브
@session 디렉티브를 사용하면 세션 값이 존재하는지 확인할 수 있습니다. 세션 값이 존재하면 @session과 @endsession 디렉티브 사이의 템플릿 내용이 평가됩니다. @session 디렉티브의 내용 안에서는 $value 변수를 출력해 세션 값을 표시할 수 있습니다.
@session('status')
<div class="p-4 bg-green-100">
{{ $value }}
</div>
@endsession컨텍스트 디렉티브
@context 디렉티브를 사용하면 컨텍스트 값이 존재하는지 확인할 수 있습니다. 컨텍스트 값이 존재하면 @context와 @endcontext 디렉티브 사이의 템플릿 내용이 평가됩니다. @context 디렉티브의 내용 안에서는 $value 변수를 출력해 컨텍스트 값을 표시할 수 있습니다.
@context('canonical')
<link href="{{ $value }}" rel="canonical">
@endcontextSwitch 문
@switch, @case, @break, @default, @endswitch 디렉티브를 사용해 switch 문을 작성할 수 있습니다.
@switch($i)
@case(1)
First case...
@break
@case(2)
Second case...
@break
@default
Default case...
@endswitch반복문
Blade는 조건문 외에도 PHP의 반복 구조를 다루기 위한 간단한 디렉티브를 제공합니다. 이 디렉티브들 역시 각각 PHP의 반복문과 동일하게 동작합니다.
@for ($i = 0; $i < 10; $i++)
The current value is {{ $i }}
@endfor
@foreach ($users as $user)
<p>This is user {{ $user->id }}</p>
@endforeach
@forelse ($users as $user)
<li>{{ $user->name }}</li>
@empty
<p>No users</p>
@endforelse
@while (true)
<p>I'm looping forever.</p>
@endwhileNOTE
foreach 반복문을 순회하는 동안에는 loop 변수를 사용해 현재 반복이 처음인지 마지막인지 등, 반복문에 대한 유용한 정보를 얻을 수 있습니다.
반복문을 사용할 때 @continue와 @break 디렉티브로 현재 반복을 건너뛰거나 반복문을 종료할 수도 있습니다.
@foreach ($users as $user)
@if ($user->type == 1)
@continue
@endif
<li>{{ $user->name }}</li>
@if ($user->number == 5)
@break
@endif
@endforeach디렉티브 선언부에 continue 또는 break 조건을 함께 작성할 수도 있습니다.
@foreach ($users as $user)
@continue($user->type == 1)
<li>{{ $user->name }}</li>
@break($user->number == 5)
@endforeachLoop 변수
foreach 반복문을 순회하는 동안 반복문 안에서 $loop 변수를 사용할 수 있습니다. 이 변수는 현재 반복문의 인덱스, 첫 번째 또는 마지막 반복 여부 등 유용한 정보를 제공합니다.
@foreach ($users as $user)
@if ($loop->first)
This is the first iteration.
@endif
@if ($loop->last)
This is the last iteration.
@endif
<p>This is user {{ $user->id }}</p>
@endforeach중첩된 반복문 안에 있다면 parent 프로퍼티로 부모 반복문의 $loop 변수에 접근할 수 있습니다.
@foreach ($users as $user)
@foreach ($user->posts as $post)
@if ($loop->parent->first)
This is the first iteration of the parent loop.
@endif
@endforeach
@endforeach$loop 변수에는 이 밖에도 다양한 유용한 프로퍼티가 있습니다.
| 프로퍼티 | 설명 |
|---|---|
$loop->index | 현재 반복의 인덱스(0부터 시작) |
$loop->iteration | 현재 반복 횟수(1부터 시작) |
$loop->remaining | 반복문에 남은 반복 횟수 |
$loop->count | 순회 중인 배열의 전체 항목 수 |
$loop->first | 반복문의 첫 번째 반복인지 여부 |
$loop->last | 반복문의 마지막 반복인지 여부 |
$loop->even | 반복문의 짝수 번째 반복인지 여부 |
$loop->odd | 반복문의 홀수 번째 반복인지 여부 |
$loop->depth | 현재 반복문의 중첩 단계 |
$loop->parent | 중첩된 반복문일 때 부모 반복문의 loop 변수 |
조건부 클래스와 스타일
@class 디렉티브는 CSS 클래스 문자열을 조건에 따라 컴파일합니다. 이 디렉티브는 클래스 배열을 받으며, 배열의 키에는 추가하려는 클래스(들)를, 값에는 불리언 표현식을 지정합니다. 배열 요소의 키가 숫자라면 해당 클래스는 렌더링되는 클래스 목록에 항상 포함됩니다.
@php
$isActive = false;
$hasError = true;
@endphp
<span @class([
'p-4',
'font-bold' => $isActive,
'text-gray-500' => ! $isActive,
'bg-red' => $hasError,
])></span>
<span class="p-4 text-gray-500 bg-red"></span>마찬가지로 @style 디렉티브를 사용하면 HTML 요소에 인라인 CSS 스타일을 조건에 따라 추가할 수 있습니다.
@php
$isActive = true;
@endphp
<span @style([
'background-color: red',
'font-weight: bold' => $isActive,
])></span>
<span style="background-color: red; font-weight: bold;"></span>추가 속성
편의를 위해 @checked 디렉티브를 사용하면 HTML 체크박스 input이 "checked" 상태인지 쉽게 지정할 수 있습니다. 이 디렉티브는 전달한 조건이 true로 평가되면 checked를 출력합니다.
<input
type="checkbox"
name="active"
value="active"
@checked(old('active', $user->active))
/>마찬가지로 @selected 디렉티브는 select 옵션이 "selected" 상태가 되어야 하는지를 지정할 때 사용합니다.
<select name="version">
@foreach ($product->versions as $version)
<option value="{{ $version }}" @selected(old('version') == $version)>
{{ $version }}
</option>
@endforeach
</select>또한 @disabled 디렉티브는 요소가 "disabled" 상태가 되어야 하는지를 지정할 때 사용합니다.
<button type="submit" @disabled($errors->isNotEmpty())>Submit</button>@readonly 디렉티브는 요소가 "readonly" 상태가 되어야 하는지를 지정할 때 사용합니다.
<input
type="email"
name="email"
value="email@laravel.com"
@readonly($user->isNotAdmin())
/>@required 디렉티브는 요소가 "required" 상태가 되어야 하는지를 지정할 때 사용합니다.
<input
type="text"
name="title"
value="title"
@required($user->isAdmin())
/>서브뷰 포함하기
NOTE
@include 디렉티브를 자유롭게 사용해도 되지만, Blade 컴포넌트는 비슷한 기능을 제공하면서 데이터 및 속성 바인딩 같은 여러 장점이 있어 @include 디렉티브보다 유리합니다.
Blade의 @include 디렉티브를 사용하면 다른 뷰 안에서 Blade 뷰를 포함할 수 있습니다. 부모 뷰에서 사용할 수 있는 모든 변수는 포함된 뷰에서도 사용할 수 있습니다.
<div>
@include('shared.errors')
<form>
<!-- Form Contents -->
</form>
</div>포함된 뷰는 부모 뷰의 모든 데이터를 상속받지만, 포함된 뷰에서 사용할 추가 데이터를 배열로 전달할 수도 있습니다.
@include('view.name', ['status' => 'complete'])존재하지 않는 뷰를 @include하려고 하면 Laravel이 오류를 발생시킵니다. 뷰가 존재할 수도, 존재하지 않을 수도 있는 경우에는 @includeIf 디렉티브를 사용해야 합니다.
@includeIf('view.name', ['status' => 'complete'])주어진 불리언 표현식이 true 또는 false로 평가될 때 뷰를 @include하려면 @includeWhen과 @includeUnless 디렉티브를 사용할 수 있습니다.
@includeWhen($boolean, 'view.name', ['status' => 'complete'])
@includeUnless($boolean, 'view.name', ['status' => 'complete'])주어진 뷰 배열 중에서 존재하는 첫 번째 뷰를 포함하려면 includeFirst 디렉티브를 사용할 수 있습니다.
@includeFirst(['custom.admin', 'admin'], ['status' => 'complete'])부모 뷰의 변수를 전혀 상속받지 않고 뷰를 포함하려면 @includeIsolated 디렉티브를 사용할 수 있습니다. 이렇게 포함된 뷰는 명시적으로 전달한 변수에만 접근할 수 있습니다.
@includeIsolated('view.name', ['user' => $user])WARNING
Blade 뷰에서는 __DIR__와 __FILE__ 상수를 사용하지 않는 것이 좋습니다. 이 상수들은 캐시된 컴파일 뷰의 위치를 가리키기 때문입니다.
컬렉션을 위한 뷰 렌더링
Blade의 @each 디렉티브를 사용하면 반복문과 include를 한 줄로 합칠 수 있습니다.
@each('view.name', $jobs, 'job')@each 디렉티브의 첫 번째 인자는 배열이나 컬렉션의 각 요소에 대해 렌더링할 뷰입니다. 두 번째 인자는 순회할 배열 또는 컬렉션이며, 세 번째 인자는 뷰 안에서 현재 반복 요소에 할당될 변수 이름입니다. 예를 들어 jobs 배열을 순회한다면, 보통 뷰 안에서 각 Job을 job 변수로 접근하고 싶을 것입니다. 현재 반복의 배열 키는 뷰 안에서 key 변수로 사용할 수 있습니다.
@each 디렉티브에는 네 번째 인자도 전달할 수 있습니다. 이 인자는 주어진 배열이 비어 있을 때 렌더링할 뷰를 지정합니다.
@each('view.name', $jobs, 'job', 'view.empty')WARNING
@each로 렌더링한 뷰는 부모 뷰의 변수를 상속받지 않습니다. 자식 뷰에서 이 변수들이 필요하다면 @foreach와 @include 디렉티브를 대신 사용해야 합니다.
`@once` 디렉티브
@once 디렉티브를 사용하면 템플릿의 일부를 렌더링 주기당 한 번만 평가하도록 정의할 수 있습니다. 스택을 이용해 특정 JavaScript를 페이지 헤더에 푸시할 때 유용합니다. 예를 들어 반복문 안에서 특정 컴포넌트를 렌더링한다면, 컴포넌트가 처음 렌더링될 때만 JavaScript를 헤더에 푸시하고 싶을 수 있습니다.
@once
@push('scripts')
<script>
// Your custom JavaScript...
</script>
@endpush
@endonce@once 디렉티브는 @push 또는 @prepend 디렉티브와 함께 쓰는 경우가 많기 때문에, 편의를 위해 @pushOnce와 @prependOnce 디렉티브도 제공됩니다.
@pushOnce('scripts')
<script>
// Your custom JavaScript...
</script>
@endPushOnce서로 다른 두 Blade 템플릿에서 중복된 내용을 푸시하는 경우에는, 내용이 한 번만 렌더링되도록 @pushOnce 디렉티브의 두 번째 인자로 고유 식별자를 지정해야 합니다.
<!-- pie-chart.blade.php -->
@pushOnce('scripts', 'chart.js')
<script src="/chart.js"></script>
@endPushOnce
<!-- line-chart.blade.php -->
@pushOnce('scripts', 'chart.js')
<script src="/chart.js"></script>
@endPushOnce순수 PHP
뷰에 PHP 코드를 직접 넣는 것이 유용한 상황도 있습니다. Blade의 @php 디렉티브를 사용하면 템플릿 안에서 순수 PHP 블록을 실행할 수 있습니다.
@php
$counter = 1;
@endphp또는 PHP를 클래스를 import하는 용도로만 쓴다면 @use 디렉티브를 사용할 수 있습니다.
@use('App\Models\Flight')@use 디렉티브에 두 번째 인자를 전달하면 import한 클래스에 별칭(alias)을 지정할 수 있습니다.
@use('App\Models\Flight', 'FlightModel')같은 네임스페이스에 속한 클래스가 여러 개라면 import를 그룹으로 묶을 수 있습니다.
@use('App\Models\{Flight, Airport}')@use 디렉티브는 import 경로 앞에 function 또는 const 수정자를 붙여 PHP 함수와 상수를 import하는 것도 지원합니다.
@use(function App\Helpers\format_currency)
@use(const App\Constants\MAX_ATTEMPTS)클래스 import와 마찬가지로 함수와 상수에도 별칭을 지정할 수 있습니다.
@use(function App\Helpers\format_currency, 'formatMoney')
@use(const App\Constants\MAX_ATTEMPTS, 'MAX_TRIES')function과 const 수정자에서도 그룹 import를 지원하므로, 같은 네임스페이스의 여러 심볼을 하나의 디렉티브로 import할 수 있습니다.
@use(function App\Helpers\{format_currency, format_date})
@use(const App\Constants\{MAX_ATTEMPTS, DEFAULT_TIMEOUT})폰트
Laravel의 Vite 폰트 최적화를 사용 중이라면, @fonts 디렉티브로 설정해 둔 폰트의 preload 링크와 인라인 폰트 CSS를 애플리케이션 레이아웃에 렌더링할 수 있습니다.
<!doctype html>
<head>
{{-- ... --}}
@fonts
@vite('resources/js/app.js')
</head>@fonts 디렉티브는 vite.config.js 파일에 설정한 모든 폰트 패밀리를 렌더링합니다. 이 디렉티브는 보통 애플리케이션 루트 레이아웃의 <head> 안에서, 해당 폰트를 사용하는 콘텐츠보다 앞에 두는 것이 좋습니다.
특정 페이지에서 설정해 둔 폰트 중 일부만 필요하다면, 디렉티브에 하나 이상의 폰트 별칭(alias)을 전달할 수 있습니다.
{{-- Load a single font alias... --}}
@fonts('sans')
{{-- Load multiple font aliases... --}}
@fonts(['sans', 'mono'])폰트 별칭은 Vite 설정에서 폰트를 정의할 때 alias 옵션으로 지정합니다. @fonts 디렉티브는 Vite 파사드가 제공하는 fonts 메서드를 호출하며, 이 메서드는 직접 호출할 수도 있습니다.
{{ Vite::fonts(['sans', 'mono']) }}주석
Blade에서는 뷰에 주석을 정의할 수도 있습니다. 다만 HTML 주석과 달리 Blade 주석은 애플리케이션이 반환하는 HTML에 포함되지 않습니다.
{{-- This comment will not be present in the rendered HTML --}}컴포넌트
컴포넌트와 슬롯은 섹션, 레이아웃, include와 비슷한 이점을 제공합니다. 다만 컴포넌트와 슬롯의 사고 모델이 더 이해하기 쉽다고 느끼는 분도 있습니다. 컴포넌트를 작성하는 방식에는 클래스 기반 컴포넌트와 익명 컴포넌트, 두 가지가 있습니다.
클래스 기반 컴포넌트를 만들려면 make:component Artisan 명령어를 사용합니다. 컴포넌트 사용법을 설명하기 위해 간단한 Alert 컴포넌트를 만들어 보겠습니다. make:component 명령어는 컴포넌트를 app/View/Components 디렉토리에 생성합니다.
php artisan make:component Alertmake:component 명령어는 컴포넌트의 뷰 템플릿도 함께 생성합니다. 뷰는 resources/views/components 디렉토리에 만들어집니다. 애플리케이션에서 직접 컴포넌트를 작성할 때는 app/View/Components 디렉토리와 resources/views/components 디렉토리 안의 컴포넌트가 자동으로 발견되므로, 보통 별도의 컴포넌트 등록이 필요하지 않습니다.
하위 디렉토리 안에 컴포넌트를 만들 수도 있습니다.
php artisan make:component Forms/Input위 명령어는 app/View/Components/Forms 디렉토리에 Input 컴포넌트를 만들고, 뷰는 resources/views/components/forms 디렉토리에 생성합니다.
패키지 컴포넌트 수동 등록
애플리케이션에서 컴포넌트를 작성할 때는 app/View/Components 디렉토리와 resources/views/components 디렉토리 안의 컴포넌트가 자동으로 발견됩니다.
하지만 Blade 컴포넌트를 사용하는 패키지를 만든다면, 컴포넌트 클래스와 HTML 태그 별칭을 수동으로 등록해야 합니다. 보통 패키지 서비스 프로바이더의 boot 메서드에서 컴포넌트를 등록합니다.
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::component('package-alert', Alert::class);
}컴포넌트를 등록한 뒤에는 태그 별칭으로 렌더링할 수 있습니다.
<x-package-alert/>또는 componentNamespace 메서드를 사용해 규칙에 따라 컴포넌트 클래스를 자동 로드할 수도 있습니다. 예를 들어 Nightshade 패키지에 Nightshade\Views\Components 네임스페이스에 속한 Calendar와 ColorPicker 컴포넌트가 있다고 해보겠습니다.
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::componentNamespace('Nightshade\\Views\\Components', 'nightshade');
}이렇게 하면 package-name:: 구문을 사용해 벤더 네임스페이스로 패키지 컴포넌트를 사용할 수 있습니다.
<x-nightshade::calendar />
<x-nightshade::color-picker />Blade는 컴포넌트 이름을 파스칼 케이스로 변환해, 이 컴포넌트와 연결된 클래스를 자동으로 찾습니다. "점(.)" 표기법을 사용하면 하위 디렉토리도 지원됩니다.
컴포넌트 렌더링
컴포넌트를 표시하려면 Blade 템플릿 안에서 Blade 컴포넌트 태그를 사용합니다. Blade 컴포넌트 태그는 x- 문자열로 시작하고, 그 뒤에 컴포넌트 클래스 이름을 케밥 케이스로 붙입니다.
<x-alert/>
<x-user-profile/>컴포넌트 클래스가 app/View/Components 디렉토리 아래에 더 깊게 중첩되어 있다면 . 문자로 디렉토리 중첩을 나타낼 수 있습니다. 예를 들어 컴포넌트가 app/View/Components/Inputs/Button.php에 있다면 다음과 같이 렌더링합니다.
<x-inputs.button/>컴포넌트를 조건부로 렌더링하고 싶다면 컴포넌트 클래스에 shouldRender 메서드를 정의하면 됩니다. shouldRender 메서드가 false를 반환하면 컴포넌트는 렌더링되지 않습니다.
use Illuminate\Support\Str;
/**
* Whether the component should be rendered
*/
public function shouldRender(): bool
{
return Str::length($this->message) > 0;
}인덱스 컴포넌트
컴포넌트가 컴포넌트 그룹의 일부여서, 관련 컴포넌트를 하나의 디렉토리에 묶고 싶을 때가 있습니다. 예를 들어 다음과 같은 클래스 구조를 가진 "card" 컴포넌트를 생각해 보겠습니다.
App\View\Components\Card\Card
App\View\Components\Card\Header
App\View\Components\Card\Body루트 Card 컴포넌트가 Card 디렉토리 안에 중첩되어 있으므로, <x-card.card>로 렌더링해야 한다고 생각할 수 있습니다. 하지만 컴포넌트의 파일 이름이 컴포넌트가 위치한 디렉토리 이름과 같으면, Laravel은 해당 컴포넌트를 "루트" 컴포넌트로 간주합니다. 그래서 디렉토리 이름을 반복하지 않고도 컴포넌트를 렌더링할 수 있습니다.
<x-card>
<x-card.header>...</x-card.header>
<x-card.body>...</x-card.body>
</x-card>컴포넌트에 데이터 전달하기
HTML 속성을 사용해 Blade 컴포넌트에 데이터를 전달할 수 있습니다. 하드코딩된 원시 값은 단순한 HTML 속성 문자열로 전달할 수 있습니다. PHP 표현식과 변수는 : 문자를 접두사로 붙인 속성을 통해 전달해야 합니다.
<x-alert type="error" :message="$message"/>컴포넌트의 모든 데이터 속성은 클래스 생성자에 정의해야 합니다. 컴포넌트의 모든 public 프로퍼티는 컴포넌트 뷰에서 자동으로 사용할 수 있게 됩니다. 컴포넌트의 render 메서드에서 데이터를 뷰로 따로 전달할 필요는 없습니다.
<?php
namespace App\View\Components;
use Illuminate\View\Component;
use Illuminate\View\View;
class Alert extends Component
{
/**
* Create the component instance.
*/
public function __construct(
public string $type,
public string $message,
) {}
/**
* Get the view / contents that represent the component.
*/
public function render(): View
{
return view('components.alert');
}
}컴포넌트가 렌더링될 때, 컴포넌트의 public 변수를 이름으로 echo해서 그 내용을 표시할 수 있습니다.
<div class="alert alert-{{ $type }}">
{{ $message }}
</div>대소문자 표기
컴포넌트 생성자 인자는 camelCase로 지정하고, HTML 속성에서 인자 이름을 참조할 때는 kebab-case를 사용해야 합니다. 예를 들어 다음과 같은 컴포넌트 생성자가 있다고 해보겠습니다.
/**
* Create the component instance.
*/
public function __construct(
public string $alertType,
) {}$alertType 인자는 다음과 같이 컴포넌트에 전달할 수 있습니다.
<x-alert alert-type="danger" />짧은 속성 문법
컴포넌트에 속성을 전달할 때 "짧은 속성(short attribute)" 문법도 사용할 수 있습니다. 속성 이름이 대응하는 변수 이름과 같은 경우가 많아서 편리합니다.
{{-- Short attribute syntax... --}}
<x-profile :$userId :$name />
{{-- Is equivalent to... --}}
<x-profile :user-id="$userId" :name="$name" />속성 렌더링 이스케이프
Alpine.js 같은 일부 JavaScript 프레임워크도 콜론으로 시작하는 속성을 사용합니다. 이럴 때는 이중 콜론(::) 접두사를 사용해 Blade에게 해당 속성이 PHP 표현식이 아니라고 알려줄 수 있습니다. 예를 들어 다음과 같은 컴포넌트가 있다고 해보겠습니다.
<x-button ::class="{ danger: isDeleting }">
Submit
</x-button>Blade는 다음과 같은 HTML을 렌더링합니다.
<button :class="{ danger: isDeleting }">
Submit
</button>컴포넌트 메서드
컴포넌트 템플릿에서는 public 변수뿐 아니라 컴포넌트의 모든 public 메서드도 호출할 수 있습니다. 예를 들어 isSelected 메서드를 가진 컴포넌트가 있다고 해보겠습니다.
/**
* Determine if the given option is the currently selected option.
*/
public function isSelected(string $option): bool
{
return $option === $this->selected;
}컴포넌트 템플릿에서는 메서드 이름과 같은 변수를 호출하는 방식으로 이 메서드를 실행할 수 있습니다.
<option {{ $isSelected($value) ? 'selected' : '' }} value="{{ $value }}">
{{ $label }}
</option>컴포넌트 클래스 안에서 속성과 슬롯에 접근하기
Blade 컴포넌트에서는 클래스의 render 메서드 안에서 컴포넌트 이름, 속성, 슬롯에 접근할 수도 있습니다. 다만 이 데이터에 접근하려면 컴포넌트의 render 메서드에서 클로저를 반환해야 합니다.
use Closure;
/**
* Get the view / contents that represent the component.
*/
public function render(): Closure
{
return function () {
return '<div {{ $attributes }}>Components content</div>';
};
}컴포넌트의 render 메서드가 반환하는 클로저는 $data 배열을 유일한 인자로 받을 수도 있습니다. 이 배열에는 컴포넌트에 대한 정보를 제공하는 여러 요소가 들어 있습니다.
return function (array $data) {
// $data['componentName'];
// $data['attributes'];
// $data['slot'];
return '<div {{ $attributes }}>Components content</div>';
};WARNING
$data 배열의 요소를 render 메서드가 반환하는 Blade 문자열에 직접 삽입해서는 안 됩니다. 악의적인 속성 내용을 통해 원격 코드 실행이 가능해질 수 있기 때문입니다.
componentName은 HTML 태그에서 x- 접두사 뒤에 쓴 이름과 같습니다. 따라서 <x-alert />의 componentName은 alert가 됩니다. attributes 요소에는 HTML 태그에 있던 모든 속성이 들어 있습니다. slot 요소는 컴포넌트 슬롯의 내용을 담은 Illuminate\View\ComponentSlot 인스턴스입니다.
클로저는 문자열을 반환해야 합니다. 반환된 문자열이 존재하는 뷰에 해당하면 그 뷰가 렌더링되고, 그렇지 않으면 반환된 문자열이 인라인 Blade 뷰로 평가됩니다.
추가 의존성
컴포넌트가 Laravel 서비스 컨테이너의 의존성을 필요로 한다면, 컴포넌트의 데이터 속성보다 앞에 나열하세요. 그러면 컨테이너가 자동으로 주입해 줍니다.
use App\Services\AlertCreator;
/**
* Create the component instance.
*/
public function __construct(
public AlertCreator $creator,
public string $type,
public string $message,
) {}속성 / 메서드 숨기기
일부 public 메서드나 프로퍼티를 컴포넌트 템플릿에 변수로 노출하고 싶지 않다면, 컴포넌트의 $except 배열 프로퍼티에 추가하면 됩니다.
<?php
namespace App\View\Components;
use Illuminate\View\Component;
class Alert extends Component
{
/**
* The properties / methods that should not be exposed to the component template.
*
* @var array
*/
protected $except = ['type'];
/**
* Create the component instance.
*/
public function __construct(
public string $type,
) {}
}컴포넌트 속성
지금까지 컴포넌트에 데이터 속성을 전달하는 방법을 살펴보았습니다. 하지만 컴포넌트가 동작하는 데 필요한 데이터는 아니지만 class처럼 추가 HTML 속성을 지정해야 할 때가 있습니다. 보통 이런 추가 속성은 컴포넌트 템플릿의 루트 요소로 전달하고 싶을 것입니다. 예를 들어 다음과 같이 alert 컴포넌트를 렌더링한다고 해보겠습니다.
<x-alert type="error" :message="$message" class="mt-4"/>컴포넌트 생성자에 포함되지 않은 모든 속성은 컴포넌트의 "속성 백(attribute bag)"에 자동으로 추가됩니다. 이 속성 백은 $attributes 변수를 통해 컴포넌트에서 자동으로 사용할 수 있습니다. 이 변수를 echo하면 컴포넌트 안에서 모든 속성을 렌더링할 수 있습니다.
<div {{ $attributes }}>
<!-- Component content -->
</div>WARNING
컴포넌트 태그 안에서 @env 같은 디렉티브를 사용하는 것은 현재 지원되지 않습니다. 예를 들어 <x-alert :live="@env('production')"/>는 컴파일되지 않습니다.
기본 / 병합 속성
속성에 기본값을 지정하거나, 컴포넌트의 일부 속성에 추가 값을 병합해야 할 때가 있습니다. 이럴 때는 속성 백의 merge 메서드를 사용하면 됩니다. 이 메서드는 컴포넌트에 항상 적용되어야 하는 기본 CSS 클래스를 정의할 때 특히 유용합니다.
<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
{{ $message }}
</div>이 컴포넌트를 다음과 같이 사용한다고 가정해 보겠습니다.
<x-alert type="error" :message="$message" class="mb-4"/>그러면 컴포넌트가 최종적으로 렌더링하는 HTML은 다음과 같습니다.
<div class="alert alert-error mb-4">
<!-- Contents of the $message variable -->
</div>조건부로 클래스 병합하기
주어진 조건이 true일 때만 클래스를 병합하고 싶을 때가 있습니다. 이럴 때는 class 메서드를 사용할 수 있습니다. 이 메서드는 클래스 배열을 받으며, 배열의 키에는 추가하려는 클래스(들)를, 값에는 불리언 표현식을 지정합니다. 배열 요소의 키가 숫자라면 해당 클래스는 렌더링되는 클래스 목록에 항상 포함됩니다.
<div {{ $attributes->class(['p-4', 'bg-red' => $hasError]) }}>
{{ $message }}
</div>컴포넌트에 다른 속성을 병합해야 한다면 class 메서드 뒤에 merge 메서드를 체이닝할 수 있습니다.
<button {{ $attributes->class(['p-4'])->merge(['type' => 'button']) }}>
{{ $slot }}
</button>NOTE
병합된 속성을 받지 않아야 하는 다른 HTML 요소에서 클래스를 조건부로 컴파일해야 한다면 @class 디렉티브를 사용할 수 있습니다.
클래스가 아닌 속성의 병합
class가 아닌 속성을 병합할 때, merge 메서드에 전달한 값은 해당 속성의 "기본값"으로 간주됩니다. 하지만 class 속성과 달리 이런 속성은 주입된 속성 값과 병합되지 않고 덮어쓰기됩니다. 예를 들어 button 컴포넌트의 구현은 다음과 같을 수 있습니다.
<button {{ $attributes->merge(['type' => 'button']) }}>
{{ $slot }}
</button>버튼 컴포넌트를 사용자 지정 type으로 렌더링하려면, 컴포넌트를 사용할 때 해당 값을 지정하면 됩니다. type을 지정하지 않으면 button 타입이 사용됩니다.
<x-button type="submit">
Submit
</x-button>이 예제에서 button 컴포넌트가 렌더링한 HTML은 다음과 같습니다.
<button type="submit">
Submit
</button>class가 아닌 속성도 기본값과 주입된 값을 함께 이어 붙이고 싶다면 prepends 메서드를 사용할 수 있습니다. 다음 예제에서 data-controller 속성은 항상 profile-controller로 시작하고, 추가로 주입된 data-controller 값은 이 기본값 뒤에 위치합니다.
<div {{ $attributes->merge(['data-controller' => $attributes->prepends('profile-controller')]) }}>
{{ $slot }}
</div>속성 조회 및 필터링
filter 메서드로 속성을 필터링할 수 있습니다. 이 메서드는 클로저를 받으며, 속성 백에 해당 속성을 남기려면 클로저가 true를 반환해야 합니다.
{{ $attributes->filter(fn (string $value, string $key) => $key == 'foo') }}편의를 위해 whereStartsWith 메서드를 사용하면 키가 특정 문자열로 시작하는 모든 속성을 가져올 수 있습니다.
{{ $attributes->whereStartsWith('wire:model') }}반대로 whereDoesntStartWith 메서드를 사용하면 키가 특정 문자열로 시작하는 모든 속성을 제외할 수 있습니다.
{{ $attributes->whereDoesntStartWith('wire:model') }}first 메서드를 사용하면 주어진 속성 백에서 첫 번째 속성을 렌더링할 수 있습니다.
{{ $attributes->whereStartsWith('wire:model')->first() }}컴포넌트에 특정 속성이 존재하는지 확인하려면 has 메서드를 사용할 수 있습니다. 이 메서드는 속성 이름을 유일한 인자로 받고, 속성의 존재 여부를 나타내는 불리언 값을 반환합니다.
@if ($attributes->has('class'))
<div>Class attribute is present</div>
@endifhas 메서드에 배열을 전달하면, 주어진 모든 속성이 컴포넌트에 존재하는지 확인합니다.
@if ($attributes->has(['name', 'class']))
<div>All of the attributes are present</div>
@endifhasAny 메서드는 주어진 속성 중 하나라도 컴포넌트에 존재하는지 확인할 때 사용합니다.
@if ($attributes->hasAny(['href', ':href', 'v-bind:href']))
<div>One of the attributes is present</div>
@endifget 메서드를 사용하면 특정 속성의 값을 가져올 수 있습니다.
{{ $attributes->get('class') }}only 메서드는 주어진 키를 가진 속성만 가져올 때 사용합니다.
{{ $attributes->only(['class']) }}except 메서드는 주어진 키를 가진 속성을 제외한 모든 속성을 가져올 때 사용합니다.
{{ $attributes->except(['class']) }}예약어
기본적으로 일부 키워드는 컴포넌트를 렌더링하기 위한 Blade 내부용으로 예약되어 있습니다. 다음 키워드는 컴포넌트 안에서 public 프로퍼티나 메서드 이름으로 정의할 수 없습니다.
datarenderresolveresolveViewshouldRenderviewwithAttributeswithName
슬롯
"슬롯(slot)"을 통해 컴포넌트에 추가 콘텐츠를 전달해야 할 때가 많습니다. 컴포넌트 슬롯은 $slot 변수를 echo해서 렌더링합니다. 이 개념을 살펴보기 위해 alert 컴포넌트가 다음과 같은 마크업을 가지고 있다고 해보겠습니다.
<!-- /resources/views/components/alert.blade.php -->
<div class="alert alert-danger">
{{ $slot }}
</div>컴포넌트 안에 내용을 넣으면 slot에 콘텐츠를 전달할 수 있습니다.
<x-alert>
<strong>Whoops!</strong> Something went wrong!
</x-alert>컴포넌트가 내부의 여러 위치에 서로 다른 슬롯을 여러 개 렌더링해야 할 때도 있습니다. alert 컴포넌트를 수정해 "title" 슬롯을 주입할 수 있게 해보겠습니다.
<!-- /resources/views/components/alert.blade.php -->
<span class="alert-title">{{ $title }}</span>
<div class="alert alert-danger">
{{ $slot }}
</div>x-slot 태그를 사용해 이름이 있는 슬롯의 내용을 정의할 수 있습니다. 명시적인 x-slot 태그 밖에 있는 내용은 모두 $slot 변수로 컴포넌트에 전달됩니다.
<x-alert>
<x-slot:title>
Server Error
</x-slot>
<strong>Whoops!</strong> Something went wrong!
</x-alert>슬롯의 isEmpty 메서드를 호출하면 슬롯에 내용이 있는지 확인할 수 있습니다.
<span class="alert-title">{{ $title }}</span>
<div class="alert alert-danger">
@if ($slot->isEmpty())
This is default content if the slot is empty.
@else
{{ $slot }}
@endif
</div>또한 hasActualContent 메서드를 사용하면 슬롯에 HTML 주석이 아닌 "실제" 내용이 있는지 확인할 수 있습니다.
@if ($slot->hasActualContent())
The scope has non-comment content.
@endif스코프 슬롯
Vue 같은 JavaScript 프레임워크를 사용해 보셨다면 슬롯 안에서 컴포넌트의 데이터나 메서드에 접근할 수 있는 "스코프 슬롯(scoped slot)"에 익숙할 것입니다. Laravel에서도 컴포넌트에 public 메서드나 프로퍼티를 정의하고, 슬롯 안에서 $component 변수를 통해 컴포넌트에 접근하면 비슷한 동작을 구현할 수 있습니다. 이 예제에서는 x-alert 컴포넌트의 클래스에 public formatAlert 메서드가 정의되어 있다고 가정합니다.
<x-alert>
<x-slot:title>
{{ $component->formatAlert('Server Error') }}
</x-slot>
<strong>Whoops!</strong> Something went wrong!
</x-alert>슬롯 속성
Blade 컴포넌트와 마찬가지로 슬롯에도 CSS 클래스 이름 같은 추가 속성을 지정할 수 있습니다.
<x-card class="shadow-sm">
<x-slot:heading class="font-bold">
Heading
</x-slot>
Content
<x-slot:footer class="text-sm">
Footer
</x-slot>
</x-card>슬롯 속성을 다루려면 슬롯 변수의 attributes 프로퍼티에 접근하면 됩니다. 속성을 다루는 방법에 대한 자세한 내용은 컴포넌트 속성 문서를 참고하세요.
@props([
'heading',
'footer',
])
<div {{ $attributes->class(['border']) }}>
<h1 {{ $heading->attributes->class(['text-lg']) }}>
{{ $heading }}
</h1>
{{ $slot }}
<footer {{ $footer->attributes->class(['text-gray-700']) }}>
{{ $footer }}
</footer>
</div>인라인 컴포넌트 뷰
아주 작은 컴포넌트라면 컴포넌트 클래스와 컴포넌트 뷰 템플릿을 모두 관리하는 것이 번거롭게 느껴질 수 있습니다. 이럴 때는 render 메서드에서 컴포넌트의 마크업을 직접 반환할 수 있습니다.
/**
* Get the view / contents that represent the component.
*/
public function render(): string
{
return <<<'blade'
<div class="alert alert-danger">
{{ $slot }}
</div>
blade;
}인라인 뷰 컴포넌트 생성
인라인 뷰를 렌더링하는 컴포넌트를 만들려면 make:component 명령어를 실행할 때 inline 옵션을 사용하면 됩니다.
php artisan make:component Alert --inline동적 컴포넌트
렌더링해야 할 컴포넌트를 런타임이 되어서야 알 수 있는 경우가 있습니다. 이럴 때는 Laravel에 내장된 dynamic-component 컴포넌트를 사용해 런타임 값이나 변수에 따라 컴포넌트를 렌더링할 수 있습니다.
// $componentName = "secondary-button";
<x-dynamic-component :component="$componentName" class="mt-4" />컴포넌트 수동 등록
WARNING
컴포넌트 수동 등록에 관한 다음 내용은 주로 뷰 컴포넌트를 포함하는 Laravel 패키지를 작성하는 분들에게 해당합니다. 패키지를 작성하지 않는다면 컴포넌트 문서의 이 부분은 필요하지 않을 수 있습니다.
애플리케이션에서 컴포넌트를 작성할 때는 app/View/Components 디렉토리와 resources/views/components 디렉토리 안의 컴포넌트가 자동으로 발견됩니다.
하지만 Blade 컴포넌트를 사용하는 패키지를 만들거나 컴포넌트를 관례에 맞지 않는 디렉토리에 두는 경우에는, Laravel이 컴포넌트의 위치를 알 수 있도록 컴포넌트 클래스와 HTML 태그 별칭을 수동으로 등록해야 합니다. 보통 패키지 서비스 프로바이더의 boot 메서드에서 컴포넌트를 등록합니다.
use Illuminate\Support\Facades\Blade;
use VendorPackage\View\Components\AlertComponent;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::component('package-alert', AlertComponent::class);
}컴포넌트를 등록한 뒤에는 태그 별칭으로 렌더링할 수 있습니다.
<x-package-alert/>패키지 컴포넌트 자동 로드
또는 componentNamespace 메서드를 사용해 규칙에 따라 컴포넌트 클래스를 자동 로드할 수도 있습니다. 예를 들어 Nightshade 패키지에 Nightshade\Views\Components 네임스페이스에 속한 Calendar와 ColorPicker 컴포넌트가 있다고 해보겠습니다.
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::componentNamespace('Nightshade\\Views\\Components', 'nightshade');
}이렇게 하면 package-name:: 구문을 사용해 벤더 네임스페이스로 패키지 컴포넌트를 사용할 수 있습니다.
<x-nightshade::calendar />
<x-nightshade::color-picker />Blade는 컴포넌트 이름을 파스칼 케이스로 변환해, 이 컴포넌트와 연결된 클래스를 자동으로 찾습니다. "점(.)" 표기법을 사용하면 하위 디렉토리도 지원됩니다.
익명 컴포넌트
인라인 컴포넌트와 비슷하게, 익명 컴포넌트는 단일 파일로 컴포넌트를 관리하는 방법을 제공합니다. 다만 익명 컴포넌트는 뷰 파일 하나만 사용하며 연결된 클래스가 없습니다. 익명 컴포넌트를 정의하려면 resources/views/components 디렉토리 안에 Blade 템플릿을 두기만 하면 됩니다. 예를 들어 resources/views/components/alert.blade.php에 컴포넌트를 정의했다면 다음과 같이 간단히 렌더링할 수 있습니다.
<x-alert/>컴포넌트가 components 디렉토리 안에 더 깊게 중첩되어 있다면 . 문자로 표시할 수 있습니다. 예를 들어 컴포넌트가 resources/views/components/inputs/button.blade.php에 정의되어 있다면 다음과 같이 렌더링합니다.
<x-inputs.button/>Artisan으로 익명 컴포넌트를 만들려면 make:component 명령어를 실행할 때 --view 플래그를 사용하면 됩니다.
php artisan make:component forms.input --view위 명령어는 resources/views/components/forms/input.blade.php에 Blade 파일을 만들며, 이 파일은 <x-forms.input />으로 컴포넌트처럼 렌더링할 수 있습니다.
익명 인덱스 컴포넌트
컴포넌트가 여러 개의 Blade 템플릿으로 구성될 때, 해당 컴포넌트의 템플릿들을 하나의 디렉토리에 묶고 싶을 수 있습니다. 예를 들어 다음과 같은 디렉토리 구조를 가진 "accordion" 컴포넌트를 생각해 보겠습니다.
/resources/views/components/accordion.blade.php
/resources/views/components/accordion/item.blade.php이 디렉토리 구조에서는 accordion 컴포넌트와 그 item을 다음과 같이 렌더링할 수 있습니다.
<x-accordion>
<x-accordion.item>
...
</x-accordion.item>
</x-accordion>하지만 x-accordion으로 accordion 컴포넌트를 렌더링하려면, "인덱스" accordion 컴포넌트 템플릿을 다른 accordion 관련 템플릿과 함께 accordion 디렉토리 안에 두지 못하고 resources/views/components 디렉토리에 둬야 했습니다.
다행히 Blade에서는 컴포넌트의 디렉토리 이름과 같은 이름의 파일을 그 디렉토리 안에 둘 수 있습니다. 이 템플릿이 존재하면 디렉토리 안에 중첩되어 있더라도 컴포넌트의 "루트" 요소로 렌더링됩니다. 따라서 위 예제와 같은 Blade 문법을 그대로 사용하면서 디렉토리 구조만 다음과 같이 바꿀 수 있습니다.
/resources/views/components/accordion/accordion.blade.php
/resources/views/components/accordion/item.blade.php데이터 프로퍼티 / 속성
익명 컴포넌트는 연결된 클래스가 없으므로, 어떤 데이터를 컴포넌트에 변수로 전달하고 어떤 속성을 컴포넌트의 속성 백에 넣어야 하는지 어떻게 구분하는지 궁금할 수 있습니다.
컴포넌트 Blade 템플릿 상단에서 @props 디렉티브를 사용해 데이터 변수로 취급할 속성을 지정할 수 있습니다. 컴포넌트의 나머지 속성은 모두 속성 백으로 사용할 수 있습니다. 데이터 변수에 기본값을 지정하려면 변수 이름을 배열의 키로, 기본값을 배열의 값으로 지정하면 됩니다.
<!-- /resources/views/components/alert.blade.php -->
@props(['type' => 'info', 'message'])
<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
{{ $message }}
</div>위와 같이 컴포넌트를 정의했다면 다음과 같이 컴포넌트를 렌더링할 수 있습니다.
<x-alert type="error" :message="$message" class="mb-4"/>부모 데이터 접근하기
자식 컴포넌트 안에서 부모 컴포넌트의 데이터에 접근하고 싶을 때가 있습니다. 이럴 때는 @aware 디렉티브를 사용할 수 있습니다. 예를 들어 부모 <x-menu>와 자식 <x-menu.item>으로 구성된 복잡한 메뉴 컴포넌트를 만든다고 해보겠습니다.
<x-menu color="purple">
<x-menu.item>...</x-menu.item>
<x-menu.item>...</x-menu.item>
</x-menu><x-menu> 컴포넌트는 다음과 같이 구현할 수 있습니다.
<!-- /resources/views/components/menu/index.blade.php -->
@props(['color' => 'gray'])
<ul {{ $attributes->merge(['class' => 'bg-'.$color.'-200']) }}>
{{ $slot }}
</ul>color prop은 부모(<x-menu>)에만 전달되었기 때문에 <x-menu.item> 안에서는 사용할 수 없습니다. 하지만 @aware 디렉티브를 사용하면 <x-menu.item> 안에서도 사용할 수 있게 만들 수 있습니다.
<!-- /resources/views/components/menu/item.blade.php -->
@aware(['color' => 'gray'])
<li {{ $attributes->merge(['class' => 'text-'.$color.'-800']) }}>
{{ $slot }}
</li>WARNING
@aware 디렉티브는 HTML 속성을 통해 부모 컴포넌트에 명시적으로 전달되지 않은 부모 데이터에는 접근할 수 없습니다. 부모 컴포넌트에 명시적으로 전달되지 않은 @props의 기본값 역시 @aware 디렉티브로 접근할 수 없습니다.
익명 컴포넌트 경로
앞서 설명했듯이 익명 컴포넌트는 보통 resources/views/components 디렉토리 안에 Blade 템플릿을 두어 정의합니다. 하지만 기본 경로 외에 다른 익명 컴포넌트 경로를 Laravel에 등록하고 싶을 때가 있습니다.
anonymousComponentPath 메서드는 첫 번째 인자로 익명 컴포넌트 위치의 "경로"를, 두 번째 인자로 컴포넌트가 속할 "네임스페이스"(선택 사항)를 받습니다. 보통 이 메서드는 애플리케이션의 서비스 프로바이더 중 하나의 boot 메서드에서 호출합니다.
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::anonymousComponentPath(__DIR__.'/../components');
}위 예제처럼 접두사를 지정하지 않고 컴포넌트 경로를 등록하면, Blade 컴포넌트에서도 해당 접두사 없이 렌더링할 수 있습니다. 예를 들어 위에서 등록한 경로에 panel.blade.php 컴포넌트가 있다면 다음과 같이 렌더링할 수 있습니다.
<x-panel />anonymousComponentPath 메서드의 두 번째 인자로 접두사 "네임스페이스"를 지정할 수도 있습니다.
Blade::anonymousComponentPath(__DIR__.'/../components', 'dashboard');접두사를 지정하면 해당 "네임스페이스" 안의 컴포넌트는 렌더링할 때 컴포넌트 이름 앞에 네임스페이스를 붙여 렌더링할 수 있습니다.
<x-dashboard::panel />레이아웃 만들기
컴포넌트를 이용한 레이아웃
대부분의 웹 애플리케이션은 여러 페이지에 걸쳐 같은 전반적인 레이아웃을 유지합니다. 만드는 모든 뷰마다 레이아웃 HTML 전체를 반복해서 작성해야 한다면 애플리케이션을 관리하기가 무척 번거롭고 어려워질 것입니다. 다행히 이 레이아웃을 하나의 Blade 컴포넌트로 정의해 두고 애플리케이션 전체에서 사용하면 편리합니다.
레이아웃 컴포넌트 정의하기
예를 들어 "할 일(todo)" 목록 애플리케이션을 만든다고 해보겠습니다. 다음과 같은 layout 컴포넌트를 정의할 수 있습니다.
<!-- resources/views/components/layout.blade.php -->
<html>
<head>
<title>{{ $title ?? 'Todo Manager' }}</title>
</head>
<body>
<h1>Todos</h1>
<hr/>
{{ $slot }}
</body>
</html>레이아웃 컴포넌트 적용하기
layout 컴포넌트를 정의했다면, 이 컴포넌트를 사용하는 Blade 뷰를 만들 수 있습니다. 이 예제에서는 작업 목록을 표시하는 간단한 뷰를 정의합니다.
<!-- resources/views/tasks.blade.php -->
<x-layout>
@foreach ($tasks as $task)
<div>{{ $task }}</div>
@endforeach
</x-layout>컴포넌트에 주입한 내용은 layout 컴포넌트의 기본 $slot 변수로 전달된다는 점을 기억하세요. 눈치채셨겠지만 layout은 $title 슬롯이 제공되면 이를 사용하고, 그렇지 않으면 기본 제목을 표시합니다. 컴포넌트 문서에서 설명한 표준 슬롯 문법을 사용해 작업 목록 뷰에서 사용자 지정 제목을 주입할 수 있습니다.
<!-- resources/views/tasks.blade.php -->
<x-layout>
<x-slot:title>
Custom Title
</x-slot>
@foreach ($tasks as $task)
<div>{{ $task }}</div>
@endforeach
</x-layout>이제 레이아웃과 작업 목록 뷰를 정의했으니, 라우트에서 task 뷰를 반환하기만 하면 됩니다.
use App\Models\Task;
Route::get('/tasks', function () {
return view('tasks', ['tasks' => Task::all()]);
});템플릿 상속을 이용한 레이아웃
레이아웃 정의하기
레이아웃은 "템플릿 상속"으로도 만들 수 있습니다. 컴포넌트가 도입되기 전에는 이 방식이 애플리케이션을 만드는 주된 방법이었습니다.
먼저 간단한 예제를 살펴보겠습니다. 우선 페이지 레이아웃을 확인해 봅시다. 대부분의 웹 애플리케이션은 여러 페이지에 걸쳐 같은 전반적인 레이아웃을 유지하므로, 이 레이아웃을 하나의 Blade 뷰로 정의하면 편리합니다.
<!-- resources/views/layouts/app.blade.php -->
<html>
<head>
<title>App Name - @yield('title')</title>
</head>
<body>
@section('sidebar')
This is the master sidebar.
@show
<div class="container">
@yield('content')
</div>
</body>
</html>보시다시피 이 파일에는 일반적인 HTML 마크업이 들어 있습니다. 다만 @section과 @yield 디렉티브에 주목하세요. @section 디렉티브는 이름 그대로 콘텐츠의 한 섹션을 정의하고, @yield 디렉티브는 주어진 섹션의 내용을 표시하는 데 사용합니다.
애플리케이션의 레이아웃을 정의했으니, 이 레이아웃을 상속받는 자식 페이지를 정의해 보겠습니다.
레이아웃 확장하기
자식 뷰를 정의할 때는 @extends Blade 디렉티브로 자식 뷰가 "상속"할 레이아웃을 지정합니다. Blade 레이아웃을 확장하는 뷰는 @section 디렉티브를 사용해 레이아웃의 섹션에 내용을 주입할 수 있습니다. 위 예제에서 본 것처럼 이 섹션들의 내용은 레이아웃에서 @yield로 표시됩니다.
<!-- resources/views/child.blade.php -->
@extends('layouts.app')
@section('title', 'Page Title')
@section('sidebar')
@@parent
<p>This is appended to the master sidebar.</p>
@endsection
@section('content')
<p>This is my body content.</p>
@endsection이 예제에서 sidebar 섹션은 @@parent 디렉티브를 사용해 레이아웃의 사이드바 내용을 덮어쓰지 않고 뒤에 추가합니다. @@parent 디렉티브는 뷰가 렌더링될 때 레이아웃의 내용으로 대체됩니다.
NOTE
앞의 예제와 달리, 이 sidebar 섹션은 @show가 아니라 @endsection으로 끝납니다. @endsection 디렉티브는 섹션을 정의하기만 하지만, @show는 섹션을 정의하고 **즉시 출력(yield)**합니다.
@yield 디렉티브는 두 번째 매개변수로 기본값도 받을 수 있습니다. 이 값은 출력하려는 섹션이 정의되지 않았을 때 렌더링됩니다.
@yield('content', 'Default content')폼
CSRF 필드
애플리케이션에서 HTML 폼을 정의할 때마다, CSRF 보호 미들웨어가 요청을 검증할 수 있도록 폼에 숨겨진 CSRF 토큰 필드를 포함해야 합니다. @csrf Blade 디렉티브로 토큰 필드를 생성할 수 있습니다.
<form method="POST" action="/profile">
@csrf
...
</form>메서드 필드
HTML 폼은 PUT, PATCH, DELETE 요청을 보낼 수 없으므로, 이런 HTTP 메서드를 흉내 내려면(spoofing) 숨겨진 _method 필드를 추가해야 합니다. @method Blade 디렉티브가 이 필드를 만들어 줍니다.
<form action="/foo/bar" method="POST">
@method('PUT')
...
</form>유효성 검증 오류
@error 디렉티브를 사용하면 특정 속성에 대한 유효성 검증 오류 메시지가 있는지 빠르게 확인할 수 있습니다. @error 디렉티브 안에서는 $message 변수를 echo해서 오류 메시지를 표시할 수 있습니다.
<!-- /resources/views/post/create.blade.php -->
<label for="title">Post Title</label>
<input
id="title"
type="text"
class="@error('title') is-invalid @enderror"
/>
@error('title')
<div class="alert alert-danger">{{ $message }}</div>
@enderror@error 디렉티브는 "if" 문으로 컴파일되므로, 속성에 오류가 없을 때 내용을 렌더링하려면 @else 디렉티브를 사용할 수 있습니다.
<!-- /resources/views/auth.blade.php -->
<label for="email">Email address</label>
<input
id="email"
type="email"
class="@error('email') is-invalid @else is-valid @enderror"
/>한 페이지에 폼이 여러 개 있을 때는 @error 디렉티브의 두 번째 매개변수로 특정 에러 백의 이름을 전달해 유효성 검증 오류 메시지를 가져올 수 있습니다.
<!-- /resources/views/auth.blade.php -->
<label for="email">Email address</label>
<input
id="email"
type="email"
class="@error('email', 'login') is-invalid @enderror"
/>
@error('email', 'login')
<div class="alert alert-danger">{{ $message }}</div>
@enderror스택
Blade에서는 이름이 있는 스택에 내용을 푸시(push)해 두었다가, 다른 뷰나 레이아웃의 원하는 위치에서 렌더링할 수 있습니다. 자식 뷰에서 필요한 JavaScript 라이브러리를 지정할 때 특히 유용합니다.
@push('scripts')
<script src="/example.js"></script>
@endpush주어진 불리언 표현식이 true일 때만 내용을 @push하고 싶다면 @pushIf 디렉티브를 사용할 수 있습니다.
@pushIf($shouldPush, 'scripts')
<script src="/example.js"></script>
@endPushIf스택에는 필요한 만큼 여러 번 푸시할 수 있습니다. 스택의 전체 내용을 렌더링하려면 스택 이름을 @stack 디렉티브에 전달합니다.
<head>
<!-- Head Contents -->
@stack('scripts')
</head>@stack 디렉티브는 해당 위치에 도달한 시점까지 푸시된 내용을 렌더링합니다. 그 이후에 푸시된 내용, 예를 들어 같은 레이아웃 컴포넌트에서 @stack 디렉티브보다 아래에 렌더링되는 컴포넌트가 푸시한 내용은 포함되지 않습니다. 이런 컴포넌트에서 푸시해야 한다면, @stack 디렉티브를 그 컴포넌트들 뒤, 예를 들어 <body> 태그의 끝에 배치하세요.
스택의 맨 앞에 내용을 추가하고 싶다면 @prepend 디렉티브를 사용해야 합니다.
@push('scripts')
This will be second...
@endpush
// Later...
@prepend('scripts')
This will be first...
@endprepend@hasstack 디렉티브를 사용하면 스택이 비어 있는지 확인할 수 있습니다.
@hasstack('list')
<ul>
@stack('list')
</ul>
@endif서비스 주입
@inject 디렉티브를 사용하면 Laravel 서비스 컨테이너에서 서비스를 가져올 수 있습니다. @inject에 전달하는 첫 번째 인자는 서비스가 담길 변수의 이름이고, 두 번째 인자는 가져오려는 서비스의 클래스 또는 인터페이스 이름입니다.
@inject('metrics', 'App\Services\MetricsService')
<div>
Monthly Revenue: {{ $metrics->monthlyRevenue() }}.
</div>인라인 Blade 템플릿 렌더링
원시 Blade 템플릿 문자열을 유효한 HTML로 변환해야 할 때가 있습니다. Blade 파사드가 제공하는 render 메서드로 이를 처리할 수 있습니다. render 메서드는 Blade 템플릿 문자열과, 템플릿에 전달할 데이터 배열(선택 사항)을 받습니다.
use Illuminate\Support\Facades\Blade;
return Blade::render('Hello, {{ $name }}', ['name' => 'Julian Bashir']);Laravel은 인라인 Blade 템플릿을 storage/framework/views 디렉토리에 파일로 기록해 렌더링합니다. Blade 템플릿을 렌더링한 뒤 이 임시 파일을 Laravel이 삭제하게 하려면, 메서드에 deleteCachedView 인자를 전달하면 됩니다.
return Blade::render(
'Hello, {{ $name }}',
['name' => 'Julian Bashir'],
deleteCachedView: true
);Blade 프래그먼트 렌더링
Turbo나 htmx 같은 프론트엔드 프레임워크를 사용할 때는 HTTP 응답에 Blade 템플릿의 일부만 반환해야 할 때가 있습니다. Blade "프래그먼트(fragment)"를 사용하면 이를 간단히 처리할 수 있습니다. 먼저 Blade 템플릿의 일부를 @fragment와 @endfragment 디렉티브로 감쌉니다.
@fragment('user-list')
<ul>
@foreach ($users as $user)
<li>{{ $user->name }}</li>
@endforeach
</ul>
@endfragment그런 다음 이 템플릿을 사용하는 뷰를 렌더링할 때 fragment 메서드를 호출해, 지정한 프래그먼트만 응답으로 내보내도록 할 수 있습니다.
return view('dashboard', ['users' => $users])->fragment('user-list');fragmentIf 메서드를 사용하면 주어진 조건에 따라 뷰의 프래그먼트를 조건부로 반환할 수 있습니다. 조건이 맞지 않으면 전체 뷰가 반환됩니다.
return view('dashboard', ['users' => $users])
->fragmentIf($request->hasHeader('HX-Request'), 'user-list');fragments와 fragmentsIf 메서드를 사용하면 응답에 여러 개의 뷰 프래그먼트를 반환할 수 있습니다. 프래그먼트들은 하나로 이어 붙여집니다.
view('dashboard', ['users' => $users])
->fragments(['user-list', 'comment-list']);
view('dashboard', ['users' => $users])
->fragmentsIf(
$request->hasHeader('HX-Request'),
['user-list', 'comment-list']
);Blade 확장하기
Blade에서는 directive 메서드를 사용해 직접 커스텀 디렉티브를 정의할 수 있습니다. Blade 컴파일러가 커스텀 디렉티브를 만나면, 디렉티브에 포함된 표현식을 인자로 넘겨 제공된 콜백을 호출합니다.
다음 예제는 주어진 $var(DateTime 인스턴스여야 합니다)를 포맷하는 @datetime($var) 디렉티브를 만듭니다.
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Register any application services.
*/
public function register(): void
{
// ...
}
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::directive('datetime', function (string $expression) {
return "<?php echo ($expression)->format('m/d/Y H:i'); ?>";
});
}
}보시다시피 디렉티브에 전달된 표현식 뒤에 format 메서드를 체이닝합니다. 따라서 이 예제에서 디렉티브가 최종적으로 생성하는 PHP는 다음과 같습니다.
<?php echo ($var)->format('m/d/Y H:i'); ?>WARNING
Blade 디렉티브의 로직을 수정한 뒤에는 캐시된 Blade 뷰를 모두 삭제해야 합니다. 캐시된 Blade 뷰는 view:clear Artisan 명령어로 삭제할 수 있습니다.
커스텀 Echo 핸들러
Blade에서 객체를 "echo"하려고 하면 해당 객체의 __toString 메서드가 호출됩니다. __toString 메서드는 PHP에 내장된 "매직 메서드" 중 하나입니다. 하지만 서드파티 라이브러리의 클래스처럼 특정 클래스의 __toString 메서드를 직접 제어할 수 없는 경우도 있습니다.
이럴 때는 Blade에서 해당 타입의 객체를 위한 커스텀 echo 핸들러를 등록할 수 있습니다. 이를 위해 Blade의 stringable 메서드를 호출하세요. stringable 메서드는 클로저를 받으며, 이 클로저는 렌더링을 담당할 객체의 타입을 타입 힌트로 지정해야 합니다. 보통 stringable 메서드는 애플리케이션 AppServiceProvider 클래스의 boot 메서드 안에서 호출합니다.
use Illuminate\Support\Facades\Blade;
use Money\Money;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::stringable(function (Money $money) {
return $money->formatTo('en_GB');
});
}커스텀 echo 핸들러를 정의했다면, Blade 템플릿에서 해당 객체를 그냥 echo하면 됩니다.
Cost: {{ $money }}커스텀 If 문
간단한 커스텀 조건문을 정의할 때는 커스텀 디렉티브를 프로그래밍하는 것이 필요 이상으로 복잡할 때가 있습니다. 이 때문에 Blade는 클로저로 커스텀 조건 디렉티브를 빠르게 정의할 수 있는 Blade::if 메서드를 제공합니다. 예를 들어 애플리케이션에 설정된 기본 "디스크"를 확인하는 커스텀 조건문을 정의해 보겠습니다. AppServiceProvider의 boot 메서드에서 정의할 수 있습니다.
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::if('disk', function (string $value) {
return config('filesystems.default') === $value;
});
}커스텀 조건문을 정의했다면 템플릿에서 사용할 수 있습니다.
@disk('local')
<!-- The application is using the local disk... -->
@elsedisk('s3')
<!-- The application is using the s3 disk... -->
@else
<!-- The application is using some other disk... -->
@enddisk
@unlessdisk('local')
<!-- The application is not using the local disk... -->
@enddisk