ServBay에서 맞춤형 PHP 모듈 컴파일 및 설치하기 (macOS)
ServBay는 macOS 사용자를 위해 설계된 강력한 로컬 웹 개발 환경으로, 현대적인 웹 개발자가 필요한 다양한 소프트웨어 패키지를 통합 제공합니다. PHP, Node.js, Python, Go, Java, 데이터베이스(MySQL, PostgreSQL, MongoDB), 캐시(Redis), 웹 서버(Caddy, Nginx, Apache) 등 폭넓은 기술 스택을 사전 탑재하고 있습니다. ServBay는 각 소프트웨어 패키지별로 여러 버전을 지원하여, 프로젝트 요구에 맞게 유연하게 환경을 전환할 수 있습니다.
ServBay에는 이미 많은 PHP 주요 모듈이 포함되어 있지만, 특정 개발 상황에서는 PHP의 기능을 확장하거나 외부 서비스를 연동하기 위해 추가 PHP 모듈을 직접 컴파일 및 설치해야 할 수 있습니다.
이 문서에서는 ServBay 환경에서 사용 중인 PHP 버전에 맞춰 커스텀 모듈을 컴파일하고 설치하는 완전한 절차를 안내합니다. 대표적으로 imagick
와 sqlsrv
(Microsoft SQL Server 드라이버) 모듈의 컴파일을 예로 들어 전체 과정을 상세히 설명하니, ServBay PHP 환경에 필요한 확장 기능을 원활히 추가하실 수 있습니다.
전제 조건
중요 안내
PHP 모듈 컴파일에 착수하기 전에, 가장 중요한 단계는 ServBay 공식 문서의 지침에 따라 컴파일 환경 초기화와 관련 시스템 환경변수를 정확하게 설정하는 것입니다. 이는 ServBay의 모든 패키지(즉, PHP 모듈 포함)의 정상적인 빌드를 위한 필수 조건입니다. 만약 해당 단계를 누락하거나 올바르게 실행하지 않으면, 이후 컴파일 과정에서 명령어, 라이브러리, 헤더 파일 미찾음과 같은 치명적인 오류가 발생할 확률이 매우 높습니다.
ServBay의 컴파일 환경 초기화 스크립트는 필수 환경변수들을 세팅합니다. 예를 들면, PATH
(ServBay 빌드 도구 경로), SERVBAY_PACKAGE_FULL_PATH
(ServBay 패키지 루트 디렉토리 경로), CPU_NUMBER
(멀티코어 빌드를 위한 병렬 처리 개수) 등이 포함됩니다. 이 변수들은 이후 빌드 명령에 핵심적으로 활용됩니다.
ServBay 컴파일 환경 초기화 방법에 대한 자세한 절차는 반드시 해당 공식 문서 ServBay로 이차 컴파일하기 를 참고하세요. 매뉴얼을 완전히 이해하고, 모든 지시사항을 정확히 따라 환경을 설정했는지 확인 후 진행하시기 바랍니다.
모듈 컴파일을 시작하기 전에, 반드시 위의 ServBay 컴파일 환경 초기화 절차를 완료했고, 현재 터미널 세션에 관련 변수들이 올바르게 설정되어 있는지 재차 확인해 주세요.
PHP 버전 지정의 중요성
ServBay의 핵심 기능 중 하나는 하나의 시스템 내에서 여러 PHP 버전을 설치, 실행할 수 있게 해주는 것입니다. 이러한 유연성 덕분에 개발자는 다양한 프로젝트 환경에 맞게 PHP를 자유롭게 사용할 수 있습니다. 하지만, PHP 모듈을 컴파일할 때는 반드시 특정 PHP 버전 기준으로 빌드를 진행해야 합니다. 이때 환경 준비와 버전별 설정 정보를 얻는 주요 도구는 phpize
와 php-config
인데, 각각 사용 대상 PHP 버전과 정확히 일치해야 합니다.
phpize
: PHP 확장 모듈 컴파일 환경을 준비하는 스크립트.config.m4
파일을 읽어 표준configure
스크립트를 생성하며, C/C++ 소프트웨어 컴파일의 일반적인 첫 과정입니다.php-config
: 해당 PHP 버전의 빌드 정보(컴파일러 플래그, include 디렉토리, 라이브러리 디렉토리, 모듈 설치 경로 등)를 제공합니다.configure
스크립트가 이 정보를 참고하여, 정확히 목표 버전에 맞춰 모듈이 빌드되도록 지원합니다.
따라서 phpize
, php-config
, 그리고 그 밖의 PHP 빌드 관련 명령을 사용할 때는, 반드시 풀 경로를 통해 원하는 ServBay 내 PHP 버전을 명확하게 지정해야 합니다. 예를 들어, ServBay에 설치된 PHP 8.3용 모듈을 컴파일하려면, /Applications/ServBay/package/php/8.3/current/bin/phpize
및 /Applications/ServBay/package/php/8.3/current/bin/php-config
경로를 사용해야만 빌드 후 호환성 및 오류(예: symbol not found 등)가 발생하지 않습니다.
이 안내서는 PHP 8.3 버전을 예시로 설명합니다. 실제 빌드시에는, 본인의 상황에 맞는 ServBay 내 실제 설치된 PHP 버전 경로로 모두 교체해야 합니다.
PHP imagick 모듈 컴파일하기
imagick
모듈은 PHP에서 폭넓게 사용되는 이미지 처리 확장입니다. 강력한 ImageMagick 명령행 라이브러리에 기반하여, 이미지 리사이즈, 자르기, 포맷 변환, 워터마크 추가, 이미지 합성 등 다양한 고급 작업을 PHP 코드에서 간단히 구현할 수 있습니다. 아래는 ServBay 환경, 특히 원하는 PHP 버전에 맞춰 imagick
모듈을 컴파일 및 설치하는 단계별 가이드입니다.
1단계: ImageMagick 의존 라이브러리 설치
imagick
PHP 모듈은 시스템에 ImageMagick 라이브러리와 개발용 헤더가 설치되어 있어야 합니다. macOS에서는 Homebrew 패키지 매니저를 사용하는 것이 가장 쉽습니다. Homebrew 미설치 시, 공식 사이트를 참고해 주세요.
터미널에서 아래 명령어로 ImageMagick을 설치합니다.
bash
brew install imagemagick
1
2단계: imagick 모듈 소스 코드 다운로드
다음으로, PHP 확장 라이브러리(PECL) 공식 웹사이트에서 imagick
모듈의 소스 패키지를 다운로드해야 합니다. PECL imagick 페이지에서 원하는 버전(일반적으로 최신 안정판)을 찾고, 다운로드 링크를 확인하세요. 예시로 3.7.0 버전을 다운로드합니다.
bash
wget https://pecl.php.net/get/imagick-3.7.0.tgz
1
3단계: 소스 압축 해제 및 디렉토리 이동
다운로드가 완료되면, tar
명령어로 압축을 해제하고 해당 디렉토리로 이동합니다.
bash
tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0
1
2
2
4단계: 컴파일 환경 준비 (phpize 사용)
모듈 소스 디렉토리에서, 반드시 목표 PHP 버전의 phpize
실행파일 전체 경로를 사용해 빌드 환경을 준비해야 합니다. 예시는 PHP 8.3 기준이며, SERVBAY_PACKAGE_FULL_PATH
변수는 ServBay 패키지 루트 경로여야 합니다.
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize
1
phpize
가 제대로 실행되면, config.m4
파일을 확인하고, 빌드 준비에 필요한 configure
스크립트 등이 생성됩니다. 터미널에 빌드 환경이 준비되었다는 메시지가 출력됩니다.
5단계: 빌드 옵션 설정
생성된 configure
스크립트를 실행해 빌드 옵션을 설정합니다. 이때 --with-php-config
플래그로 반드시 목표 PHP 버전의 php-config
경로를 지정해야만, 올바른 빌드 정보가 적용됩니다.
bash
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config
1
configure
는 ImageMagick 라이브러리 및 헤더 존재 여부 검사, PHP 빌드 정보 수집을 거쳐 Makefile
을 생성합니다. 에러가 나는 경우는 주로 의존 라이브러리 미설치 또는 경로 오입력입니다.
6단계: 모듈 컴파일 및 설치
Makefile
이 생성되면, 아래 명령어로 본격적으로 모듈을 컴파일 및 설치합니다. ${CPU_NUMBER}
변수(ServBay 환경 초기화 시 설정됨)는 병렬 빌드 처리 개수로, 빌드 속도를 높입니다.
bash
make -j ${CPU_NUMBER}
make install
1
2
2
make install
을 실행하면, 빌드된 imagick.so
파일이 ServBay의 해당 PHP 버전 확장 모듈 디렉토리(예: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
등)로 자동 복사됩니다.
7단계: 모듈 활성화
설치가 완료되었으면, 해당 PHP 버전 설정 파일에서 모듈을 활성화해야 합니다. ServBay에서는 GUI(그래픽 인터페이스)로 쉽게 설정할 수 있습니다.
- ServBay 프로그램 실행
- 왼쪽 메뉴에서
언어
-PHP
-PHP 8.3
선택 - 우측에서
PHP
탭 클릭 후, 스크롤 맨 하단 “추가 파라미터” 항목에extension=imagick.so
입력 저장
클릭 시 PHP 프로세스가 자동 재시작되며, 새 모듈을 불러옵니다
8단계: 모듈 로드 확인
모듈 활성화 후, ServBay의 PHP 패키지를 반드시 재시작해야 변경된 설정이 반영됩니다. ServBay 관리 패널의 해당 PHP 버전 옆 재시작 버튼을 누르거나, ServBay의 명령라인 도구를 사용할 수도 있습니다(자세한 명령어는 ServBay 문서 참고).
PHP를 재시작했다면, CLI에서 아래와 같이 imagick
로드 확인이 가능합니다.
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick
1
이때 $SERVBAY_PACKAGE_FULL_PATH/php/8.3/current/bin/php
명령어를 반드시 사용해야 ServBay 내 해당 PHP 버전으로 확인할 수 있습니다. -m
플래그는 로드된 모든 PHP 모듈을 출력합니다. 정상 설치라면 결과에 imagick
이 표시됩니다.
더욱 정밀한 확인을 위해, 웹 루트(기본: /Applications/ServBay/www
)에 info.php
예제 파일(내부: <?php phpinfo(); ?>
)을 생성하여, 브라우저에서 http://localhost/info.php
또는 ServBay에 설정한 도메인으로 접속해 phpinfo()
결과에서 “imagick” 항목이 활성화되어 있는지 직접 체크할 수 있습니다.
PHP sqlsrv/pdo_sqlsrv 모듈 컴파일하기
sqlsrv
및 pdo_sqlsrv
모듈은 PHP에서 Microsoft SQL Server 데이터베이스 연결·조작을 위해 공식적으로 제공되는 확장입니다. 이는 Microsoft의 ODBC 드라이버에 기반합니다. ServBay PHP 환경에서 SQL Server에 접속하려면 반드시 해당 모듈 컴파일 및 설치가 필요합니다. 아래는 sqlsrv/pdo_sqlsrv 빌드 절차 안내입니다.
참고: 필수 선행 설치
macOS 환경에서 sqlsrv
모듈을 컴파일하려면, 반드시 먼저 Microsoft의 SQL Server ODBC 드라이버(msodbcsql18
)와 관련 명령줄 도구(mssql-tools18
)를 깔아야 합니다. 이는 ServBay에 내장되어 있지 않으므로 직접 설치가 필요합니다.
Homebrew 패키지 매니저를 이용한 설치를 권장합니다. Homebrew 미설치 시 공식 사이트 참고 바랍니다.
아래는 Microsoft ODBC 드라이버 및 도구 설치용 Homebrew 명령어입니다. 라이선스 동의가 필요할 경우, 환경변수 HOMEBREW_ACCEPT_EULA=Y
를 함께 지정하세요.
bash
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18
1
2
3
2
3
sqlsrv
모듈을 컴파일하기 전에 이 의존 패키지들이 정상적으로 설치되었는지, 설치 디렉토리가 /opt/homebrew/
(Apple Silicon Mac) 혹은 /usr/local/
(Intel Mac) 등으로 올바른지 반드시 확인해야 합니다.
안내
sqlsrv
와 pdo_sqlsrv
는 별도의 모듈로서 각각 따로 빌드해야 하지만, 절차는 매우 유사합니다. 아래 예시는 sqlsrv
기준입니다.
1단계: Microsoft ODBC 드라이버 및 도구 설치
(위의 선행 안내문에 따라, 반드시 msodbcsql18
과 mssql-tools18
을 Homebrew로 설치했는지 확인 바랍니다)
2단계: sqlsrv 모듈 소스 코드 다운로드
PECL 공식 웹사이트에서 sqlsrv
및 pdo_sqlsrv
모듈의 소스 패키지를 최신 또는 원하는 버전으로 다운로드합니다. (예시: v5.12.0)
bash
wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz # pdo_sqlsrv
1
2
2
3단계: 소스 압축 해제 및 디렉토리 이동
아래 순서로 압축을 해제하고 모듈 소스 디렉토리로 이동합니다.
bash
tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0
# pdo_sqlsrv도 동일하며, 이 예시는 sqlsrv 기준입니다.
1
2
3
4
2
3
4
4단계: 컴파일 환경 준비 (phpize 사용)
소스 디렉토리에서, 목표 PHP 버전의 phpize
(전체 경로와 환경변수 포함)를 사용해 빌드 환경을 준비합니다.
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize
1
5단계: 빌드 옵션 설정 (의존 경로 포함)
sqlsrv
는 Homebrew로 설치한 Microsoft ODBC 드라이버 및 unixODBC 라이브러리에 의존하므로, ./configure
실행 전 반드시 환경변수 LDFLAGS
, CPPFLAGS
에 라이브러리 및 헤더 경로를 추가해야 합니다. 플래그에는 사용 중인 Homebrew 경로(예: Apple Silicon Mac → /opt/homebrew
, Intel Mac → /usr/local
)를 맞춰서 입력하세요. 예시는 /opt/homebrew
기준입니다.
bash
export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}"
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config
1
2
3
2
3
LDFLAGS
: 링커가 라이브러리 파일을 탐색할 경로 지정(-L/opt/homebrew/lib
)CPPFLAGS
: 헤더 파일 탐색 경로 지정(-I/opt/homebrew/opt/unixodbc/include
, 필요 시-I/opt/homebrew/include
추가)${CPPFLAGS}
,${LDFLAGS}
는 ServBay 환경 변수의 기존 값이 있을 경우를 고려한 유지용
6단계: 모듈 컴파일 및 설치
설정이 끝나고 Makefile
이 생성되면, 아래와 같이 컴파일 및 설치를 진행합니다.
bash
make -j ${CPU_NUMBER}
make install
1
2
2
make install
이 완료되면, 빌드된 sqlsrv.so
및 pdo_sqlsrv.so
가 ServBay 내 해당 PHP 버전 확장 모듈 디렉토리에 복사됩니다.
7단계: 모듈 활성화
모듈 설치가 끝났으면, ServBay의 GUI에서 설정을 적용합니다.
- ServBay 실행
- 왼쪽 메뉴에서
언어
-PHP
-PHP 8.3
선택 - 우측
PHP
탭으로 이동, 스크롤 하단 “추가 파라미터”에extension=sqlsrv.so
및extension=pdo_sqlsrv.so
등록 저장
버튼 클릭 후, PHP 프로세스가 자동 재시작되며, 새 확장 모듈이 적용됩니다
8단계: 모듈 로드 확인
모듈 활성화 후, 반드시 ServBay PHP 패키지를 재시작해야 합니다.
이후 아래처럼 CLI 명령어로 sqlsrv
및 pdo_sqlsrv
모듈이 정상 로드되는지 확인 가능합니다.
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv
1
2
2
모듈이 정상적으로 인식되었다면 출력 결과에 각각 모듈명이 나타납니다. 추가적으로 phpinfo()
를 통한 상세 정보 확인도 가능합니다.
자주 묻는 질문 (FAQ)
- Q: "Cannot find autoconf" 또는 유사한 에러가 컴파일 시 발생합니다.
- A: 이는 거의 대부분 ServBay 컴파일 환경 설정이 미완료이거나 잘못 초기화된 경우입니다. 반드시 본 문서 상단 “전제 조건” 및 ServBay로 이차 컴파일하기 안내서를 확인하여, 빌드 도구(autoconf, automake, libtool 등) 설치 및 환경변수 세팅이 정상적으로 되었는지 점검하세요. 대체로 컴파일 환경 스크립트 실행 후 터미널 재시작으로 해결합니다.
- Q:
configure
실행 중 라이브러리나 헤더 파일을 찾지 못한다고 나옵니다.- A: 이는 필수 시스템 라이브러리 or 헤더 파일 미설치 또는 경로 인식 실패에 기인합니다.
imagick
의 경우, 반드시 ImageMagick 개발 라이브러리가 설치되어야 하며, Homebrew로brew install imagemagick
명령을 써 설치하세요.sqlsrv
라면, 반드시 Homebrew로 Microsoft ODBC 드라이버(msodbcsql18
)와mssql-tools18
가 선행 설치되어야 하며,./configure
전 환경변수LDFLAGS
,CPPFLAGS
에 Homebrew 관련 경로를 정확히 입력했는지 확인하세요(예: /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).- ServBay 컴파일 환경의 PATH에 Homebrew 경로가 포함되어 있는지, 필요시 Homebrew bin 디렉토리를 추가했는지도 점검하시기 바랍니다.
- A: 이는 필수 시스템 라이브러리 or 헤더 파일 미설치 또는 경로 인식 실패에 기인합니다.
- Q:
make
또는make install
에서 빌드가 실패합니다.- A: 실패 원인은 다양합니다.
- 컴파일 의존성 부족: 에러 메시지로 어떤 파일/라이브러리가 부족한지 파악 후, 적절한 의존 패키지를 설치하세요.
- 설정 오류:
configure
단계의 옵션(특히--with-php-config
경로)이 올바른지 재차 확인하세요. - 권한 문제:
make install
이 ServBay 설치 디렉토리에 쓰기 작업을 하므로, 권한 미설정 시 해당 에러가 발생할 수 있습니다. 이 경우, 위험성 인지 하에sudo make install
로 시도 가능합니다. - 소스 손상: 다운로드한 모듈 소스에 문제가 없는지 점검하세요.
- A: 실패 원인은 다양합니다.
- Q:
.so
모듈 파일이 확장 디렉토리에 정상 설치됐고,.ini
에도 추가했지만,php -m
이나phpinfo()
에는 나오지 않습니다.- A:
- 가장 흔한 원인: ServBay PHP 패키지의 재시작을 하지 않은 경우입니다.
.ini
파일 수정 후, 반드시 ServBay 관리자에서 해당 PHP 버전을 완전히 재시작해야 하며, 웹서버만 재시작(혹은 단순 새로고침)하는 것은 불충분합니다. .ini
파일 문법 오류: 작성한.ini
파일 문법 및 철자 확인(extension=모듈명.so)- 확장 디렉토리 설정 오류:
php.ini
의extension_dir
이 실제 ServBay PHP 확장 경로와 일치하는지,php-config --extension-dir
명령어로 확인 가능합니다. - 빌드 호환성/파일 손상: 모듈을 다시 빌드해보고, 소스 버전과 PHP 버전 호환 여부를 체크하세요. 또한 ServBay 로그 폴더 내 로그에서 해당 모듈 로딩 실패 원인을 참조할 수 있습니다.
- 가장 흔한 원인: ServBay PHP 패키지의 재시작을 하지 않은 경우입니다.
- A:
요약
이 단계별 안내를 따르면, ServBay macOS 로컬 개발 환경에서 imagick
, sqlsrv
등 커스텀 PHP 모듈을 직접 컴파일하여 정상적으로 설치할 수 있습니다. 전체 과정에서 핵심적으로 유의할 점은 다음과 같습니다.
- ServBay 컴파일 환경을 정확하고 완벽하게 초기화: 모든 빌드 작업은 완료된 환경 세팅이 전제입니다.
- 목표 PHP 버전 경로의 명확한 지정 및 활용:
phpize
,php-config
실행 시 반드시 전체 경로로 지정하고, 타 버전 혼동을 방지하세요. - 모듈별 외부 의존성 해결: ImageMagick, Microsoft ODBC 드라이버 등 모듈이 필요로 하는 시스템 라이브러리 및 도구를 사전에 설치하고,
./configure
단계의 환경변수(LDFLAGS, CPPFLAGS) 및 옵션에 올바른 경로를 입력해 모든 의존성이 충족되게 하세요. - 정확한 모듈 활성화: 목표 PHP의
conf.d
폴더에.ini
파일을 신설하거나 수정해extension=모듈명.so
로 등록하세요. - ServBay PHP 패키지의 재시작: 신규 모듈 적용/설정을 활성화하려면, 반드시 ServBay 내 PHP 패키지 자체를 재시작해야 합니다.
ServBay는 폭넓고 유연한 환경으로 여러분의 다양한 개발 니즈를 지원합니다. 이 문서에 언급된 PHP 모듈 컴파일, 직접 설치뿐만 아니라, MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust 등 다양한 기술 생태계를 완벽 지원합니다. 그뿐 아니라, ACME 인증을 통한 실 SSL 인증서 발급, 쉬운 CORS 설정, 사이트·DB·SSL 인증서 자동 백업, DB root 비밀번호 재설정, 로컬 HTTPS 개발을 위한 ServBay User CA/Public CA 제공 등 효율적이고 강력한 개발 워크플로우를 위한 다양한 부가 기능도 제공합니다.
이 가이드가 ServBay PHP 환경에 필요한 기능 추가 및 보다 효율적인 웹 개발 작업에 도움이 되길 바랍니다. 추가적인 문제 상황에 부딪힌다면, ServBay 공식 문서 또는 커뮤니티 지원 자료를 적극 참고하시기 바랍니다.