ServBay PHP 버전 관리: 커맨드라인 및 웹사이트 환경 설정 가이드
ServBay는 macOS를 위해 설계된 강력한 로컬 웹 개발 환경 도구로, 다양한 프로그래밍 언어와 데이터베이스를 지원합니다. 본 문서에서는 ServBay에서 프로젝트마다 다양한 PHP 버전을 유연하게 관리하는 방법을, 커맨드라인에서 스크립트를 실행할 때, 혹은 특정 웹사이트를 위한 환경을 설정할 때 각각 상세하게 설명합니다. ServBay의 PHP 버전 관리 메커니즘을 숙지하면 개발 효율성이 크게 향상되고, 프로젝트 환경의 격리와 안정성도 보장할 수 있습니다.
1. 커맨드라인 환경: .servbay.config로 프로젝트별 PHP 버전 관리
프로젝트의 루트 디렉토리에 .servbay.config 설정 파일을 생성하면, 각 프로젝트마다 개별적인 커맨드라인 PHP 버전을 지정할 수 있습니다. ServBay는 현재 터미널의 작업 경로를 기준으로 해당 PHP 환경을 자동으로 로드하여, 프로젝트 간의 버전 격리 및 전역 설정 충돌을 방지합니다.
1. .servbay.config의 역할 및 원리
- 프로젝트별 버전 제어: ServBay는 PHP 5.6부터 최신 안정 버전, 개발 버전까지 여러 PHP 버전을 동시에 설치하고 실행할 수 있게 해줍니다.
.servbay.config로 각 프로젝트에 필요한 PHP 버전을 정확히 지정할 수 있습니다. - 비침습적 전환: 터미널에서
cd명령을 통해.servbay.config가 포함된 프로젝트 디렉터리로 진입하면, ServBay가 해당 파일을 자동으로 감지하여 현재 터미널 세션의 환경 변수(주로PATH)를 임시 변경합니다. 이로써php,composer등의 명령어가 지정한 PHP 버전을 가리키게 되며, 디렉터리를 벗어나면 글로벌 기본 설정으로 복원됩니다. 시스템 환경에는 일절 영향을 주지 않습니다.
2. 설정 방법
프로젝트 루트 디렉토리에 .servbay.config라는 파일을 만들고 아래와 같이 PHP 버전을 지정하세요:
bash
# 이 프로젝트에서 사용할 PHP 버전 지정 (예: PHP 8.3 사용)
PHP_VERSION=8.3
# 프로젝트가 특정 Node.js 버전도 필요하다면 함께 지정 가능 (예: Node.js 20 사용)
# NODE_VERSION=20PHP_VERSION값은 ServBay에서 이미 설치된 PHP 버전 식별자여야 하며, 보통 메이저 또는 메이저.마이너 번호 형태입니다(7.4,8.1,8.3,8.5등). 반드시 해당 버전이 ServBay에 설치 및 활성화된 상태인지 확인하세요.NODE_VERSION역시 동일 방식으로 Node.js 버전을 지정합니다.
적용 확인:
.servbay.config가 포함된 프로젝트 폴더에서 터미널을 열고, 아래 명령어로 설정이 적용되었는지 검증하세요:
bash
$ pwd # 현재 디렉터리가 프로젝트 루트인지 확인
$ php -v # PHP 버전이 설정한 버전(예: PHP 8.3.x)인지 확인
$ composer install # 의존성 설치 시 현재 활성화된 PHP 버전 사용.servbay.config를 수정했는데 버전이 변하지 않는다면, 터미널을 완전히 닫았다 다시 열거나 cd . 명령으로 ServBay 설정 재적용을 유도해 보세요.
3. 사용 시 주의사항 및 고급 팁
- 버전 호환성: 명령어 실행 시 "Class not found", "Call to undefined function" 등 오류가 발생하면, 프로젝트 의존성(
composer.json등)이 요구하는 PHP 지원 범위를 반드시 확인하고, 설정한 PHP 버전 호환 여부를 점검하세요. 구버전 프로젝트의 경우 최신 PHP에 제거된 확장이나 기능(예: PHP 7.2는mcrypt확장 제거) 의존성이 있을 수 있습니다. - 글로벌 기본값: 현재 디렉터리와 상위 경로에
.servbay.config파일이 없으면, ServBay GUI의 "설정"에서 지정한 글로벌 기본 PHP 버전이 사용됩니다. - 복수 서비스 관리:
.servbay.config는 PHP뿐만 아니라 Node.js 버전도(NODE_VERSION으로) 지정할 수 있습니다. PHP 백엔드, Node.js 프론트엔드 빌드(Webpack, Vite 등)를 동시에 사용하는 프로젝트에 특히 유용합니다.
4. 실행 예시
아래는 서로 다른 프로젝트 디렉터리에서 .servbay.config를 이용해 PHP 버전이 자동 전환되는 데모 화면입니다:
이미지 설명: ServBay에서 각기 다른 .servbay.config 파일이 있는 디렉터리로 이동하면 php -v 실행 시 해당 파일에 지정한 PHP 버전으로 자동 전환됩니다.
2. 웹사이트 환경: ServBay GUI에서 PHP 버전 관리
ServBay의 그래픽 사용자 인터페이스(GUI)는 각 웹사이트마다 독립적인 PHP 버전 설정을 지원합니다. 웹사이트 환경에서의 PHP 버전은 커맨드라인 환경과 완전히 별개이므로, 사이트별 요구에 맞춰 자유롭게 선택할 수 있습니다.
1. 설정 절차
- ServBay GUI 실행: ServBay 앱을 실행하세요.
- 웹사이트 관리로 이동: 좌측 네비게이션 바의 웹사이트(Websites) 탭을 선택합니다.
- 웹사이트 추가/편집:
- 왼쪽 하단 + 버튼으로 신규 사이트 설정을 시작할 수 있습니다.
- 이미 등록된 사이트 설정을 선택해 수정할 수도 있습니다.
- 사이트 속성 설정:
- Root Directory(사이트 루트 디렉토리): 웹사이트 소스 파일이 위치한 폴더를 지정합니다.
/Applications/ServBay/www/하위 디렉토리를 권장하며, 예를 들어 Laravel 또는 Symfony 프로젝트라면/Applications/ServBay/www/your-website-name/public식으로 설정하세요. - Domain(도메인): 로컬 개발 도메인 예:
your-website-name.servbay.demo와 같이 등록합니다. ServBay는 도메인 자동 DNS, HTTPS 인증서(ServBay User CA 또는 ServBay Public CA) 발급을 지원하여 개발과 테스트가 대폭 편리해집니다. - PHP Version(PHP 버전): 드롭다운에서 이 웹사이트에 사용할 PHP 버전을 선택합니다. ServBay에 설치 및 활성화된 모든 PHP 버전(예: 7.4, 8.1, 8.3, 8.5 등)을 목록에서 고를 수 있습니다.
- Root Directory(사이트 루트 디렉토리): 웹사이트 소스 파일이 위치한 폴더를 지정합니다.
- 설정 저장: 설정이 완료되면 저장 버튼을 클릭하세요. ServBay가 변경사항을 적용하며, 필요시 웹 서버 및 PHP-FPM 프로세스를 재시작/갱신할 수 있습니다.
2. 기술적 세부사항 및 장점
- 서비스 격리: 사이트마다 할당된 PHP 버전은 각기 별도의 PHP-FPM 프로세스 풀로 동작합니다. 이로써 사이트 간 PHP 환경의 완전한 격리가 보장되고, 한 사이트의 오류나 메모리 누수가 타 사이트에 영향을 주지 않습니다.
- 성능 최적화: ServBay 패키지(각 PHP버전)는 ARM64(Apple Silicon)와 X86_64 아키텍처 모두에 맞춰 튜닝되어, 다양한 하드웨어에서 최상의 성능을 발휘합니다.
- 오류 진단:
- PHP 오류 로그 확인: 사이트 구동 중 PHP 오류는
/Applications/ServBay/var/log/php/php_error.log에 기록됩니다. - PHP-FPM 상태 확인: ServBay 명령줄 도구
servbayctl로 특정 PHP 버전 동작 상태를 조회할 수 있습니다(예:servbayctl status php 8.3).
- PHP 오류 로그 확인: 사이트 구동 중 PHP 오류는
3. 웹서버 및 데이터베이스 통합
ServBay는 프로젝트 요구에 유연하게 맞출 수 있도록 웹서버 및 데이터베이스 선택도 지원합니다.
- 웹서버 지원: ServBay 1.7.0 이상에서는 각 사이트별로 Apache, Nginx, Caddy를 손쉽게 전환할 수 있습니다. 이들 웹서버는 ServBay의 PHP-FPM 풀과 무리 없이 연동됩니다.
- DB 연동: MySQL, MariaDB, PostgreSQL, MongoDB, Redis 등 여러 버전의 DB 패키지 설치 · 관리를 지원합니다. 사이트 설정 혹은 코드에서 ServBay 내 실행 중인 특정 DB 인스턴스에 연결할 수 있어, DB 버전/종류가 중요한 프로젝트(예: Laravel 일부 프로젝트는 MariaDB 11.x 권장)도 쉽게 운영 가능합니다.
3. 환경 간 협업 및 베스트 프랙티스
커맨드라인 환경과 웹사이트 환경에서 PHP 버전 관리가 어떻게 독립적으로 동작하는지, 각 설정 방식의 특성을 정확히 이해하면 더 나은 개발 환경을 만들 수 있습니다:
| 활용 시나리오 | 커맨드라인 환경 설정(.servbay.config) | 웹사이트 환경 설정(ServBay GUI) | 비고 |
|---|---|---|---|
| 레거시 시스템 유지 관리 | 프로젝트 루트에 PHP_VERSION=5.6 설정 | 사이트별 PHP 5.6 선택 | 구프로젝트 호환용 PHP 버전/확장 ServBay에 사전 설치 확인 |
| 신규 프로젝트 개발(예: Laravel 11) | PHP_VERSION=8.3(혹은 그 이상), 필요시 NODE_VERSION=20 | 신규 사이트 추가, 루트는 프로젝트 public 폴더, PHP 8.3+ 선택, 개발 도메인/HTTPS 활성화 | 커맨드라인 도구(Composer, Artisan, Node 빌드)와 웹환경 PHP 버전을 일치시키는 게 바람직함 |
| 차세대 PHP 버전 테스트 | 테스트 프로젝트 루트에 PHP_VERSION=8.5 | 테스트 사이트 신규 추가, PHP 8.5 선택 | 새 PHP 버전 호환성 사전 점검용 |
| Composer 명령 실행 | 현재 디렉터리 또는 상위에 .servbay.config로 올바른 PHP 버전 지정 | N/A(Composer는 커맨드라인에서 실행) | Composer는 현재 터미널 세션의 PHP 버전 사용 |
주의사항
- CLI와 웹환경 차이: 동일한 PHP 버전을 선택했어도, 커맨드라인(CLI)과 웹서비스(PHP-FPM)의 기본 설정값 · 확장 모듈 로딩 현황은 다를 수 있습니다. 예를 들어,
opcache는 PHP-FPM에선 기본 활성화로 성능을 높이지만 CLI에서는 비활성화가 기본입니다. 예상과 다른 동작이 있다면 ServBay 내부 각 PHP 버전의php.ini와 활성 확장 모듈을 꼭 확인하세요. - ServBay 런타임 업데이트: ServBay 앱과 그 런타임이 최신 상태를 유지하도록 항상 확인하세요. ServBay 팀은 꾸준히 새 PHP 버전, 보안 패치 등 패키지를 제공하며, 앱을 업데이트하면 런타임도 자동 최신화되어 새로운 기능 및 개선점을 받을 수 있습니다.
자주 묻는 질문 (FAQ)
Q: 커맨드라인과 웹사이트 환경의 PHP 버전이 충돌하면 어떻게 하나요?
A: 커맨드라인 환경(.servbay.config로 제어)과 사이트 환경(ServBay GUI로 제어)은 완전히 분리되어 동작합니다. .servbay.config는 터미널 세션에서 php 명령이 어느 버전을 가리키는지만 결정할 뿐이고, 사이트 환경은 웹서버(Apache/Nginx/Caddy)에서 PHP-FPM이 어떤 PHP 버전으로 웹 리퀘스트를 처리할지 결정합니다. 서로 직접적인 충돌은 없습니다. 한 프로젝트에서 Composer/Artisan 등의 CLI는 한 버전을 쓰고, 웹사이트 실행은 다른 PHP 버전을 지정할 수도 있으나, 실제 운영환경과의 일관성을 위해 두 환경의 PHP 버전은 맞추는 것이 권장됩니다.
정리
ServBay는 .servbay.config 파일과 직관적인 GUI를 통해 개발자에게 매우 강력하고 유연한 PHP 버전 관리 기능을 제공합니다. 구 PHP 버전이 필요한 레거시 프로젝트 유지부터, 최신 버전의 신기술 적용까지 모든 환경에 대응할 수 있습니다. 이 기능들을 적절히 활용하면, 로컬 개발 환경과 실제 운영환경의 차이를 최소화하고, 개발 효율과 프로젝트의 안정성 모두를 높일 수 있습니다.
