Installation
- Meet Laravel
- Creating a Laravel Application
- Initial Configuration
- Installation Using Herd
- IDE Support
- Laravel and AI
- Next Steps
Meet Laravel
Laravel은 표현력이 뛰어나고 우아한 문법을 제공하는 웹 애플리케이션 프레임워크입니다. 웹 프레임워크란, 애플리케이션을 만들 때 구조와 출발점을 제공하여, 여러분이 세세한 부분까지 신경 쓰지 않고도 멋진 것을 만드는 데 집중할 수 있게 도와주는 도구입니다.
Laravel은 강력한 기능과 함께 뛰어난 개발자 경험을 제공하기 위해 노력합니다. 예를 들어 철저한 의존성 주입, 표현력 높은 데이터베이스 추상화 레이어, 큐와 예약 작업, 단위 및 통합 테스트 등 다양한 기능을 제공합니다.
PHP 웹 프레임워크가 처음인 분이든, 다년간의 경험을 가진 개발자이든, Laravel은 여러분과 함께 성장할 수 있는 프레임워크입니다. 웹 개발자로서 첫 걸음을 내딛도록 돕거나, 여러분의 역량을 한 단계 더 성장시킬 수 있도록 지원합니다. 여러분이 Laravel로 어떤 것을 만들어낼지 기대됩니다.
Why Laravel?
웹 애플리케이션을 개발할 때 선택할 수 있는 도구와 프레임워크는 다양합니다. 하지만 저희는 Laravel이 현대적이고, 풀스택 웹 애플리케이션을 구축하기에 가장 적합한 선택이라고 믿습니다.
A Progressive Framework
Laravel은 "점진적(progressive)" 프레임워크로 불리기도 합니다. 이는 Laravel이 여러분과 함께 성장할 수 있다는 뜻입니다. 웹 개발에 첫발을 들이는 단계라면, Laravel의 방대한 공식 문서, 가이드, video tutorials 덕분에 부담 없이 기본기를 익힐 수 있습니다.
경험이 풍부한 시니어 개발자라면, Laravel은 dependency injection, unit testing, queues, real-time events 등 전문가용 도구를 제공합니다. Laravel은 전문적인 웹 애플리케이션 구축에 최적화되어 있으며, 엔터프라이즈 규모의 트래픽도 거뜬히 처리할 준비가 되어 있습니다.
A Scalable Framework
Laravel은 매우 뛰어난 확장성을 자랑합니다. PHP의 확장 친화적인 특성과, Redis와 같은 빠르고 분산된 캐시 시스템을 Laravel에서 기본적으로 지원하기 때문에, Laravel로 수평 확장이 매우 쉽게 가능합니다. 실제로, Laravel 애플리케이션은 월 수억 건의 요청을 처리하도록 쉽게 확장된 사례가 있습니다.
더 극단적인 확장이 필요하다면, Laravel Cloud 같은 플랫폼을 이용해 거의 무제한에 가까운 규모로 Laravel 애플리케이션을 운영할 수 있습니다.
An Agent Ready Framework
Laravel은 명확한 규칙과 잘 정의된 구조를 갖추고 있어, Cursor나 Claude Code와 같은 도구를 활용한 AI assisted development에 최적화되어 있습니다. 예를 들어, AI 에이전트에게 컨트롤러를 추가하라고 명령하면, 어디에 추가해야 하는지 정확히 알 수 있습니다. 마이그레이션 파일 역시 이름 규칙과 디렉터리 구조가 예측 가능해 AI 도구가 실수 없이 작업을 수행할 수 있습니다.
파일 구조뿐만 아니라, 표현력 있는 문법과 포괄적인 문서 덕분에 AI 에이전트는 필요한 맥락 정보를 충분히 얻어 올바른 코드, 즉 Laravel 스타일의 코드를 만들어낼 수 있습니다. Eloquent 연관 관계, 폼 리퀘스트, 미들웨어와 같은 기능 역시 예측 가능한 패턴을 따르므로, AI가 쉽게 이해하고 활용할 수 있습니다. 그 결과, AI가 작성한 코드도 숙련된 Laravel 개발자가 작성한 것처럼 자연스럽게 만들어집니다.
AI 지원 개발에 이상적인 프레임워크로서의 Laravel에 대해 더 알고 싶다면 agentic development 문서를 참고하세요.
A Community Framework
Laravel은 PHP 생태계의 우수한 패키지들을 결합하여, 가장 강력하고 개발자 친화적인 프레임워크를 제공합니다. 전 세계 수많은 뛰어난 개발자들이 Laravel에 contributed to the framework하고 있습니다. 여러분도 언젠가 Laravel에 기여하게 될지도 모릅니다.
Creating a Laravel Application
Installing PHP and the Laravel Installer
처음 Laravel 애플리케이션을 만들기 전에, 로컬 머신에 PHP, Composer, 그리고 the Laravel installer가 설치되어 있는지 확인하세요. 또한, 애플리케이션의 프론트엔드 자산을 컴파일하기 위해 Node and NPM 또는 Bun 중 하나를 설치해야 합니다.
만약 로컬 머신에 PHP와 Composer가 설치되어 있지 않다면, 아래 명령어로 macOS, Windows, Linux에서 PHP, Composer, Laravel 설치 도구를 한 번에 설치할 수 있습니다:
/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
# Run as administrator...
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))
/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"
위 명령어 중 하나를 실행한 후에는 터미널 세션을 다시 시작하세요. 추후 PHP, Composer, Laravel 설치 도구를 php.new로 설치한 이후에도, 위 명령어를 다시 실행하면 업데이트할 수 있습니다.
이미 PHP와 Composer가 설치되어 있다면 Composer로 Laravel 설치 도구만 따로 설치할 수 있습니다:
composer global require laravel/installer
보다 완벽한 기능과 그래픽 기반의 PHP 설치/관리를 원한다면 Laravel Herd를 참고하세요.
Creating an Application
PHP, Composer, Laravel 설치 도구 설치가 끝났다면 이제 새로운 Laravel 애플리케이션을 바로 만들 수 있습니다. Laravel 설치 도구는 원하는 테스트 프레임워크, 데이터베이스, 스타터 키트 등을 선택할 수 있도록 안내합니다:
laravel new example-app
애플리케이션이 만들어지면, dev Composer 스크립트로 Laravel의 로컬 개발 서버, 큐 워커, Vite 개발 서버를 실행할 수 있습니다:
cd example-app
npm install && npm run build
composer run dev
개발 서버가 실행되면, 애플리케이션은 웹 브라우저에서 http://localhost:8000 주소로 접속 가능합니다. 이제 start taking your next steps into the Laravel ecosystem할 준비가 되었습니다. 물론 configure a database도 원하실 수 있습니다.
Laravel 애플리케이션 개발을 빠르게 시작하고 싶다면 starter kits를 사용해 보세요. Laravel의 스타터 키트는 인증 시스템(백엔드/프론트엔드 포함)을 빠르게 적용할 수 있습니다.
Initial Configuration
Laravel 프레임워크의 모든 설정 파일은 config 디렉터리에 저장됩니다. 각 옵션에는 설명이 잘 달려 있으니 언제든 파일을 살펴보며 설정 가능한 옵션을 익혀보세요.
Laravel은 기본값 그대로도 대부분의 경우 별도의 추가 설정이 필요하지 않습니다. 바로 개발을 시작하실 수 있습니다! 하지만, config/app.php 파일과 그 문서도 한번 확인해 보시기 바랍니다. 예를 들어 url, locale 등 애플리케이션 특성에 따라 변경할 수 있는 여러 옵션이 포함되어 있습니다.
Environment Based Configuration
Laravel의 설정 값은 로컬 머신에서 실행하는지, 운영 서버에서 실행하는지에 따라 값이 달라질 수 있습니다. 그래서 중요한 설정 값들은 애플리케이션 루트의 .env 파일을 통해 지정하는 것이 일반적입니다.
.env 파일은 개발자나 서버별 환경이 다를 수 있으므로 애플리케이션의 소스 관리 시스템에는 커밋하지 않는 것이 좋습니다. 게다가 침입자가 소스 관리 저장소에 접근할 경우 중요한 인증 정보가 모두 노출되어 보안상 위험하기 때문입니다.
.env파일과 환경 기반 설정에 대해 더 자세히 알고 싶다면 configuration documentation를 참고하세요.
Databases and Migrations
Laravel 애플리케이션을 만들었다면 데이터를 데이터베이스에 저장하고 싶을 것입니다. 기본적으로 여러분의 .env 설정 파일에는 Laravel이 SQLite 데이터베이스를 사용하도록 지정되어 있습니다.
애플리케이션을 생성하는 과정에서 Laravel이 자동으로 database/database.sqlite 파일을 만들고, 마이그레이션을 실행해 필요한 데이터베이스 테이블도 초기화합니다.
MySQL이나 PostgreSQL 등 다른 데이터베이스 드라이버를 사용하고 싶다면, .env 설정 파일에서 적절한 데이터베이스로 변경할 수 있습니다. 예를 들어 MySQL을 사용하려면, .env 설정 파일의 DB_* 변수를 아래와 같이 수정하면 됩니다:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=
SQLite 이외 데이터베이스를 사용한다면, 직접 데이터베이스를 생성하고 database migrations을 실행해야 합니다:
php artisan migrate
macOS나 Windows에서 MySQL, PostgreSQL, Redis 등을 로컬에 설치하고 싶다면, Herd Pro 또는 DBngin을 이용해 보세요.
Directory Configuration
Laravel은 반드시 웹 서버의 "웹 디렉터리" 루트에서 서비스되어야 합니다. 웹 디렉터리의 하위 디렉터리에서 Laravel 애플리케이션을 실행하려고 해서는 안 됩니다. 그렇게 할 경우 애플리케이션에 포함된 민감한 파일들이 노출될 수 있습니다.
Installation Using Herd
Laravel Herd는 macOS와 Windows에서 사용할 수 있는 매우 빠르고, 네이티브한 Laravel·PHP 개발 환경입니다. Herd에는 Laravel 개발에 필요한 PHP, Nginx 등이 모두 포함되어 있습니다.
Herd를 설치하면 바로 Laravel 개발을 시작할 수 있습니다. Herd에는 php, composer, laravel, expose, node, npm, nvm 등 개발에 필요한 명령줄 도구가 기본 제공됩니다.
Herd Pro는 Herd에 강력한 추가 기능을 제공합니다. 예를 들어, 로컬 MySQL, Postgres, Redis 데이터베이스 생성/관리, 메일 뷰잉, 로그 모니터링 기능 등이 포함되어 있습니다.
Herd on macOS
macOS에서 개발한다면 Herd website에서 설치 프로그램을 다운로드할 수 있습니다. 설치 프로그램은 최신 버전의 PHP를 자동으로 다운로드하고, Mac에서 Nginx가 항상 백그라운드에서 실행되도록 설정합니다.
macOS용 Herd는 dnsmasq를 사용해 "파킹된" 디렉터리를 지원합니다. 파킹된 디렉터리 내의 Laravel 애플리케이션은 자동으로 Herd에서 서비스됩니다. 기본적으로 Herd는 ~/Herd 경로에 파킹 디렉터리를 만드며, 이곳에 있는 Laravel 애플리케이션은 디렉터리 명을 그대로 사용해 .test 도메인에서 접근할 수 있습니다.
Herd를 설치한 뒤, 새로운 Laravel 애플리케이션을 만들 때는 Herd와 함께 제공되는 Laravel CLI를 활용하는 것이 가장 빠릅니다:
cd ~/Herd
laravel new my-app
cd my-app
herd open
물론 시스템 트레이의 Herd 메뉴에서 Herd UI를 열어 파킹 디렉터리나 기타 PHP 설정을 직접 관리할 수도 있습니다.
Herd에 대해 더 알고 싶다면 Herd documentation를 참고하세요.
Herd on Windows
Herd website에서 Windows용 설치 프로그램을 다운로드할 수 있습니다. 설치가 완료되면 Herd를 실행해 온보딩 절차를 마치고, Herd UI에 처음으로 접속할 수 있습니다.
Herd UI는 시스템 트레이에 있는 Herd 아이콘을 왼쪽 클릭해서 열 수 있으며, 오른쪽 클릭하면 필요한 여러 도구에 빠르게 접근할 수 있는 메뉴가 나타납니다.
설치 중 Herd는 홈 디렉터리의 %USERPROFILE%\Herd에 "파킹된" 디렉터리를 생성합니다. 이 디렉터리 안에 있는 모든 Laravel 애플리케이션은 Herd에 의해 자동으로 서비스되며, 디렉터리 이름을 사용해 .test 도메인으로 쉽게 접근할 수 있습니다.
설치 후에는 Herd에 포함된 Laravel CLI로 새로운 Laravel 애플리케이션을 만들 수 있습니다. PowerShell을 열고 아래 명령어를 실행하세요:
cd ~\Herd
laravel new my-app
cd my-app
herd open
Herd에 대한 더 자세한 내용은 Herd documentation for Windows를 참고하세요.
IDE Support
Laravel 애플리케이션 개발에는 원하는 어떤 코드 에디터도 자유롭게 사용할 수 있습니다. 가볍고 확장성 있는 에디터를 원한다면 VS Code 또는 Cursor에 공식 Laravel VS Code Extension을 추가해서 사용해 보세요. Laravel 전용 문법 하이라이팅, 코드 스니펫, 아티즌 명령어 통합, Eloquent 모델/라우트/미들웨어/에셋/설정/Inertia.js 자동완성 등 강력한 기능을 지원합니다.
좀 더 강력하고 깊이 있는 Laravel 지원을 원한다면 JetBrains의 PhpStorm을 추천합니다. Blade 템플릿, Eloquent 모델/라우트/뷰/다국어/컴포넌트 자동완성, 강력한 코드 생성 및 프로젝트 전체 네비게이션 등 Laravel을 위한 내장 기능을 제공합니다.
클라우드 기반 개발 경험이 필요하다면 Firebase Studio를 활용해 브라우저에서 바로 Laravel 개발을 할 수 있습니다. 별도 셋업 없이, 언제 어디서든 즉시 Laravel 프로젝트를 시작할 수 있습니다.
Laravel and AI
Laravel Boost는 AI 코딩 에이전트와 Laravel 애플리케이션 사이의 장벽을 허물어주는 강력한 도구입니다. Boost는 AI 에이전트에게 Laravel만의 맥락, 도구, 지침을 제공하여, Laravel 규칙 및 버전에 맞는 더 정확한 코드를 만들어낼 수 있게 도와줍니다.
Boost를 애플리케이션에 설치하면, AI 에이전트가 사용할 수 있는 15개 이상의 전용 도구가 추가됩니다. 사용 중인 패키지 확인, 데이터베이스 쿼리, Laravel 문서 검색, 브라우저 로그 읽기, 테스트 생성, Tinker를 통한 코드 실행 등이 가능합니다.
또한 Boost는 프로젝트별로 설치된 패키지 버전에 맞는 1만 7천개 이상의 벡터화된 Laravel 생태계 문서 데이터를 AI 에이전트에 제공합니다. 덕분에 AI가 프로젝트에 딱 맞는 버전의 정보를 기반으로 더 정확한 도움을 줄 수 있습니다.
Boost에는 Laravel에서 직접 관리하는 AI 개발 지침이 함께 제공되어, 에이전트가 프레임워크 규칙을 잘 따르고, 적절한 테스트 코드를 작성하며, 코드 생성 시 흔히 저지르는 실수를 방지할 수 있습니다.
Installing Laravel Boost
Boost는 PHP 8.1 이상을 사용하는 Laravel 10, 11, 12 버전에서 설치할 수 있습니다. 다음 명령어로 개발 의존성으로 Boost를 추가하세요:
composer require laravel/boost --dev
설치가 끝나면, 상호작용형 인스톨러를 실행합니다:
php artisan boost:install
인스톨러는 여러분의 IDE와 AI 에이전트를 자동 감지하며, 프로젝트에 적합한 기능들을 선택적으로 활성화할 수 있습니다. Boost는 기존 프로젝트 규칙을 존중하며, 기본적으로 스타일 규칙을 강제하지 않습니다.
Boost에 대해 더 알아보려면 Laravel Boost repository on GitHub를 참고하세요.
Adding Custom AI Guidelines
Laravel Boost에 직접 만든 AI 지침을 추가하고 싶다면, 애플리케이션의 .ai/guidelines/* 디렉터리에 .blade.php 또는 .md 파일을 넣으면 됩니다. 이 파일들은 boost:install 명령 실행 시 Boost의 기본 지침과 함께 자동으로 적용됩니다.
Next Steps
이제 Laravel 애플리케이션을 만들었으니, 앞으로 무엇을 공부하고 개발할지 고민하실 수 있습니다. 먼저, Laravel이 어떻게 동작하는지 익히기 위해 다음 문서를 꼭 읽어보시길 추천합니다:
여러분이 Laravel을 어떻게 사용하고 싶은지에 따라서도 앞으로의 학습 방향이 달라집니다. Laravel 프레임워크를 활용하는 대표적인 두 가지 방식을 아래에서 소개합니다.
Laravel the Full Stack Framework
Laravel을 풀스택 프레임워크로 사용할 수 있습니다. 여기서 "풀스택"이라는 것은, Laravel로 요청을 처리하고, Blade templates이나 Inertia 같은 SPA 하이브리드 기술로 프론트엔드까지 직접 렌더링하는 방식을 의미합니다. 가장 일반적이고, 저희가 생각하기에도 가장 생산적인 Laravel 사용 방식입니다.
이 방식으로 Laravel을 사용할 계획이라면 frontend development, routing, views, Eloquent ORM 문서를 확인해 보세요. 또한, 커뮤니티 패키지인 Livewire, Inertia도 추천합니다. 이 패키지들은 Laravel 풀스택 프레임워크 환경에서, SPA가 주는 UI의 장점도 함께 누릴 수 있게 해 줍니다.
풀스택 프레임워크로 Laravel을 사용할 때는 Vite로 CSS, 자바스크립트 자산을 빌드하는 방법도 꼭 익히시기 바랍니다.
애플리케이션 개발을 더 빠르게 시작하고 싶다면 공식 application starter kits를 확인해보세요.
Laravel the API Backend
Laravel은 자바스크립트 싱글 페이지 애플리케이션(SPA)이나 모바일 애플리케이션을 위한 API 백엔드로도 사용할 수 있습니다. 예를 들어 Next.js 애플리케이션의 API 백엔드로 Laravel을 사용할 수 있습니다. 이 경우, Laravel은 authentication과 데이터 저장/조회 기능은 물론, 큐, 이메일, 알림 등 다양한 강력한 서비스를 제공합니다.
이와 같이 Laravel을 API 백엔드로 활용한다면, routing, Laravel Sanctum, Eloquent ORM에 관한 문서를 참고해 보세요.