Laravel 로컬 설치하기

1. Homebrew 업데이트 및 PHP 설치

1.1. Homebrew 업데이트

brew update

• Homebrew: macOS에서 패키지를 간편하게 설치/관리할 수 있게 해주는 패키지 매니저입니다.
• brew update 명령어를 통해 Homebrew 자체를 최신 상태로 업데이트합니다.

1.2. 설치 가능한 PHP 버전 확인

brew search php

• 설치 가능한 PHP의 버전 목록이 표시됩니다.
• PHP 8.1, 8.2 등이 나올 수 있으며, 프로젝트 호환성에 맞추어 원하는 버전을 골라 설치하시면 됩니다.

1.3. PHP 설치

brew install php

• 위 예시는 Homebrew에서 현재 기본 PHP 버전을 설치하는 예시입니다.
• 특정 버전을 설치하려면 예: brew install php@8.1 처럼 버전을 지정할 수 있습니다.

설치 후 PHP 버전을 확인합니다.

php -v

설치한 PHP 버전이 정상적으로 출력되면 설치가 완료된 것입니다.

2. Composer 설치

2.1. Composer 란?

Composer는 PHP의 의존성 관리 도구로, Laravel과 같은 프레임워크에서 필요한 외부 라이브러리나 패키지를 쉽게 설치하고 관리할 수 있게 해줍니다.

• 패키지 관리: 필요한 라이브러리를 composer.json에 기록하면 자동으로 설치됩니다.
• 의존성 해결: 라이브러리 간 의존 관계를 자동으로 처리하여 충돌을 방지합니다.
• 버전 관리 및 자동화: 적절한 버전을 선택하고, 업데이트나 설치 작업을 자동화하여 개발 효율성을 높입니다.

2.2. Composer 설치 스크립트 다운로드

아래 명령어는 Composer 공식 홈페이지에 안내된 방법으로, 설치 스크립트를 직접 받아서 검증 후 설치하는 절차입니다.

공식문서 링크: https://getcomposer.org/doc/00-intro.md

1. 설치 스크립트 다운로드

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

• PHP의 copy() 함수를 사용해 installer 스크립트를 로컬에 composer-setup.php라는 이름으로 저장합니다.

2. 해시값 검증

(아래 해시값은 예시이며, 실제로는 공식 사이트에서 제공되는 최신 해시값을 확인하시기 바랍니다.)

php -r "if (hash_file('sha384', 'composer-setup.php') === 'dac665fdc30fdd8ec78b38b9800061b4150413ff2e3b6f88543c636f7cd84f6db9189d43a81e5503cda447da73c7e5b6') { echo 'Installer verified'.PHP_EOL; } else { echo 'Installer corrupt'.PHP_EOL; unlink('composer-setup.php'); exit(1); }"

• 설치 스크립트가 공식적으로 제공된 스크립트와 동일한지 검증합니다.
• Installer verified 메시지가 나오면 다음 단계로 진행합니다.
• Installer corrupt 메시지가 나온다면, 다운로드가 깨졌거나 해시값이 일치하지 않는 것이므로 다시 다운로드해야 합니다.

3. Composer 설치

php composer-setup.php

• composer-setup.php 스크립트를 실행하여 Composer를 설치합니다.
• 설치가 완료되면 같은 폴더에 composer.phar 파일이 생성됩니다.

4. 설치 스크립트 제거

php -r "unlink('composer-setup.php');"

더 이상 필요 없는 설치 스크립트를 삭제합니다.

2.3. Composer 전역 실행 설정

sudo mv composer.phar /usr/local/bin/composer

• composer.phar 파일을 /usr/local/bin/composer 경로로 이동시키면서 실행 권한을 주기 위해 sudo를 사용합니다.
• macOS 비밀번호를 요청받으면 본인 계정의 macOS 관리자 비밀번호를 입력합니다.
• 이렇게 하면 터미널에서 전역으로 composer 명령어를 실행할 수 있게 됩니다.

설치 확인

composer -V

명령어 입력 시 Composer 버전 정보가 출력되어야 합니다.

3. Laravel Installer 설치

3.1. Laravel Installer 란?

Laravel Installer는 Laravel 프레임워크의 새로운 애플리케이션을 빠르게 생성할 수 있도록 도와주는 커맨드라인 도구입니다. 주된 특징은 아래과 같습니다.

• 개발 환경 간소화 및 빠른 프로젝트 생성: 프로젝트명 명령어로 초기 설정과 기본 디렉터리 구조를 자동으로 구성해주어, 개발자가 바로 비즈니스 로직에 집중할 수 있도록 돕습니다. 즉, Laravel Installer는 Laravel 애플리케이션을 시작하는 과정을 간소화해 주는 매우 유용한 도구입니다.

3.2. Laravel 설치를 위한 명령어

composer global require "laravel/installer"

• Composer를 통해 laravel/installer 패키지를 글로벌로 설치합니다.
• 글로벌로 설치하면 laravel 명령어를 어디서든 사용할 수 있게 됩니다.

4. Composer 글로벌 바이너리 PATH 설정

4.1. 현재 쉘 확인

echo $SHELL

macOS의 기본 쉘은 zsh일 가능성이 높습니다. (모하비 이후 버전)

4.2. zsh를 사용 중인 경우

vi ~/.zshrc

• .zshrc 설정 파일을 vi 편집기로 엽니다.
• 다른 편집기(예: nano, code, sublime 등)를 사용해도 됩니다.
  예) nano ~/.zshrc, code ~/.zshrc

4.2.1. PATH 환경 변수에 Composer 글로벌 경로 추가

• .zshrc 파일 안에서 입력 모드로 들어갑니다: esc → i
• 아래 줄을 추가합니다. (이미 존재한다면 중복 없이 확인)

export PATH="$PATH:$HOME/.composer/vendor/bin"

• 입력이 끝나면 esc 키 → :wq → 엔터키 를 눌러 저장 후 종료합니다.

주의: macOS 일부 버전에서는 Composer 글로벌 설치 경로가 ~/.composer/vendor/bin 대신 ~/.config/composer/vendor/bin 인 경우도 있습니다. 본인의 설치 경로가 어디인지 확인 후 적절히 수정하세요.

4.3. 설정 파일 재로드

source ~/.zshrc

• .zshrc 파일에 설정한 내용을 즉시 반영합니다.

4.4. 환경 변수 확인

echo $PATH

• echo $PATH 명령어로 실제 경로가 추가되었는지 확인합니다.
• ...:/Users/사용자명/.composer/vendor/bin 과 같은 경로가 보이면 정상입니다.

4.5. laravel 명령어 확인

echo laravel

• 에러 없이 laravel 라는 단어가 출력되면 현재 PATH에 laravel 이 인식되고 있는 것입니다.
• 혹은 직접 laravel --version 명령어로 버전을 확인해도 됩니다.

5. Valet 설치

5.1. Valet 이란?

• Valet는 macOS 전용 라라벨 개발 환경 툴로, nginx 웹 서버 및 DnsMasq 등을 간단히 설정하여 로컬 개발을 빠르고 편리하게 진행할 수 있게 해줍니다.

5.2. Valet 설치

composer global require laravel/valet

5.3. Valet 설정

valet install

• valet install 명령어를 실행하면 내부적으로 nginx, dnsmasq 등이 자동 설정됩니다.
• 실행 시에도 macOS 비밀번호를 물어볼 수 있습니다. 입력해 주면 설치가 진행됩니다.

6. 새로운 Laravel 프로젝트 생성

6.1. Laravel 프로젝트 생성

laravel new blog

• 현재 디렉터리(또는 지정한 경로)에 blog라는 이름의 새로운 Laravel 프로젝트를 생성합니다.
• 생성된 후 프로젝트 폴더(blog) 안에 라라벨의 디렉터리 구조와 기본 코드가 들어있습니다.

프로젝트 폴더로 이동 후, php artisan serve 명령어를 사용해 로컬 서버를 구동해볼 수 있습니다.

cd blog
php artisan serve

터미널에 Laravel development server started: http://127.0.0.1:8000 등의 메시지가 보이면, 브라우저에서 http://127.0.0.1:8000 에 접속해 Laravel 웰컴 페이지가 뜨는지 확인할 수 있습니다.

7. (선택) Valet 사용 시 프로젝트 접근

Valet 설치 후에는 별도의 php artisan serve 없이도 로컬에 .test 도메인으로 접근할 수 있습니다.

1. Valet 서비스 시작 / 폴더 연결

cd ~
mkdir Sites
cd Sites
valet park

• ~/Sites 폴더 안의 프로젝트들은 폴더명.test로 접근할 수 있게 됩니다.
• 예: ~/Sites/blog 프로젝트가 있다면 브라우저에서 http://blog.test 로 접근 가능.
  (DNS 설정과 nginx 설정을 Valet가 자동으로 처리해줍니다.)
  프로젝트 생성(또는 이동)

cd ~/Sites
laravel new blog

이 폴더에 신규 프로젝트를 만들면 자동으로 blog.test 로 접속 가능합니다.

마무리 정리

1. Homebrew 업데이트 → 원하는 PHP 버전 설치
2. Composer를 설치 스크립트로 직접 설치 후 전역 등록
3. composer global require "laravel/installer" 로 Laravel 설치
4. 쉘 설정 파일(~/.zshrc)에 PATH를 등록하여 laravel 명령어를 전역 인식
5. (선택) Valet 설치 및 설정(valet install)
6. laravel new blog 명령으로 새 프로젝트 생성

설치 과정 중 macOS 비밀번호를 여러 번 물어볼 수 있으며, 이는 관리자 권한이 필요한 폴더 접근/설치/링크 작업 때문입니다.

위 과정을 순서대로 진행하면 macOS에서 Laravel 개발 환경이 완성됩니다. 이후에는 프로젝트를 생성하고, cd blog && php artisan serve 또는 Valet를 통해 로컬에서 Laravel을 구동하여 개발을 이어갈 수 있습니다.

Laravel 공식 문서를 읽어보면서( 공식 사이트 ) 프로젝트 설정이나 폴더 구조를 이해해 두는 것이 좋습니다.
macOS 업그레이드나 새 버전에서 Valet, PHP 버전 호환 문제가 발생할 수 있으니, 주기적으로 Homebrew와 Valet 등을 업데이트해 주는 것이 좋습니다.