ServBay PHP 버전 관리: 명령행 및 웹사이트 환경 설정 가이드

ServBay는 macOS와 Windows를 지원하는 강력한 로컬 웹 개발 환경 도구로, 다양한 프로그래밍 언어와 데이터베이스를 동시에 다룰 수 있습니다. 이 문서는 ServBay에서 각기 다른 프로젝트의 PHP 버전을 자유롭게 관리하는 방법을 설명합니다. 명령행 스크립트 실행부터 특정 웹사이트의 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 명령이 지정 버전의 실행 파일을 참조하게 됩니다. 폴더에서 벗어나면 환경은 ServBay의 글로벌 기본값으로 되돌아가며, 시스템에는 영향이 없습니다.

2. 설정 방법

프로젝트 루트 디렉터리에 .servbay.config 파일을 만들고, 다음과 같이 PHP 버전을 지정하세요:

bash

# 현재 프로젝트에 사용할 PHP 버전 지정 (예: PHP 8.3 사용)
PHP_VERSION=8.3

# 프로젝트가 특정 Node.js 버전도 필요하다면 함께 지정 가능 (예: Node.js 20 사용)
# NODE_VERSION=20

PHP_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(웹사이트 루트 디렉터리): 웹 파일이 위치한 디렉터리 지정. ServBay 기본 경로 /Applications/ServBay/www/ 아래 하위 폴더(예: /Applications/ServBay/www/your-website-name/public, Laravel/Symfony 프로젝트 기준) 활용 권장.
- Domain(도메인): 사이트 접근용 로컬 도메인(예: your-website-name.servbay.demo) 설정. ServBay는 이 도메인에 자동으로 로컬 DNS 및 HTTPS 인증서(ServBay User CA 또는 ServBay Public CA) 설정을 지원하여 개발/테스트를 편리하게 합니다.
- PHP Version(PHP 버전): 드롭다운에서 해당 사이트에 사용할 ServBay 설치/활성화 PHP 버전을 선택(예: 7.4, 8.1, 8.3, 8.5 등).
저장 및 적용: 설정을 완료한 뒤 저장 버튼 클릭. ServBay가 자동으로 변경사항을 적용하며, 웹 서버 및 PHP-FPM 프로세스 재시작이 필요할 수 있습니다.

2. 기술적 특징 및 장점

서비스 분리: 각 웹사이트는 독립된 PHP-FPM 프로세스 풀로 작동하므로, 사이트별로 PHP 환경이 완전히 격리됩니다. 한 사이트의 오류나 메모리 누수도 다른 사이트에 영향을 미치지 않습니다.
성능 최적화: ServBay의 소프트웨어 패키지(PHP 각 버전 포함)는 ARM64(Apple Silicon)와 X86_64 아키텍처 모두에 맞게 최적화되어 뛰어난 성능을 제공합니다.
오류 진단:
- PHP 에러 로그 확인: /Applications/ServBay/var/log/php/php_error.log에서 웹사이트 내 PHP 에러 기록을 확인하세요.
- PHP-FPM 프로세스 상태: ServBay CLI 도구 servbayctl로 특정 PHP 버전의 상태 확인(예: servbayctl status php 8.3).

3. 웹 서버 및 데이터베이스 통합

ServBay는 프로젝트 특성에 맞게 다양한 웹 서버 및 데이터베이스를 선택/관리할 수 있도록 지원합니다:

웹 서버 지원: ServBay 1.7.0 이상에서는 아파치(Apache), 엔진엑스(Nginx), 캐디(Caddy) 등 웹 서버를 손쉽게 전환할 수 있습니다. 이들 서버는 ServBay가 관리하는 PHP-FPM과 매끄럽게 통합됩니다.
데이터베이스 연동: MySQL, MariaDB, PostgreSQL, MongoDB, Redis 등 다양한 버전의 데이터베이스 패키지를 설치/운영할 수 있습니다. 웹사이트 설정 혹은 프로젝트 코드에서 ServBay 내 특정 DB 인스턴스에 연결할 수 있으며, MariaDB 11.x 등 특정 DB가 필요한 프레임워크/프로젝트(Laravel 등)도 유연하게 지원 가능합니다.

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 vs 웹 환경 차이: 동일 버전 PHP라도 명령행(CLI) 환경과 웹 서비스(PHP-FPM) 환경은 기본 설정 및 로드되는 확장 모듈에 차이가 있습니다. 예를 들면, opcache 확장은 PHP-FPM에서 기본 활성화되어 성능을 높지만, CLI에선 기본 비활성화일 수 있습니다. 이로 인한 차이는 각 버전별 ServBay의 php.ini 및 로드된 확장 모듈을 따로 확인해야 합니다.
ServBay Runtime 최신 유지: ServBay 앱과 Runtime 버전을 항상 최신으로 관리하세요. ServBay 팀은 PHP 및 각종 패키지의 최신 버전/보안 패치를 지속적으로 제공하므로, 앱/Runtime 업데이트 시 새로운 기능과 개선사항을 자동으로 적용받을 수 있습니다.

자주 묻는 질문 (FAQ)

Q: 명령행과 웹사이트 환경의 PHP 버전이 충돌할 경우 어떻게 하나요?

A: 명령행 환경(프로젝트별 .servbay.config로 제어)과 웹사이트 환경(ServBay GUI 설정)은 서로 완전 독립적입니다. .servbay.config는 현재 터미널 세션의 php 명령(예: Composer 또는 Artisan 실행)에만 적용되며, 웹사이트 설정은 웹서버(Apache/Nginx/Caddy)가 PHP-FPM을 통해 웹 요청을 처리할 때 어느 PHP 버전을 쓸지 결정합니다. 양쪽이 직접적으로 충돌하지는 않으며, 하나의 프로젝트도 필요에 따라 명령행과 웹 환경 PHP 버전을 다르게 쓸 수 있습니다(예: 명령행은 Composer 위해, 웹은 운영 환경 위해 등). 단, 개발과 실운영 환경의 일관성을 위해 두 환경의 버전을 맞추는 것이 일반적으로 권장됩니다.

결론

ServBay는 .servbay.config 파일과 직관적인 GUI 환경을 통해, 개발자에게 강력하면서도 유연한 PHP 버전 관리 기능을 제공합니다. 구버전 PHP에 의존하는 레거시 프로젝트부터 최신 PHP로 개발하는 신규 앱까지, ServBay만 있으면 손쉽게 버전 관리가 가능합니다. 이런 기능을 적극 활용하면, 로컬 개발 환경과 실운영 환경의 차이를 최소화하고, 개발 효율과 프로젝트 안정성을 높일 수 있습니다.

ServBay PHP 버전 관리: 명령행 및 웹사이트 환경 설정 가이드 ​

1. 명령행 환경: .servbay.config로 프로젝트별 PHP 버전 관리 ​

1. .servbay.config의 역할과 원리 ​

2. 설정 방법 ​

3. 유의사항 및 고급 팁 ​

4. 실행 예시 ​

2. 웹사이트 환경: ServBay GUI로 PHP 버전 관리 ​

1. 설정 절차 ​

2. 기술적 특징 및 장점 ​

3. 웹 서버 및 데이터베이스 통합 ​

3. 환경별 협업 및 베스트 프랙티스 ​

유의사항 ​

자주 묻는 질문 (FAQ) ​

결론 ​