디렉터리 구조

• 소개
• 루트 디렉터리
  • 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 파일이 있으며, 오토로딩 설정도 이 파일에서 이루어집니다. 이미지, JavaScript, CSS 등 정적 에셋 파일들도 이 디렉터리에 위치합니다.

resources 디렉터리

resources 디렉터리에는 뷰 파일과 컴파일 전의 원본 CSS, JavaScript 등의 에셋이 포함됩니다.

routes 디렉터리

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

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

console.php에는 클로저 기반의 Artisan 커맨드를 정의합니다. 각 클로저는 커맨드 인스턴스에 바인딩되어 입출력 메서드를 간편하게 사용할 수 있습니다. HTTP 라우트를 정의하는 파일은 아니지만, CLI를 통해 애플리케이션에 접근하는 진입점(라우트)을 정의한다고 볼 수 있습니다. 작업 스케줄링도 이 파일에서 설정합니다.

API 라우트(api.php)와 브로드캐스팅 채널(channels.php)이 필요하다면, Artisan 커맨드 install:api와 install:broadcasting를 실행해 추가할 수 있습니다.

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

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 커맨드로 실행하거나, 더 보기 좋은 결과 화면을 원한다면 php artisan test 커맨드를 사용하세요.

vendor 디렉터리

vendor 디렉터리에는 Composer로 설치한 패키지 의존성이 들어 있습니다.

App 디렉터리

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

기본 설치 시에는 Http, Models, Providers 디렉터리만 존재합니다. 그 외의 디렉터리들은 Artisan의 make 커맨드로 클래스를 생성할 때 자동으로 만들어집니다. 예를 들어, app/Console 디렉터리는 make:command 커맨드를 처음 실행해야 생성됩니다.

Console과 Http 디렉터리는 각각 CLI와 HTTP라는 두 가지 방식으로 애플리케이션 핵심에 접근하는 인터페이스 역할을 합니다. 이 두 디렉터리는 애플리케이션에 명령을 전달하는 통로일 뿐, 비즈니스 로직 자체를 담지는 않습니다. Console 디렉터리에는 모든 Artisan 커맨드가, Http 디렉터리에는 컨트롤러, 미들웨어, 폼 리퀘스트가 위치합니다.

Broadcasting 디렉터리

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

Console 디렉터리

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

Events 디렉터리

기본적으로 존재하지 않으며, event:generate 또는 make:event Artisan 커맨드를 실행하면 자동으로 생성됩니다. Events 디렉터리에는 이벤트 클래스가 위치합니다. 이벤트는 애플리케이션의 다른 부분에 특정 동작이 발생했음을 알리는 수단으로, 코드 간의 결합도를 낮추는 데 유용합니다.

Exceptions 디렉터리

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

Http 디렉터리

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

Jobs 디렉터리

기본적으로 존재하지 않으며, make:job Artisan 커맨드를 실행하면 자동으로 생성됩니다. Jobs 디렉터리에는 애플리케이션의 큐 작업 클래스가 들어 있습니다. Job은 큐에 넣어 비동기로 처리하거나, 현재 요청 사이클 내에서 동기적으로 실행할 수 있습니다. 동기적으로 실행되는 Job은 커맨드 패턴의 구현이므로 "커맨드"라고 부르기도 합니다.

Listeners 디렉터리

기본적으로 존재하지 않으며, event:generate 또는 make:listener Artisan 커맨드를 실행하면 자동으로 생성됩니다. Listeners 디렉터리에는 이벤트를 처리하는 리스너 클래스들이 위치합니다. 리스너는 발생한 이벤트 인스턴스를 받아 필요한 로직을 실행합니다. 예를 들어, UserRegistered 이벤트가 발생하면 SendWelcomeEmail 리스너가 이를 처리해 환영 이메일을 발송하는 방식입니다.

Mail 디렉터리

기본적으로 존재하지 않으며, make:mail Artisan 커맨드를 실행하면 자동으로 생성됩니다. Mail 디렉터리에는 애플리케이션에서 발송하는 이메일을 나타내는 클래스들이 들어 있습니다. 메일 객체를 사용하면 이메일 생성에 필요한 모든 로직을 하나의 클래스로 캡슐화할 수 있으며, Mail::send 메서드로 간단히 발송할 수 있습니다.

Models 디렉터리

Models 디렉터리에는 모든 Eloquent 모델 클래스가 위치합니다. Laravel에 내장된 Eloquent ORM은 ActiveRecord 패턴 기반의 직관적인 데이터베이스 인터페이스를 제공합니다. 데이터베이스의 각 테이블에 대응하는 모델 클래스가 있으며, 이를 통해 데이터를 조회하거나 새 레코드를 저장할 수 있습니다.

Notifications 디렉터리

기본적으로 존재하지 않으며, make:notification Artisan 커맨드를 실행하면 자동으로 생성됩니다. Notifications 디렉터리에는 애플리케이션에서 발송하는 알림 클래스들이 들어 있습니다. 이메일, Slack, SMS, 데이터베이스 저장 등 다양한 채널을 통한 알림 발송을 추상화하여 일관된 방식으로 처리할 수 있습니다.

Policies 디렉터리

기본적으로 존재하지 않으며, make:policy Artisan 커맨드를 실행하면 자동으로 생성됩니다. Policies 디렉터리에는 인가 정책 클래스들이 들어 있습니다. 정책(Policy)은 특정 사용자가 특정 리소스에 대해 주어진 작업을 수행할 권한이 있는지를 판단하는 로직을 담습니다.

Providers 디렉터리

Providers 디렉터리에는 애플리케이션의 모든 서비스 프로바이더가 들어 있습니다. 서비스 프로바이더는 서비스 컨테이너에 서비스를 바인딩하고, 이벤트를 등록하고, 요청을 처리할 준비를 갖추는 등 애플리케이션 부트스트랩에 필요한 작업들을 수행합니다.

새로 생성된 Laravel 프로젝트에는 AppServiceProvider가 기본으로 포함되어 있습니다. 필요에 따라 이 디렉터리에 프로바이더를 추가할 수 있습니다.

Rules 디렉터리

기본적으로 존재하지 않으며, make:rule Artisan 커맨드를 실행하면 자동으로 생성됩니다. Rules 디렉터리에는 커스텀 유효성 검사 규칙 객체들이 들어 있습니다. 복잡한 유효성 검사 로직을 단순한 객체 하나로 캡슐화할 수 있습니다. 자세한 내용은 유효성 검사 문서를 참고하세요.