ServBay에서 서드파티 PHP 확장 모듈 로드 방법

ServBay는 강력한 로컬 웹 개발 환경으로, 다양한 PHP 확장 모듈을 기본으로 제공합니다. 일반적으로 사용자는 ServBay의 패키지(Packages) -> 언어(Languages) -> PHP 버전 -> 확장 메뉴에서 손쉽게 확장 모듈을 설치 및 활성화할 수 있습니다.

하지만, 개발자는 때때로 ServBay에 기본 포함되어 있지 않은 서드파티 또는 직접 빌드한 PHP 확장 모듈을 로드해야 할 때가 있습니다. 본 문서에서는 ionCube Loader를 예시로 하여 ServBay에서 특정 PHP 버전에 이러한 확장 모듈을 설치하는 상세 과정을 안내합니다. 이 절차는 기타 Zend 확장 및 직접 빌드한 .so 확장 파일에도 동일하게 적용할 수 있습니다.

Zend 확장에 대한 특별 안내: ionCube Loader는 Zend 확장으로, 일반 확장보다 PHP의 Zend 엔진과 더 깊이 상호작용합니다. 따라서 구성 시에는 반드시 zend_extension 지시어를 사용해야 하며, 일반 확장에 사용하는 extension 지시어와는 다름을 유의해야 합니다.

사전 준비

macOS 시스템에 ServBay가 설치 및 실행 중이어야 합니다.
시스템 파일 및 ServBay 설정 화면에 접근할 수 있는 관리자 권한이 필요합니다.
macOS의 터미널(Terminal) 사용에 익숙해야 합니다.
로드하려는 서드파티 PHP 확장 파일(보통 .so)이 ServBay의 대상 PHP 버전 및 아키텍처(Intel 또는 Apple Silicon) 그리고 빌드 옵션(NTS/ZTS 등)과 완벽하게 호환되는지 확인해야 합니다.

주의: 아키텍처 호환성은 반드시 확인해야 합니다

ServBay는 Intel(x86_64) 및 Apple Silicon(ARM64, M1/M2/M3/M4 칩 등) 아키텍처용으로 각각 네이티브 PHP 패키지를 제공합니다. .so 확장 파일을 로드할 때, 해당 파일이 ServBay의 PHP 패키지 아키텍처와 반드시 일치해야 합니다.

아키텍처가 다르면 파일을 섞어 사용할 수 없으며, 일치하지 않으면 PHP가 실행되지 않거나 크래시가 발생합니다.

file 명령으로 실행 파일이나 .so 파일의 아키텍처를 확인할 수 있습니다:

ServBay가 제공하는 PHP 패키지의 아키텍처 확인(아래에서 8.3을 실제 사용하는 PHP 버전으로 교체):

bash

file /Applications/ServBay/package/php/8.3/current/bin/php

출력 예시:

/Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # Apple Silicon ARM64 아키텍처

또는

/Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Intel x86_64 아키텍처

다운로드 또는 빌드한 .so 확장 파일의 아키텍처 확인(아래에서 xdebug.so를 실제 파일명으로 교체):
bash
```
file xdebug.so
```
1
출력 예시:
```
xdebug.so: Mach-O 64-bit bundle arm64 # Apple Silicon ARM64 아키텍처
```
1
또는
```
xdebug.so: Mach-O 64-bit bundle x86_64 # Intel x86_64 아키텍처
```
1
1번과 2번의 아키텍처 정보가 반드시 일치해야 합니다.

설치 절차

1단계: 서드파티 확장 파일 다운로드 (ionCube Loader를 예로)

ionCube Loader 공식 다운로드 페이지로 이동해, macOS 아키텍처에 맞는 버전을 선택합니다. macOS ARM64(Apple Silicon M 시리즈 칩)의 경우 Darwin ARM64 버전을 다운로드하세요. 아래는 예시 링크(공식 사이트에서 최신 버전 여부를 꼭 확인할 것)입니다: https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
다운로드가 완료되면 ioncube_loaders_dar_arm64.tar.gz와 같이 .tar.gz 압축 파일이 생성됩니다.

2단계: 대상 PHP 버전 및 ServBay 확장 모듈 설치 디렉토리 확인

ServBay 앱을 실행합니다.
왼쪽 네비게이션 바에서 패키지(Packages) > **언어(Languages)**를 클릭합니다.
오른쪽 리스트에서 ionCube Loader를 설치하려는 PHP 버전(예시: PHP 8.3)을 찾고, 버전 번호를 기억해 둡니다.
해당 PHP 버전의 확장 설치 디렉토리(extension_dir)를 확인합니다. 이는 .so 파일을 저장하는 기본 위치입니다. ServBay의 PHP 확장 모듈은 보통 설치 경로, PHP 버전, 빌드 옵션마다 다르게 지정됩니다.
가장 확실한 방법은 터미널에서 명령으로 확인하는 것입니다.
터미널을 열고 아래 명령(실제 사용하는 PHP 버전의 경로로 교체)을 실행:
bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir
```
1
출력 예시:
```
extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831
```
1
여기서 표시된 경로를 반드시 메모해두세요. 다음 단계에서 필요합니다.

3단계: Loader 파일 압축 해제 및 배치

터미널을 실행합니다.
cd 명령으로 다운로드 폴더(일반적으로 ~/Downloads)로 이동합니다.
bash
```
cd ~/Downloads
```
1
다운받은 파일 압축 해제:
bash
```
tar -zxvf ioncube_loaders_dar_arm64.tar.gz
```
1
현재 경로에 ioncube라는 새 폴더가 생성됩니다.
ioncube 폴더로 이동:
bash
```
cd ioncube
```
1
폴더 내에 다양한 PHP 버전용 .so 파일(예: ioncube_loader_dar_8.3.so)이 있습니다. 대상 PHP 버전(2단계에서 확인한 버전)과 일치하는 파일을 찾으세요.
선택한 .so 파일을 2단계에서 확인한 PHP 확장 설치 디렉토리로 복사합니다. 예를 들어, 설치 경로가 /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/이고, PHP 8.3 Loader를 설치하려면:
bash
```
cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/
```
1
- 명령문의 대상 경로(/Applications/ServBay/.../no-debug-non-zts-20230831/)는 반드시 2단계에서 php -i로 얻은 실제 확장 설치 디렉토리로 교체해야 합니다.
- 대상 PHP 버전과 일치하는 .so 파일인지, PHP 패키지 아키텍처와 확장 파일 아키텍처가 동일한지 꼭 확인하세요(사전 준비 참고).

4단계: ServBay에서 PHP 확장 설정

다시 ServBay 앱으로 이동합니다.
왼쪽의 **언어(Languages)**에서 설정할 PHP 버전(예: PHP 8.3)을 클릭합니다.
오른쪽 설정 영역에서 PHP 탭을 여세요.
아래쪽에서 Additional Parameters(추가 매개변수) 텍스트박스를 찾습니다.
아래와 같이 Loader 파일명을 지정하는 구성 지시어를 한 줄 추가하세요:
ini
```
zend_extension = ioncube_loader_dar_8.3.so
```
1
- 중요: Loader 파일명인 ioncube_loader_dar_8.3.so는 실제 복사한 파일명으로 반드시 교체해야 합니다.
- ionCube Loader는 Zend 확장이므로 zend_extension을 사용합니다(일반 확장은 extension 사용).
- .so 파일을 이미 extension_dir에 복사했다면, 여기서는 파일명만 적으면 되며 경로는 필요 없습니다.
- 본 텍스트박스에 이미 다른 설정이 존재할 경우, 한 줄씩 추가로 입력하시면 됩니다.
(이미지는 예시이며, 실제 화면은 버전에 따라 다소 다를 수 있습니다)
우측 하단 Save(저장) 버튼을 눌러 적용하세요.

5단계: PHP 서비스 재시작

ServBay에서 Save 버튼을 클릭하면 ServBay가 자동으로 서비스(특히 PHP)를 감지해 부드럽게 재시작합니다. 따로 추가 재시작 작업은 필요하지 않습니다.

6단계: 로딩 성공 여부 확인

아래 두 가지 방법으로 ionCube Loader가 정상 로드됐는지 확인할 수 있습니다:

명령어로 확인:
- 터미널을 실행합니다.
- 아래 명령으로 로드된 PHP 모듈 리스트를 확인(대상 PHP 버전 경로로 교체):
  bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube
```
  1
  정상적으로 로드됐다면 ionCube Loader와 유사한 출력이 나타납니다.
- 또는 php -v로 PHP 버전 정보를 확인해도 됩니다. ionCube Loader가 정상 로드되면 Zend Engine 버전 정보 아래에 출력이 추가됩니다:
  bash
```
/Applications/ServBay/package/php/8.3/current/bin/php -v
```
  1
  정상 로드시 예시 출력(버전은 환경마다 다름):
```
PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.16, Copyright (c) Zend Technologies
    with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.
```
  1
  2
  3
  4
  with the ionCube PHP Loader ... 문구를 확인하세요.
phpinfo() 함수로 확인:
- 웹사이트 루트 디렉토리(예: /Applications/ServBay/www/servbay.demo/ 또는 설정된 사이트 폴더)에 새 PHP 파일(e.g., info.php)을 생성합니다.
- 파일에 아래 내용을 입력합니다:
  php
```
<?php
// phpinfo() 함수로 전체 PHP 정보 출력
phpinfo();
?>
```
  1
  2
  3
  4
- 브라우저로 해당 파일(예: http://servbay.demo/info.php, 실제 사이트 도메인으로 교체)을 엽니다.
- 열린 phpinfo() 페이지에서 "ionCube"를 검색(Cmd + F 또는 Ctrl + F)합니다. 정상적으로 로드됐다면 별도 정보 블록에 ionCube Loader 관련 상세 정보가 표시됩니다.

위의 방법으로 ionCube Loader 정보가 확인된다면 확장 모듈이 정상적으로 로드된 것입니다.

자주 묻는 질문과 문제 해결

PHP가 실행되지 않거나 크래시가 발생함: 가장 흔한 원인은 확장 파일의 아키텍처와 PHP 패키지 아키텍처가 일치하지 않을 때입니다. 반드시 사전 준비 단계 절차대로 아키텍처를 확인해야 합니다. 또한 PHP 버전/빌드 옵션(예: NTS/ZTS) 불일치도 원인이 될 수 있습니다.
extension_dir 경로가 잘못됨: .so 파일을 정확히 해당 PHP 버전의 실제 extension_dir에 복사했는지 확인하세요. php -i | grep extension_dir 명령으로 얻은 경로가 가장 신뢰할 수 있습니다.
설정 지시어 오타: ServBay 내 Additional Parameters에 입력한 확장 지시어가 올바른지 확인하세요. Zend 확장은 반드시 zend_extension = 파일명.so를, 일반 확장은 extension = 파일명.so를 사용합니다. 파일명은 대소문자까지 완전히 일치해야 합니다.
파일 권한 문제: ServBay를 실행하는 사용자가(.보통 macOS 자신의 계정) .so 파일 및 경로에 읽기 권한이 있는지 확인하세요. 일반적으로 복사 시 권한 문제가 없으나, 수동으로 권한을 변경한 경우는 반드시 체크해야 합니다.
ServBay가 재시작되지 않음: ServBay가 자동 재시작되지 않거나 설정이 적용되지 않으면, ServBay 앱 내에서 관련 서비스를 직접 재시작하거나 앱을 완전히 종료 후 다시 실행하세요.
phpinfo()에 정보가 없음: ServBay에서 관리하고, 이미 확장 설정을 적용한 PHP 버전의 phpinfo() 페이지를 반드시 열어야 합니다. 여러 PHP 버전 또는 사이트가 존재한다면 자신이 확인 중인 환경이 맞는지 확인하세요.

마무리

위의 단계들을 순차적으로 따라하면 ServBay에서 관리하는 원하는 PHP 버전에 ionCube Loader나 그 외 서드파티 .so 확장 모듈을 성공적으로 로드할 수 있습니다. 핵심은 대상 PHP 버전의 식별, *확장 설치 디렉토리(extension_dir)*의 정확한 확인, 호환되는 확장 파일 복사, 그리고 ServBay 설정 화면의 Additional Parameters에 zend_extension 또는 extension 지시어로 파일명을 지정하는 것입니다. 설치 과정에서 문제가 있다면 반드시 문제 해결 파트를 참고해 각 단계별로 꼼꼼히 점검하세요. 특히 아키텍처 호환성과 파일 경로를 재확인하시기 바랍니다.

ServBay에서 서드파티 PHP 확장 모듈 로드 방법 ​

사전 준비 ​

설치 절차 ​

1단계: 서드파티 확장 파일 다운로드 (ionCube Loader를 예로) ​

2단계: 대상 PHP 버전 및 ServBay 확장 모듈 설치 디렉토리 확인 ​

3단계: Loader 파일 압축 해제 및 배치 ​

4단계: ServBay에서 PHP 확장 설정 ​

5단계: PHP 서비스 재시작 ​

6단계: 로딩 성공 여부 확인 ​

자주 묻는 질문과 문제 해결 ​

마무리 ​