디렉터리 구조

• 소개
• 루트 디렉터리
  • 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 디렉터리에 들어갑니다. 거의 모든 클래스가 이곳에 위치하며, 아래에서 더 자세히 살펴보겠습니다.

bootstrap 디렉터리

bootstrap 디렉터리에는 프레임워크를 초기화하는 app.php 파일이 있습니다. 또한 라우트 캐시, 서비스 캐시 등 성능 최적화를 위해 프레임워크가 자동으로 생성하는 파일들을 담아 두는 cache 디렉터리도 이 안에 있습니다.

config 디렉터리

이름 그대로 애플리케이션의 모든 설정 파일이 config 디렉터리에 모여 있습니다. 각 파일에 어떤 옵션이 있는지 한 번쯤 훑어보면, 나중에 설정을 변경할 때 큰 도움이 됩니다.

database 디렉터리

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

public 디렉터리

public 디렉터리에는 모든 HTTP 요청의 진입점인 index.php가 있으며, Composer 자동 로딩 설정도 이 파일에서 이루어집니다. 이미지, JavaScript, CSS 같은 정적 에셋도 이 디렉터리에 보관합니다.

resources 디렉터리

resources 디렉터리에는 뷰 파일과 컴파일되지 않은 원본 CSS, JavaScript 에셋이 들어갑니다.

routes 디렉터리

애플리케이션의 모든 라우트 정의는 routes 디렉터리에 있습니다. 기본적으로 web.php와 console.php 두 파일이 제공됩니다.

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

console.php에는 클로저 기반의 Artisan 콘솔 명령어를 정의합니다. 각 클로저는 명령어 인스턴스에 바인딩되어 입출력 메서드를 간편하게 사용할 수 있습니다. HTTP 라우트가 아니라 콘솔 진입점(라우트)을 정의하는 파일이라고 생각하면 됩니다. 스케줄링 작업도 이 파일에서 등록할 수 있습니다.

API 라우트(api.php)와 브로드캐스팅 채널(channels.php) 파일은 필요한 경우 Artisan 명령어로 추가할 수 있습니다.

php artisan install:apiphp artisan install:broadcasting

api.php에는 Stateless 라우트를 정의합니다. 이 라우트로 들어오는 요청은 토큰 기반 인증(Sanctum)을 사용하며 세션 상태에 접근하지 않습니다.

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

storage 디렉터리

storage 디렉터리에는 로그, 컴파일된 Blade 템플릿, 파일 기반 세션, 파일 캐시, 프레임워크가 생성하는 각종 파일이 저장됩니다. 내부는 app, framework, logs 세 디렉터리로 나뉩니다.

• app — 애플리케이션이 생성하는 파일을 저장하는 용도로 자유롭게 사용
• framework — 프레임워크가 생성하는 파일과 캐시 저장
• logs — 애플리케이션 로그 파일 저장

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

php artisan storage:link

tests 디렉터리

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

php artisan test

vendor 디렉터리

vendor 디렉터리에는 Composer로 설치한 의존성 패키지가 들어갑니다. 이 디렉터리는 직접 수정하지 않으며 버전 관리에서 제외(.gitignore)하는 것이 일반적입니다.

App 디렉터리 내부

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

기본적으로 app 디렉터리에는 Http, Models, Providers 디렉터리가 포함되어 있습니다. 그 외 디렉터리들은 Artisan의 make 명령어로 클래스를 생성할 때 필요에 따라 자동으로 만들어집니다. 예를 들어 app/Console 디렉터리는 make:command 명령어를 처음 실행할 때 생성됩니다.

Console과 Http 디렉터리는 애플리케이션 핵심 로직으로 향하는 두 가지 진입 방식을 나타냅니다. HTTP 프로토콜과 CLI는 애플리케이션에 명령을 전달하는 수단일 뿐, 비즈니스 로직 자체를 담지는 않습니다. Console 디렉터리에는 모든 Artisan 명령어가, Http 디렉터리에는 컨트롤러, 미들웨어, Form Request가 들어갑니다.

Broadcasting 디렉터리

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

Console 디렉터리

Console 디렉터리에는 애플리케이션에서 사용하는 커스텀 Artisan 명령어 클래스가 들어갑니다. make:command 명령어로 생성할 수 있습니다.

Events 디렉터리

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

Exceptions 디렉터리

Exceptions 디렉터리에는 애플리케이션의 커스텀 예외 클래스가 들어갑니다. make:exception 명령어로 생성할 수 있습니다.

Http 디렉터리

Http 디렉터리에는 컨트롤러, 미들웨어, Form Request가 들어갑니다. 애플리케이션으로 들어오는 요청을 처리하는 로직의 대부분이 이 디렉터리에 위치합니다.

Jobs 디렉터리

기본적으로 존재하지 않으며, make:job Artisan 명령어를 실행하면 자동으로 생성됩니다. 큐 Job 클래스를 이 디렉터리에 보관합니다. Job은 큐에 등록하여 비동기로 처리하거나, 현재 요청 사이클 내에서 동기적으로 실행할 수 있습니다. 동기적으로 실행하는 Job은 커맨드 패턴의 구현체로서 "커맨드"라고 부르기도 합니다.

Listeners 디렉터리

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

Mail 디렉터리

기본적으로 존재하지 않으며, make:mail Artisan 명령어를 실행하면 자동으로 생성됩니다. 애플리케이션이 발송하는 이메일을 표현하는 클래스를 이 디렉터리에 보관합니다. 메일 객체는 이메일 작성에 필요한 모든 로직을 하나의 간결한 클래스에 캡슐화하며, Mail::send 메서드로 발송합니다.

Models 디렉터리

Models 디렉터리에는 모든 Eloquent 모델 클래스가 들어갑니다. Laravel에 내장된 Eloquent ORM은 ActiveRecord 패턴 기반으로 데이터베이스를 간결하게 다룰 수 있게 해줍니다. 데이터베이스의 각 테이블에는 대응하는 모델이 있으며, 이를 통해 데이터를 조회하거나 새 레코드를 삽입할 수 있습니다.

Notifications 디렉터리

기본적으로 존재하지 않으며, make:notification Artisan 명령어를 실행하면 자동으로 생성됩니다. 애플리케이션이 발송하는 알림 클래스를 이 디렉터리에 보관합니다. Laravel의 알림 기능은 이메일, Slack, SMS, 데이터베이스 저장 등 다양한 드라이버를 통한 알림 발송을 추상화합니다.

Policies 디렉터리

기본적으로 존재하지 않으며, make:policy Artisan 명령어를 실행하면 자동으로 생성됩니다. 인가(Authorization) 정책 클래스를 이 디렉터리에 보관합니다. 정책은 특정 사용자가 특정 리소스에 대해 어떤 작업을 수행할 수 있는지 판단하는 데 사용합니다.

Providers 디렉터리

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

새로운 Laravel 프로젝트에는 기본적으로 AppServiceProvider가 포함되어 있습니다. 필요에 따라 직접 만든 프로바이더를 이 디렉터리에 추가하면 됩니다.

Rules 디렉터리

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