파사드
번역일: 2026년 6월 20일
파사드
소개
Laravel 공식 문서 전반에 걸쳐 "파사드(Facade)"를 통해 Laravel의 기능을 사용하는 예제를 자주 볼 수 있습니다. 파사드는 애플리케이션의 서비스 컨테이너에 등록된 클래스에 "정적(static)" 인터페이스처럼 접근할 수 있게 해주는 편의 레이어입니다. Laravel은 거의 모든 핵심 기능에 접근할 수 있도록 다양한 파사드를 기본 제공합니다.
파사드는 서비스 컨테이너에서 꺼낸 실제 객체로 메서드 호출을 위임하는 "정적 프록시" 역할을 합니다. 덕분에 간결하고 표현력 있는 문법을 사용하면서도 일반 정적 메서드보다 테스트하기 훨씬 쉽고 유연합니다. 지금 당장 내부 동작을 완전히 이해하지 못해도 괜찮습니다. 먼저 흐름을 익히면서 Laravel을 계속 배워가면 됩니다.
모든 Laravel 파사드는 Illuminate\Support\Facades 네임스페이스 아래에 정의되어 있습니다. 다음과 같이 간단하게 사용할 수 있습니다.
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Route;
Route::get('/cache', function () {
return Cache::get('key');
});헬퍼 함수
파사드를 보완하는 수단으로, Laravel은 자주 쓰이는 기능을 더 간편하게 호출할 수 있는 글로벌 "헬퍼 함수"도 다양하게 제공합니다. view, response, url, config 등이 대표적입니다. 각 헬퍼 함수는 해당 기능 문서에서 설명하며, 전체 목록은 헬퍼 문서에서 확인할 수 있습니다.
예를 들어 JSON 응답을 생성할 때 Illuminate\Support\Facades\Response 파사드 대신 response 헬퍼 함수를 사용할 수 있습니다. 헬퍼 함수는 전역으로 사용 가능하므로 별도로 클래스를 import할 필요가 없습니다.
use Illuminate\Support\Facades\Response;
// 파사드 방식
Route::get('/users', function () {
return Response::json([
// ...
]);
});
// 헬퍼 함수 방식 (동일한 동작)
Route::get('/users', function () {
return response()->json([
// ...
]);
});파사드를 언제 사용해야 할까
파사드는 여러 장점이 있습니다. 긴 클래스명을 기억하거나 직접 주입·설정하지 않아도 Laravel의 기능을 간결하고 직관적인 문법으로 사용할 수 있습니다. 또한 PHP의 동적 메서드를 활용하기 때문에 테스트도 편리합니다.
다만 한 가지 주의할 점이 있습니다. 파사드는 너무 편리한 나머지 한 클래스에서 무분별하게 많은 파사드를 사용하게 되는 "책임 범위 비대화(scope creep)" 문제가 생길 수 있습니다. 의존성 주입을 사용할 때는 생성자가 복잡해질수록 클래스가 너무 많은 일을 한다는 것을 시각적으로 확인할 수 있지만, 파사드를 쓸 때는 이런 신호를 놓치기 쉽습니다. 파사드를 사용할 때는 클래스의 크기와 역할 범위에 의식적으로 주의를 기울이세요. 클래스가 지나치게 커진다면 여러 개의 작은 클래스로 분리하는 것을 고려하세요.
파사드 vs. 의존성 주입
의존성 주입의 가장 큰 장점 중 하나는 주입되는 구현체를 손쉽게 교체할 수 있다는 것입니다. 이는 테스트 시 Mock이나 Stub을 주입하고 특정 메서드가 올바르게 호출되었는지 검증할 수 있어 매우 유용합니다.
진짜 정적 메서드는 Mock으로 대체하기가 어렵지만, 파사드는 내부적으로 서비스 컨테이너에서 꺼낸 객체로 메서드 호출을 동적으로 위임하기 때문에, 주입된 클래스 인스턴스를 테스트하는 것과 동일한 방식으로 테스트할 수 있습니다. 예를 들어 다음과 같은 라우트가 있다고 가정해보겠습니다.
use Illuminate\Support\Facades\Cache;
Route::get('/cache', function () {
return Cache::get('key');
});Laravel의 파사드 테스트 메서드를 사용하면 Cache::get이 원하는 인자로 호출되었는지 다음과 같이 검증할 수 있습니다.
Pest
use Illuminate\Support\Facades\Cache;
test('기본 예제', function () {
Cache::shouldReceive('get')
->with('key')
->andReturn('value');
$response = $this->get('/cache');
$response->assertSee('value');
});PHPUnit
use Illuminate\Support\Facades\Cache;
/**
* 기본 기능 테스트 예제
*/
public function test_basic_example(): void
{
Cache::shouldReceive('get')
->with('key')
->andReturn('value');
$response = $this->get('/cache');
$response->assertSee('value');
}파사드 vs. 헬퍼 함수
Laravel에는 뷰 생성, 이벤트 발생, Job 디스패치, HTTP 응답 반환 등 공통적인 작업을 위한 다양한 헬퍼 함수가 있습니다. 이 헬퍼 함수 중 상당수는 대응하는 파사드와 완전히 동일한 동작을 합니다. 예를 들어 아래 두 코드는 완전히 동일합니다.
return Illuminate\Support\Facades\View::make('profile');
return view('profile');파사드와 헬퍼 함수 사이에는 실질적인 차이가 없습니다. 헬퍼 함수를 사용할 때도 대응하는 파사드를 Mock하는 방식으로 동일하게 테스트할 수 있습니다. 예를 들어 다음과 같은 라우트가 있을 때:
Route::get('/cache', function () {
return cache('key');
});cache 헬퍼는 내부적으로 Cache 파사드가 감싸고 있는 클래스의 get 메서드를 호출합니다. 따라서 헬퍼 함수를 사용하더라도 아래와 같이 동일하게 테스트할 수 있습니다.
use Illuminate\Support\Facades\Cache;
/**
* 기본 기능 테스트 예제
*/
public function test_basic_example(): void
{
Cache::shouldReceive('get')
->with('key')
->andReturn('value');
$response = $this->get('/cache');
$response->assertSee('value');
}파사드의 동작 원리
Laravel에서 파사드는 서비스 컨테이너에 등록된 객체에 접근하는 통로 역할을 하는 클래스입니다. 이 모든 동작의 핵심은 Facade 기반 클래스에 있으며, Laravel이 제공하는 파사드와 직접 만드는 커스텀 파사드 모두 Illuminate\Support\Facades\Facade 클래스를 상속합니다.
Facade 기반 클래스는 PHP의 __callStatic() 매직 메서드를 활용하여, 파사드에서 호출된 메서드를 서비스 컨테이너에서 꺼낸 실제 객체에 위임합니다.
아래 코드를 보면 Cache::get이 마치 정적 메서드처럼 보이지만, 실제로는 서비스 컨테이너에서 꺼낸 캐시 인스턴스에 위임되어 실행됩니다.
<?php
namespace App\Http\Controllers;
use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\Cache;
use Illuminate\View\View;
class UserController extends Controller
{
/**
* 지정된 사용자의 프로필을 보여줍니다.
*/
public function showProfile(string $id): View
{
$user = Cache::get('user:'.$id);
return view('profile', ['user' => $user]);
}
}파일 상단에서 Cache 파사드를 import하고 있습니다. 이 파사드는 Illuminate\Contracts\Cache\Factory 인터페이스의 실제 구현체에 접근하기 위한 프록시입니다. 파사드를 통해 호출하는 모든 메서드는 Laravel 캐시 서비스의 실제 인스턴스로 전달됩니다.
실제 Illuminate\Support\Facades\Cache 클래스를 살펴보면 get이라는 정적 메서드가 없다는 걸 확인할 수 있습니다.
class Cache extends Facade
{
/**
* 컴포넌트의 등록된 이름을 반환합니다.
*/
protected static function getFacadeAccessor(): string
{
return 'cache';
}
}Cache 파사드는 기반 Facade 클래스를 상속하고 getFacadeAccessor() 메서드만 정의합니다. 이 메서드는 서비스 컨테이너 바인딩 키를 반환하는 역할을 합니다. 누군가 Cache 파사드의 정적 메서드를 호출하면, Laravel은 서비스 컨테이너에서 cache 바인딩을 꺼내어 해당 객체에 실제 메서드(이 경우 get)를 실행합니다.
실시간 파사드
실시간 파사드(Real-Time Facade)를 사용하면 애플리케이션의 어떤 클래스든 마치 파사드인 것처럼 다룰 수 있습니다. 먼저 실시간 파사드를 사용하지 않는 경우를 살펴보겠습니다.
예를 들어, Podcast 모델에 publish 메서드가 있고, 팟캐스트를 발행하려면 Publisher 인스턴스를 주입해야 한다고 가정해보겠습니다.
<?php
namespace App\Models;
use App\Contracts\Publisher;
use Illuminate\Database\Eloquent\Model;
class Podcast extends Model
{
/**
* 팟캐스트를 발행합니다.
*/
public function publish(Publisher $publisher): void
{
$this->update(['publishing' => now()]);
$publisher->publish($this);
}
}메서드에 Publisher 구현체를 주입하면 Mock을 사용해 독립적으로 테스트하기 쉬워지지만, publish를 호출할 때마다 Publisher 인스턴스를 직접 넘겨야 하는 번거로움이 있습니다.
실시간 파사드를 활용하면 동일한 테스트 가능성을 유지하면서도 Publisher 인스턴스를 명시적으로 전달할 필요가 없습니다. 실시간 파사드를 만들려면 import하는 클래스의 네임스페이스 앞에 Facades를 붙이기만 하면 됩니다.
<?php namespace App\Models; use App\Contracts\Publisher; //use Facades\App\Contracts\Publisher; //use Illuminate\Database\Eloquent\Model; class Podcast extends Model{ /** * 팟캐스트를 발행합니다. */ public function publish(Publisher $publisher): void // public function publish(): void // { $this->update(['publishing' => now()]); $publisher->publish($this); // Publisher::publish($this); // }}실시간 파사드를 사용하면 Facades 접두사 뒤에 오는 인터페이스 또는 클래스명을 기준으로 서비스 컨테이너에서 구현체를 꺼내어 사용합니다. 테스트에서는 Laravel의 내장 파사드 테스트 헬퍼로 이 메서드 호출을 Mock할 수 있습니다.
Pest
<?php
use App\Models\Podcast;
use Facades\App\Contracts\Publisher;
use Illuminate\Foundation\Testing\RefreshDatabase;
uses(RefreshDatabase::class);
test('팟캐스트를 발행할 수 있다', function () {
$podcast = Podcast::factory()->create();
Publisher::shouldReceive('publish')->once()->with($podcast);
$podcast->publish();
});PHPUnit
<?php
namespace Tests\Feature;
use App\Models\Podcast;
use Facades\App\Contracts\Publisher;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class PodcastTest extends TestCase
{
use RefreshDatabase;
/**
* 테스트 예제
*/
public function test_podcast_can_be_published(): void
{
$podcast = Podcast::factory()->create();
Publisher::shouldReceive('publish')->once()->with($podcast);
$podcast->publish();
}
}파사드 클래스 레퍼런스
아래 표에서 모든 파사드와 그에 대응하는 실제 클래스를 확인할 수 있습니다. 특정 파사드의 API 문서를 빠르게 찾아볼 때 유용하게 활용하세요. 해당하는 경우 서비스 컨테이너 바인딩 키도 함께 표기했습니다.