Laravel 프로젝트 폴더 구조 및 디렉터리 역할 정리

오늘의 포스트는 직접 따라 할 건 없고, 라라벨을 처음 접하는 사람들을 대상으로 Laravel 프로젝트의 폴더 구조를 설명하려고 한다.

Laravel 프로젝트를 처음 생성하고 VSCode로 열어보면, 생각보다 너무 많은 폴더와 파일들에 초보자들에게는 벌써부터 어렵게 느껴질 수 있다.

그래서 오늘 포스트에서는 라라벨 초보자분들을 위해 각 폴더가 어떤 역할을 하는지, 그리고 실제 개발할 때 어떤 곳을 주로 만지게 되는지 핵심만 골라 정리해 보겠다.

이전 포스트

라라벨 성능 최적화를 위한 Laravel Debugbar 설치 및 다크모드 설정하기

라라벨 웹 앱 개발의 필수 패키지인 Laravel Debugbar 설치 가이드입니다. 특정 페이지 비활성화, 테마 변경 팁, 실제 운영 서버 배포 시 서비스가 느려지지 않도록 --dev 옵션과 APP_DEBUG=false를 활용하는 안전 장치 설정까지 정리했습니다.

VSCode를 캡처한 이미지다.

왼쪽에 보이는 것처럼 라라벨 프로젝트에는 이렇게 많은 폴더들이 있다.

각 폴더들의 역할에 대해서 설명하자면 다음과 같다.

app: 애플리케이션의 메인이 되는 곳

MVC 패턴의 핵심인 Model과 Controller가 이곳에 집중되어 있다.

그래서 개발을 할 때 이 안의 파일들을 수정하게 되는 일이 많다.

거의 라라벨 개발 시간의 70~80%를 이 폴더 안에서 보낸다.

app/Models 디렉토리 안에 MVC의 M, DB에 접속하는 모델 파일들이 들어있고,

app/Http/Controllers 디렉토리 안에 MVC의 C, 컨트롤러 파일들이 들어있다.

bootstrap: 초기 부팅 처리가 이루어지는 곳

라라벨 프레임워크가 켜질 때 필요한 뼈대 작업과 성능 향상을 위한 캐시^Cache 파일들이 들어간다.

예전에는 개발자가 직접 여기의 파일을 수정할 일은 없었다.

사이트 속도를 올리거나 설정을 초기화할 때 터미널 명령어를 통해 이 안의 캐시 파일들을 간접적으로 제어할 뿐이었다.

그런데 최신 라라벨(11 이상부터)에는 기존의 미들웨어 설정의 일부가 bootstrap/app.php 파일로 통합되었다.

그래서 최신 버전을 쓸 때는 이 파일을 아주 가끔 만질 일이 생길 수 있다.

(예전에는 app/Http/Middleware 폴더에서 수정했는데, 지금은 app/Http 안에 Middleware 폴더가 없다.)

config: 애플리케이션의 설정을 하는 곳

데이터베이스 연결 정보, 메일 서버 설정, 그리고 상단에 링크해 둔 이전 포스트에서 다룬 디버그바 같은 패키지 설정들이 모여 있다.

새로운 라이브러리를 설치하거나 세부 설정을 바꿀 때 가끔 들어와서 확인하고 수정하는 폴더다.

이 폴더 안의 파일들을 수정할 때는 .env 파일의 값을 가져와 쓰도록 되어있는 경우가 많다.

라라벨(Laravel) 초기 세팅: 타임존 설정 및 한글화

라라벨 애플리케이션의 타임존을 'Asia/Seoul'로 변경하고 전체 웹사이트를 한글화하는 상세 가이드입니다. laravel-lang/lang 패키지를 활용해 한국어로 자동 번역하는 명령어 단계를 정리했습니다. chown 명령어로 소유자를 변경하는 것도 잊지 마세요.

이전에 타임존 설정도 config/app.php 파일에서 했었다.

database: 데이터베이스와 관련된 파일들이 들어있는 곳

테이블 구조를 짜는 마이그레이션^Migration, 가짜 데이터를 넣는 시딩^Seeding과 팩토리^Factory가 있다.

개발 중에 매우 자주 만진다고 할 수는 없지만, 데이터베이스 테이블을 새로 만들거나 컬럼을 추가할 때마다 마이그레이션 파일을 새로 생성하고 수정해야 한다.

lang: 다국어 및 메시지 처리를 하는 곳

처음에는 기본으로 포함되지 않는 폴더인데, 위에 링크해 둔 "라라벨(Laravel) 초기 세팅: 타임존 설정 및 한글화" 때 생성된 폴더다.

한국어 지원 사이트를 만들 때, 에러 메시지를 한국어로 번역하여 저장해두기 위해 프로젝트 초반이나 다국어 지원 작업 시 수정하게 되는 곳이다.

node_modules: 프론트엔드 라이브러리 저장소

백엔드에 vendor 폴더가 있다면, 프론트엔드(JavaScript/CSS)에는 node_modules 폴더가 있다.

npm install 명령어를 실행하면 Tailwind CSS, Vite, Alpine.js, Vue, React 등 화면을 꾸미고 동적 기능을 넣기 위한 자바스크립트 패키지들이 다운로드되는 곳이다.

우리가 절대 직접 만질 일이 없는 곳이다.

public: 웹 서버가 바라보는 공개 디렉토리

보안을 위해 외부 인터넷 상에서는 오직 이 public 폴더만 노출된다.

모든 요청의 시작점인 index.php가 여기 있다.

과거에는 CSS나 이미지 파일을 여기에 다 넣었지만, 모던 라라벨(Vite 빌드 도구 사용)에서는 원본 파일을 resources에 넣고 자동으로 빌드되게 한다.

그래서 지금은 웹사이트 로고 이미지, 파비콘(favicon.ico), 업로드된 파일(storage 링크), robots.txt 등을 넣을 때만 직접 수정한다.

resources: 화면을 만드는 원본 소스들이 모인 곳

MVC의 View인 블레이드(blade.php) 파일이 있으며, 첫 화면인 welcome.blade.php가 있는 곳이다.

HTML 뼈대를 잡고 화면을 그리는 작업을 해야 하므로 app 폴더만큼이나 매일 드나들며 수정하는 곳이다.

블레이드 파일뿐만 아니라 컴파일되기 전의 순수 CSS(또는 Sass) 파일과 JavaScript 원본 파일도 resources/css, resources/js 안에서 작성하고 관리한다.

routes: 애플리케이션의 URL(경로) 주도를 담당하는 곳

URL 주소와 컨트롤러를 매핑해주는 이정표 역할을 한다.

새로운 페이지(기능)를 만들 때마다 "이 주소로 들어오면 이 컨트롤러로 가라"고 주소를 뚫어주어야 한다.

그런 작업을 할 때마다 수정해야 하는 필수 폴더다.

storage: 시스템이 살아 숨 쉬며 만드는 파일 저장소

라라벨이 구동되면서 생기는 로그, 캐시, 세션 데이터가 들어간다.

이전에 다루었던 디버그바의 임시 로그 파일도 여기에 쌓인다.

시스템이 자동으로 파일을 쓰고 지우는 곳이므로 코드를 직접 수정할 일은 없다.

다만, 사이트에 에러가 날 때 storage/logs/laravel.log 파일을 열어서 원인을 분석할 때 자주 읽게 되는 곳이다.

또, 사용자가 업로드한 프로필 이미지 등을 storage/app/public 안에 코드로 저장하곤 한다.

tests: 코드의 무결성을 검증하는 테스트 실험실

작성한 기능들이 버그 없이 잘 돌아가는지 컴퓨터가 자동으로 테스트하게 만드는 코드가 들어간다.

자동화 테스트(TDD)를 도입한 프로젝트라면 코드를 짤 때마다 테스트 코드를 작성하므로 자주 만지게 된다.

하지만 작은 개인 프로젝트나 기초 공부 단계에서는 아예 만질 일이 없을 수도 있다.

vendor: 컴포저가 지배하는 외부 라이브러리 성역

이전 포스트에서 다룬 디버그바 패키지를 포함하여 라라벨 핵심 소스코드가 들어있는 곳으로, 절대로 직접 수정해서는 안 되는 곳이다.

composer.json을 통해 관리되는 영역이므로, 수정하고 싶은 설정이 있다면 앞서 공부한 vendor:publish 명령어로 밖으로 꺼내서 수정해야 한다.

지금까지 라라벨 프로젝트의 복잡한 폴더 구조를 함께 살펴보았다.

처음에 이 많은 디렉토리를 다 외우려고 머리 싸맬 필요는 전혀 없다.

결국 우리가 가장 자주 드나들며 코딩하게 될 곳은 app, resources, routes 세 가지 폴더다.

개발을 하면서 자연스럽게 체득하게 될 테니, 가벼운 마음으로 다음 포스트와 함께 라라벨 개발을 시작해 보자.

다음 포스트

php artisan make:model -mrc 옵션 (Laravel 모델, 마이그레이션, 컨트롤러 역할 정리)

라라벨 입문자를 위해 모델, 마이그레이션, 리소스 컨트롤러를 명령어 한 줄로 동시에 생성하는 php artisan make:model -mrc 옵션의 사용법을 안내합니다. 개별 파일들의 개념과 데이터베이스 연동 과정에서의 핵심 역할을 알기 쉽게 정리했습니다.