디렉터리 구조

• 소개
• 루트 디렉터리
  • 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 REST API를 제공하지 않는 일반적인 웹 애플리케이션이라면, 대부분의 라우트를 이 파일에 정의하게 됩니다.

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

API 라우트용 api.php와 브로드캐스팅 채널용 channels.php는 기본 포함 파일이 아니며, install:api 및 install:broadcasting Artisan 커맨드로 각각 추가 설치할 수 있습니다.

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 커맨드로 실행하거나, 보다 보기 좋은 결과를 원한다면 아래 Artisan 커맨드를 사용하세요.

php artisan test

vendor 디렉터리

vendor 디렉터리에는 Composer로 설치된 의존성 패키지들이 위치합니다.

App 디렉터리

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

기본적으로 app 디렉터리에는 Http, Models, Providers 세 개의 하위 디렉터리가 포함되어 있습니다. 그 외의 디렉터리들(예: Console, Events, Jobs 등)은 관련 Artisan make 커맨드를 실행할 때 자동으로 생성됩니다. 예를 들어, make:command 커맨드를 처음 실행하기 전까지는 app/Console 디렉터리가 존재하지 않습니다.

Console과 Http 디렉터리는 애플리케이션 핵심 로직으로 향하는 두 가지 진입 경로라고 생각하면 이해하기 쉽습니다. HTTP 프로토콜과 CLI는 모두 애플리케이션에 명령을 전달하는 수단일 뿐, 애플리케이션의 실제 비즈니스 로직은 담고 있지 않습니다. 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은 큐에 넣어 비동기로 처리하거나, 현재 요청 사이클 안에서 동기적으로 실행할 수 있습니다. 동기 실행 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 디렉터리에는 애플리케이션에서 발송하는 알림 클래스가 위치합니다. Laravel의 알림 기능은 이메일, Slack, SMS, 데이터베이스 저장 등 다양한 드라이버를 추상화하여 일관된 방식으로 알림을 보낼 수 있게 해줍니다.

Policies 디렉터리

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

Providers 디렉터리

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

새로 생성된 Laravel 애플리케이션에는 이미 AppServiceProvider가 포함되어 있습니다. 필요에 따라 이 디렉터리에 커스텀 서비스 프로바이더를 자유롭게 추가할 수 있습니다.

Rules 디렉터리

기본적으로는 존재하지 않으며, make:rule Artisan 커맨드를 실행할 때 생성됩니다. Rules 디렉터리에는 애플리케이션의 커스텀 유효성 검사 룰 오브젝트가 위치합니다. 복잡한 유효성 검사 로직을 단순한 오브젝트 하나로 캡슐화할 때 유용합니다. 자세한 내용은 유효성 검사 문서를 참고하세요.