ServBay에서 커스텀 PHP 모듈 컴파일 및 설치하기
ServBay는 macOS와 Windows 모두에서 사용할 수 있는 강력한 로컬 웹 개발 환경으로, 현대 웹 개발자들의 요구를 만족시키기 위해 다양한 소프트웨어 패키지를 통합합니다. PHP, Node.js, Python, Go, Java, 데이터베이스(MySQL, PostgreSQL, MongoDB), 캐시(Redis), 웹 서버(Caddy, Nginx, Apache) 등 광범위한 기술 스택을 기본 내장하고 있습니다. 각 소프트웨어 패키지별로 여러 버전 지원이 가능하여, 프로젝트에 맞는 환경을 유연하게 전환할 수 있습니다.
이미 ServBay에는 많은 일반적인 PHP 모듈이 내장되어 있지만, 특정 개발 환경에서는 PHP의 기능을 확장하거나 특수한 서드파티 서비스를 연동하기 위해 추가 PHP 모듈을 직접 컴파일 후 설치해야 할 수도 있습니다.
이 문서는 ServBay 환경에서 원하는 PHP 버전을 대상으로 커스텀 모듈을 컴파일하고 설치하는 방법을 단계별로 안내합니다. 여기서는 이미지 처리 모듈인 imagick
과 Microsoft SQL Server용 드라이버 모듈인 sqlsrv
를 예시로 들어 전체 과정을 자세히 설명하여, 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
스크립트를 생성합니다.php-config
: 선택한 PHP 버전 설치 정보(컴파일러 플래그, 헤더/라이브러리/확장 디렉터리 등)를 제공합니다.configure
스크립트는 이 정보를 바탕으로 모듈이 올바르게 빌드·링크되도록 지원합니다.
따라서, phpize
, php-config
및 기타 PHP 빌드 관련 명령을 쓸 때는 절대 경로로 반드시 원하는 PHP 버전을 지정해야 합니다.
경로 예제
예를 들어, ServBay에서 PHP 8.3 버전에 맞춰 모듈을 컴파일하려면:
macOS:
phpize
:/Applications/ServBay/package/php/8.3/current/bin/phpize
php-config
:/Applications/ServBay/package/php/8.3/current/bin/php-config
Windows:
phpize
:C:\ServBay\package\php\8.3\current\bin\phpize
php-config
:C:\ServBay\package\php\8.3\current\bin\php-config
올바른 버전을 선택하면 컴파일된 모듈이 목표 PHP 환경에 호환되어, 빌드 에러나 실행 오류(예: 심볼을 찾을 수 없음)를 방지할 수 있습니다.
이 문서의 예시는 ServBay에 설치된 PHP 8.3 버전을 기준으로 설명합니다. 실제로는 본인의 ServBay에서 사용하려는 PHP 버전의 경로로 바꿔서 명령을 사용하세요.
PHP imagick 모듈 컴파일하기
imagick
은 PHP에서 매우 인기 있는 확장 모듈로, 강력한 ImageMagick 라이브러리를 기반으로 다양한 이미지 처리 기능을 제공합니다. imagick
을 이용하면 PHP 코드 내에서 이미지 크기 조정, 자르기, 포맷 변환, 워터마크, 합성 등 복잡한 이미지 작업을 손쉽게 구현할 수 있습니다. 아래는 ServBay 환경에서 특정 PHP 버전을 대상으로 imagick
모듈을 컴파일 및 설치하는 전체 과정입니다.
1단계: ImageMagick 의존 라이브러리 설치
imagick
PHP 모듈은 시스템에 ImageMagick 라이브러리가 설치되어 있어야 합니다.
macOS
Homebrew 패키지 관리자를 사용하는 것이 가장 편리합니다. Homebrew가 필요하다면 Homebrew 공식 웹사이트에서 안내를 참고하세요.
터미널에서 아래 명령으로 ImageMagick과 개발용 라이브러리를 설치하세요:
bash
brew install imagemagick
1
Windows
Windows 사용자는 ImageMagick 공식 다운로드 페이지에서 직접 버전을 선택해 다운 받아 설치해야 합니다.
설치 시 개발용 라이브러리가 포함된 버전을 선택하고, 설치 경로를 시스템 환경 변수에 추가하면 됩니다.
2단계: imagick 모듈 소스코드 받기
PHP 확장 라이브러리(PECL)의 imagick 공식 페이지에서 원하는 버전(보통 최신 안정 버전)을 받아 다운로드 링크를 얻습니다. 다음은 작성 시점의 최신 버전 3.7.0
예시입니다.
bash
wget https://pecl.php.net/get/imagick-3.7.0.tgz
1
3단계: 소스 압축 해제 및 디렉토리 이동
다운로드 후, tar
명령으로 소스코드를 풀고, cd
로 해당 디렉터리로 이동합니다.
bash
tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0
1
2
2
4단계: 컴파일 환경 준비(phpize 사용)
소스 디렉터리에서 원하는 PHP 버전의 phpize
툴로 컴파일 환경을 준비하세요. 반드시 목표 PHP 버전의 절대경로를 사용해야 합니다. 예를 들어, PHP 8.3을 사용하고 환경변수 SERVBAY_PACKAGE_FULL_PATH
가 올바르게 설정되었다면:
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단계: 모듈 컴파일 및 설치
설정이 끝나면 make
로 컴파일하고, make install
로 완성된 모듈 파일을 PHP 확장 디렉터리에 설치합니다. ${CPU_NUMBER}
는 ServBay 컴파일 환경에서 설정된 병렬 작업 프로세스 수로, 빌드 속도를 높여줍니다.
bash
make -j ${CPU_NUMBER}
make install
1
2
2
make install
명령은 php-config
정보를 참고해 적절한 ServBay PHP 확장 설치 경로로 파일을 복사합니다.
- macOS:
/Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
- Windows:
C:\ServBay\package\php\8.3\current\lib\php\extensions\no-debug-non-zts-YYYYMMDD\
실제 경로는 PHP 버전과 빌드 옵션에 따라 다릅니다.
7단계: 모듈 활성화
설치가 끝난 뒤, PHP 설정 파일에 모듈을 등록해야 합니다. ServBay는 GUI에서 이 과정을 지원합니다.
- ServBay 프로그램 실행
- 좌측 메뉴에서
언어
-PHP
-PHP 8.3
선택 - 우측의 PHP 탭에서 아래로 스크롤해 "추가 파라미터" 항목에
extension=imagick.so
입력 저장
클릭 시, PHP 프로세스가 자동으로 재시작 및 모듈을 로드함
8단계: 모듈 로드 확인
모듈 설정 후 반드시 ServBay 내 PHP 패키지를 재시작해야 새 설정이 적용됩니다. ServBay 관리 패널에서 해당 PHP 소프트웨어 패키지의 재시작 버튼을 누르거나, ServBay 명령줄 도구로 재시작하세요(명령은 공식 문서 참고).
PHP 재시작 후, 커맨드라인에서 imagick
모듈이 정상 로드됐는지 다음 명령으로 확인하세요:
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick
1
이 명령은 ServBay 내 해당 PHP의 실행 파일을 대상으로 하며, -m
옵션으로 로딩된 모든 모듈을 표시합니다. 출력 결과에 imagick
이 있으면 정상입니다.
좀 더 자세하게 확인하려면 웹 루트 디렉터리(기본값 아래 참고)에 info.php
파일을 만들어 <?php phpinfo(); ?>
코드를 넣고,
- macOS:
/Applications/ServBay/www
- Windows:
C:\ServBay\www
브라우저로 http://localhost/info.php
또는 서빙 중인 ServBay 도메인에서 접속하세요. phpinfo()
페이지에서 "imagick"을 검색하면 활성 여부와 세부 정보를 확인할 수 있습니다.
PHP sqlsrv/pdo_sqlsrv 모듈 컴파일하기
sqlsrv
와 pdo_sqlsrv
는 PHP 확장 공식 모듈로, Microsoft SQL Server 데이터베이스 연동에 사용됩니다. Microsoft가 제공하는 ODBC 드라이버에 기반하며, ServBay 내 PHP 환경에서 SQL Server에 접속해야 할 때 반드시 설치합니다. 아래는 ServBay 환경에서 이 모듈들을 컴파일/설치하는 과정입니다.
참고: 필수 사전 작업
sqlsrv
모듈 빌드 전, 반드시 Microsoft의 SQL Server ODBC 드라이버 및 관련 툴을 먼저 설치해야 합니다. 이 소프트웨어는 ServBay에 포함되어 있지 않으므로 직접 설치해야 합니다.
macOS
Homebrew로 설치 가능하며, Homebrew가 없다면 공식 홈페이지 참고하세요.
아래 Homebrew 커맨드로 Microsoft ODBC 드라이버 및 관련 툴을 설치합니다(라이선스 동의를 위해 환경변수 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
대부분 /opt/homebrew/(Apple Silicon) 또는 /usr/local/(Intel Mac)에 설치됩니다. 반드시 컴파일 시 이 경로를 참조해야 합니다.
Windows
Windows 사용자는 Microsoft 공식 ODBC Driver for SQL Server에서 본인 시스템에 맞는 버전을 다운로드/설치해야 합니다.
설치가 끝나면 시스템에서 드라이버가 제대로 인식되는지 확인하세요.
sqlsrv
모듈 컴파일 전, 해당 의존 패키지가 반드시 준비되어 있어야 합니다.
안내
sqlsrv
와 pdo_sqlsrv
는 별도의 두 모듈이며, 각각 따로 컴파일해야 하지만 과정은 거의 동일하니 아래는 sqlsrv
예시로 설명합니다.
1단계: Microsoft ODBC 드라이버 및 툴 설치
(위에서 이미 안내한 내용이므로, Homebrew 등으로 msodbcsql18
, mssql-tools18
설치가 필요합니다.)
2단계: sqlsrv 모듈 소스코드 받기
PECL 공식 sqlsrv 페이지에서 최신 또는 필요한 버전의 다운로드 링크를 받아 소스 파일을 받습니다. 아래는 최신 버전 5.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
로 헤더/라이브러리 탐색 경로를 명확히 지정해야 합니다. 또한 --with-php-config
로 PHP 설정 경로 지정이 필요합니다.
사용 중인 Homebrew 경로(일반적으로 Intel Mac은 /usr/local
, Apple Silicon은 /opt/homebrew
)에 따라 아래 명령의 경로를 조정하세요. Apple Silicon 기준 예시입니다.
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
: C/C++ 헤더 탐색 경로(예:-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단계: 모듈 활성화
설치 후, 해당 PHP 버전 설정 파일에 모듈을 등록해야 합니다. ServBay에서는 GUI로 쉽게 활성화할 수 있습니다.
- ServBay 프로그램 실행
- 좌측 언어 > PHP > PHP 8.3
- 오른쪽 PHP 탭 하단 "추가 파라미터"에
extension=sqlsrv.so
및extension=pdo_sqlsrv.so
입력 저장
클릭 시 PHP가 자동으로 재시작하며 모듈을 읽음
8단계: 모듈 로드 확인
모듈 활성화 후 반드시 재시작해야 합니다.
재기동 후, 커맨드라인에서 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 컴파일 환경이 올바르게 초기화되지 않은 것이 거의 확실합니다. 문서 앞 "사전 준비사항"을 다시 보고 패키지 재컴파일 문서를 참고해 환경 설정 절차를 제대로 완료해야 합니다. autoconf, automake, libtool 등 빌드 툴이 설치되어 있고 환경 변수에도 반영되어야 합니다. 컴파일 환경 초기화 스크립트 실행 및 셸 재시작으로 대부분 해결됩니다.
- Q:
configure
스크립트 실행 시 라이브러리나 헤더 파일을 찾을 수 없다고 나옵니까?- A: 해당 확장에 필요한 시스템 라이브러리나 헤더 파일이 설치되지 않았거나, 경로가 잘못되었을 경우입니다.
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 컴파일 환경 변수에 Homebrew 경로가 포함되어 있는지 확인, 필요시 Homebrew bin 경로를
PATH
에 추가
- A: 해당 확장에 필요한 시스템 라이브러리나 헤더 파일이 설치되지 않았거나, 경로가 잘못되었을 경우입니다.
- Q:
make
,make install
이 실패합니까?- A: 다양한 원인이 있을 수 있습니다:
- 컴파일 의존성 부족: 에러 메시지에서 어떤 파일이나 라이브러리가 부족한지 확인하고 필요한 의존성 설치
- 설정 오류:
configure
단계에서 옵션(특히--with-php-config
경로)이 정확한지 체크 - 권한 문제:
make install
은 ServBay 설치 디렉토리의 PHP 확장 폴더에 파일을 복사합니다. 권한 혹은 경로 문제가 있다면sudo make install
을 시도할 수도 있으나, 위험 요소를 인지하고 사용할 것 - 소스 코드 내용 문제: 다운로드한 소스 패키지의 손상 여부 점검
- A: 다양한 원인이 있을 수 있습니다:
- Q:
.so
모듈 파일은 확장 디렉터리에 설치됐고,.ini
파일에도 등록했지만php -m
또는phpinfo()
에서 모듈이 안 보입니까?- A:
- 가장 흔한 원인: ServBay 내 PHP 소프트웨어 패키지를 재시작하지 않음.
.ini
파일 수정 시 반드시 ServBay 관리 패널 또는 CLI 툴로 해당 PHP 버전을 완전히 재기동해야 하며, 단순 웹서버 재시작은 불충분. .ini
문법 오류: 직접 작성한.ini
파일의 문법이나 오타 검토(extension=modulename.so
)- 확장 디렉터리 경로 오류:
php.ini
내extension_dir
이 ServBay PHP 확장 디렉터리를 올바르게 가리키는지 확인, 또는php-config --extension-dir
로 경로 재확인 - 모듈 파일 손상이나 PHP 버전 미호환: 다시 컴파일하며 과정 오류 없음 확인. 소스 버전이 PHP와 근본적으로 호환되는지 체크. ServBay 로그(설치 경로 logs 폴더)를 확인하여 모듈 로드 에러 기록 유무 점검
- 가장 흔한 원인: ServBay 내 PHP 소프트웨어 패키지를 재시작하지 않음.
- A:
요약
이 문서의 단계별 안내에 따라 ServBay 로컬 개발 환경에서 imagick
, sqlsrv
등 커스텀 PHP 모듈을 성공적으로 컴파일/설치할 수 있습니다. 전체 과정의 관건은 다음과 같습니다:
- ServBay 컴파일 환경 철저히 초기화: 이후 모든 컴파일 과정의 원활한 진행에 반드시 필요
- 정확한 PHP 버전 경로 지정:
phpize
와php-config
사용 시, 명령어를 해당 PHP 버전의 절대 경로로 지정해야 함 - 외부 의존성 설치 및 경로 지정: 각 모듈이 요구하는 시스템 라이브러리와 툴(예: ImageMagick, Microsoft ODBC 드라이버 등)을 설치하고,
./configure
단계에서 환경변수(LDFLAGS
,CPPFLAGS
) 및 각종 설정으로 경로를 알려줘야 함 - 모듈 올바르게 활성화: 목표 PHP 버전의
conf.d
폴더에서.ini
파일 생성 또는 편집,extension=modulename.so
문법으로 모듈 등록 - 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 인증서 포함), 데이터베이스 root 비밀번호 초기화, ServBay User CA 및 Public CA 통한 로컬 HTTPS 개발 등, 효율적이고 강력한 개발 워크플로우 구현을 위한 다양한 기능을 지원합니다.
이 안내서가 ServBay의 PHP 환경에 필요한 기능을 원활하게 추가하고, 더 효율적인 웹 개발에 도움이 되길 바랍니다. 추가로 문제가 발생하면 ServBay 공식 문서 및 커뮤니티 지원을 참고하세요.