디렉터리 구조

• 소개
• 루트 디렉터리
  • app 디렉터리
  • bootstrap 디렉터리
  • config 디렉터리
  • database 디렉터리
  • public 디렉터리
  • resources 디렉터리
  • routes 디렉터리
  • storage 디렉터리
  • tests 디렉터리
  • vendor 디렉터리
• App 디렉터리
  • Broadcasting 디렉터리
  • Console 디렉터리
  • Events 디렉터리
  • Exceptions 디렉터리
  • Http 디렉터리
  • Jobs 디렉터리
  • Listeners 디렉터리
  • Mail 디렉터리
  • Models 디렉터리
  • Notifications 디렉터리
  • Policies 디렉터리
  • Providers 디렉터리
  • Rules 디렉터리

소개

Laravel의 기본 디렉터리 구조는 소규모 프로젝트부터 대규모 애플리케이션까지 모두 잘 어울리도록 설계되어 있습니다. 다만 구조는 자유롭게 변경할 수 있습니다. Composer가 클래스를 오토로드할 수 있는 한, Laravel은 클래스 파일의 위치에 거의 제약을 두지 않습니다.

루트 디렉터리

app 디렉터리

app 디렉터리에는 애플리케이션의 핵심 코드가 들어갑니다. 애플리케이션을 구성하는 거의 모든 클래스가 이 디렉터리 안에 위치합니다. 자세한 내용은 아래 App 디렉터리 절에서 설명합니다.

bootstrap 디렉터리

bootstrap 디렉터리에는 프레임워크를 초기화하는 app.php 파일이 있습니다. 또한 라우트 캐시나 서비스 캐시처럼 성능 최적화를 위해 프레임워크가 자동 생성하는 파일들을 보관하는 cache 하위 디렉터리도 포함되어 있습니다. 일반적으로 이 디렉터리의 파일을 직접 수정할 일은 없습니다.

config 디렉터리

config 디렉터리에는 애플리케이션의 모든 설정 파일이 들어 있습니다. 각 파일을 한 번쯤 훑어보며 어떤 옵션이 있는지 파악해 두면 개발할 때 많은 도움이 됩니다.

database 디렉터리

database 디렉터리에는 데이터베이스 마이그레이션, 모델 팩토리, 시더(seeder)가 위치합니다. 필요하다면 SQLite 데이터베이스 파일을 이 디렉터리에 저장해도 됩니다.

public 디렉터리

public 디렉터리에는 모든 HTTP 요청의 진입점인 index.php 파일이 있으며, 오토로딩 설정도 여기서 이루어집니다. 이미지, JavaScript, CSS 같은 정적 에셋 파일도 이 디렉터리에 두는 것이 일반적입니다.

resources 디렉터리

resources 디렉터리에는 뷰 파일과 컴파일 전의 원본 CSS, JavaScript 파일이 들어갑니다.

routes 디렉터리

routes 디렉터리에는 애플리케이션의 모든 라우트 정의가 담겨 있습니다. 기본적으로 web.php, api.php, console.php, channels.php 네 개의 라우트 파일이 제공됩니다.

web.php에는 RouteServiceProvider가 web 미들웨어 그룹에 등록하는 라우트가 정의됩니다. 이 그룹은 세션 상태 관리, CSRF 보호, 쿠키 암호화를 제공합니다. 별도의 Stateless RESTful API를 제공하지 않는 일반적인 웹 애플리케이션이라면 대부분의 라우트를 이 파일에 정의하게 됩니다.

api.php에는 RouteServiceProvider가 api 미들웨어 그룹에 등록하는 라우트가 정의됩니다. 이 라우트들은 Stateless하게 동작하도록 설계되어 있으며, 토큰 기반 인증을 사용하고 세션 상태에는 접근하지 않습니다.

console.php에는 클로저 기반의 Artisan 콘솔 명령을 정의합니다. 각 클로저는 명령 인스턴스에 바인딩되어 입출력 메서드를 간편하게 사용할 수 있습니다. HTTP 라우트를 정의하는 파일은 아니지만, 애플리케이션으로 들어오는 콘솔 기반 진입점(라우트)을 정의한다고 볼 수 있습니다.

channels.php에는 애플리케이션이 지원하는 이벤트 브로드캐스팅 채널을 등록합니다.

storage 디렉터리

storage 디렉터리에는 로그, 컴파일된 Blade 템플릿, 파일 기반 세션, 파일 캐시, 그리고 프레임워크가 생성하는 기타 파일들이 저장됩니다. 내부적으로 app, framework, logs 세 개의 하위 디렉터리로 구분됩니다.

• app — 애플리케이션이 직접 생성하는 파일을 저장합니다.
• framework — 프레임워크가 생성하는 파일과 캐시를 저장합니다.
• logs — 애플리케이션 로그 파일이 저장됩니다.

storage/app/public 디렉터리는 프로필 사진처럼 외부에서 접근 가능해야 하는 사용자 생성 파일을 저장하는 데 사용합니다. 이 디렉터리를 외부에서 접근할 수 있도록 public/storage 심볼릭 링크를 생성해야 하며, 아래 Artisan 명령으로 간편하게 만들 수 있습니다.

php artisan storage:link

storage 디렉터리의 위치는 LARAVEL_STORAGE_PATH 환경 변수로 변경할 수 있습니다.

tests 디렉터리

tests 디렉터리에는 자동화 테스트 코드가 들어갑니다. PHPUnit 기반의 유닛 테스트와 기능 테스트 예시가 기본으로 제공됩니다. 테스트 클래스의 이름은 반드시 Test로 끝나야 합니다. 테스트는 phpunit 또는 php vendor/bin/phpunit 명령으로 실행할 수 있으며, 더 보기 좋은 결과 화면을 원한다면 php artisan test 명령을 사용하세요.

vendor 디렉터리

vendor 디렉터리에는 Composer로 설치한 의존 패키지들이 위치합니다. 직접 수정하지 않는 것이 원칙입니다.

App 디렉터리

애플리케이션 코드의 대부분은 app 디렉터리에 위치합니다. 이 디렉터리는 기본적으로 App 네임스페이스를 사용하며, Composer가 PSR-4 오토로딩 표준에 따라 자동으로 로드합니다.

app 디렉터리에는 Console, Http, Providers 등 다양한 하위 디렉터리가 있습니다. Console과 Http는 애플리케이션 핵심 로직에 접근하는 두 가지 통로라고 생각하면 됩니다. HTTP 프로토콜과 CLI는 애플리케이션과 상호작용하는 수단일 뿐, 비즈니스 로직 자체를 담지는 않습니다. Console 디렉터리에는 모든 Artisan 명령이, Http 디렉터리에는 컨트롤러, 미들웨어, 폼 리퀘스트가 위치합니다.

Jobs, Events, Listeners 같은 디렉터리들은 기본적으로 존재하지 않으며, 관련 Artisan make 명령을 실행할 때 자동으로 생성됩니다.

Broadcasting 디렉터리

Broadcasting 디렉터리에는 애플리케이션의 브로드캐스트 채널 클래스가 위치합니다. make:channel 명령으로 생성하며, 기본적으로 존재하지 않고 첫 번째 채널을 만들 때 자동으로 생성됩니다. 채널에 대한 자세한 내용은 이벤트 브로드캐스팅 문서를 참고하세요.

Console 디렉터리

Console 디렉터리에는 애플리케이션의 커스텀 Artisan 명령이 위치합니다. make:command 명령으로 새 명령을 생성할 수 있습니다. 또한 커스텀 Artisan 명령을 등록하고 스케줄 작업을 정의하는 콘솔 커널도 이 디렉터리에 있습니다.

Events 디렉터리

Events 디렉터리는 기본적으로 존재하지 않으며, event:generate 또는 make:event Artisan 명령을 실행할 때 자동으로 생성됩니다. 이 디렉터리에는 이벤트 클래스가 위치합니다. 이벤트는 애플리케이션의 특정 동작이 발생했음을 다른 구성 요소에 알리는 데 사용되며, 코드 간 결합도를 낮추는 데 효과적입니다.

Exceptions 디렉터리

Exceptions 디렉터리에는 애플리케이션의 예외 핸들러가 위치하며, 커스텀 예외 클래스를 두기에도 좋은 장소입니다. 예외를 로깅하거나 렌더링하는 방식을 바꾸고 싶다면 이 디렉터리의 Handler 클래스를 수정하면 됩니다.

Http 디렉터리

Http 디렉터리에는 컨트롤러, 미들웨어, 폼 리퀘스트가 위치합니다. 들어오는 HTTP 요청을 처리하는 로직의 대부분은 이 디렉터리 안에 작성하게 됩니다.

Jobs 디렉터리

Jobs 디렉터리는 기본적으로 존재하지 않으며, make:job Artisan 명령을 실행할 때 자동으로 생성됩니다. 이 디렉터리에는 애플리케이션의 큐 Job이 위치합니다. Job은 큐에 올려 비동기로 처리하거나, 현재 요청 라이프사이클 내에서 동기적으로 실행할 수 있습니다. 동기적으로 실행되는 Job은 커맨드 패턴의 구현체이므로 "커맨드"라고 부르기도 합니다.

Listeners 디렉터리

Listeners 디렉터리는 기본적으로 존재하지 않으며, event:generate 또는 make:listener Artisan 명령을 실행할 때 자동으로 생성됩니다. 이 디렉터리에는 이벤트를 처리하는 리스너 클래스가 위치합니다. 리스너는 이벤트 인스턴스를 받아 해당 이벤트에 반응하는 로직을 수행합니다. 예를 들어 UserRegistered 이벤트는 SendWelcomeEmail 리스너가 처리할 수 있습니다.

Mail 디렉터리

Mail 디렉터리는 기본적으로 존재하지 않으며, make:mail Artisan 명령을 실행할 때 자동으로 생성됩니다. 이 디렉터리에는 애플리케이션이 발송하는 이메일 클래스가 위치합니다. 메일 객체를 사용하면 이메일 생성 로직을 하나의 간결한 클래스로 캡슐화할 수 있으며, Mail::send 메서드로 발송합니다.

Models 디렉터리

Models 디렉터리에는 모든 Eloquent 모델 클래스가 위치합니다. Laravel에 내장된 Eloquent ORM은 ActiveRecord 패턴을 기반으로 데이터베이스와 간편하게 상호작용할 수 있는 방법을 제공합니다. 데이터베이스의 각 테이블에는 대응하는 모델이 있으며, 이를 통해 데이터를 조회하거나 새 레코드를 삽입할 수 있습니다.

Notifications 디렉터리

Notifications 디렉터리는 기본적으로 존재하지 않으며, make:notification Artisan 명령을 실행할 때 자동으로 생성됩니다. 이 디렉터리에는 이메일, Slack, SMS, 데이터베이스 저장 등 다양한 채널로 발송하는 애플리케이션의 알림 클래스가 위치합니다. Laravel의 알림 기능은 여러 드라이버를 추상화하여 일관된 방식으로 알림을 처리할 수 있게 해줍니다.

Policies 디렉터리

Policies 디렉터리는 기본적으로 존재하지 않으며, make:policy Artisan 명령을 실행할 때 자동으로 생성됩니다. 이 디렉터리에는 애플리케이션의 인가 정책 클래스가 위치합니다. 정책(Policy)은 특정 사용자가 특정 리소스에 대해 어떤 작업을 수행할 수 있는지를 결정하는 데 사용됩니다.

Providers 디렉터리

Providers 디렉터리에는 애플리케이션의 모든 서비스 프로바이더가 위치합니다. 서비스 프로바이더는 서비스 컨테이너에 서비스를 바인딩하고, 이벤트를 등록하거나, 요청 처리 전 필요한 초기화 작업을 수행하며 애플리케이션을 부트스트랩합니다.

새로 생성한 Laravel 프로젝트에는 이미 몇 가지 기본 프로바이더가 포함되어 있으며, 필요에 따라 이 디렉터리에 직접 프로바이더를 추가할 수 있습니다.

Rules 디렉터리

Rules 디렉터리는 기본적으로 존재하지 않으며, make:rule Artisan 명령을 실행할 때 자동으로 생성됩니다. 이 디렉터리에는 커스텀 유효성 검사 규칙 객체가 위치합니다. 복잡한 유효성 검사 로직을 하나의 간결한 객체로 캡슐화하는 데 사용합니다. 자세한 내용은 유효성 검사 문서를 참고하세요.