ServBay에서 MongoDB 사용하기 (PHP 확장 및 데이터베이스 서비스 연동)

ServBay는 개발자를 위해 설계된 강력한 로컬 웹 개발 환경으로, 다양한 웹 서버, 프로그래밍 언어, 데이터베이스를 통합 제공하며, 자주 사용하는 언어 확장과 도구들이 사전 설치되어 있습니다. PHP 개발자가 MongoDB 데이터베이스를 사용해야 할 때, ServBay를 이용하면 PHP의 MongoDB 확장 모듈을 쉽게 활성화하고 MongoDB 데이터베이스 서비스를 시작할 수 있습니다.

이 문서에서는 ServBay에서 PHP의 MongoDB 확장 모듈을 활성화하고 MongoDB 데이터베이스 서비스를 실행하는 방법, 그리고 PHP 프로젝트에서 MongoDB와 연결 및 사용 방법을 단계별로 안내합니다.

개요: ServBay와 MongoDB

MongoDB는 고성능의 오픈소스 문서 지향 NoSQL 데이터베이스로, 유연한 데이터 모델과 우수한 확장성 덕분에 현대 웹 애플리케이션에서 널리 사용됩니다.

ServBay는 MongoDB를 빌트인 소프트웨어 패키지 중 하나로 포함하여, 개발자가 로컬 환경에서 손쉽게 MongoDB 인스턴스를 배포하고 관리할 수 있도록 지원합니다. 또한 ServBay는 각 PHP 버전에 맞는 MongoDB 확장(mongodb.so)도 사전 컴파일 및 패키징해 제공하므로, PHP 애플리케이션이 MongoDB 데이터베이스와 원활히 연동할 수 있습니다.

PHP 프로젝트에서 MongoDB를 사용하려면 아래 두 가지 주요 단계를 거쳐야 합니다.

PHP의 MongoDB 확장 모듈 활성화: PHP 코드가 MongoDB 관련 함수를 호출할 수 있도록 지원합니다.
MongoDB 데이터베이스 서비스 실행: 실제 데이터 저장과 관리를 위한 MongoDB 인스턴스를 운영합니다.

ServBay의 그래픽 사용자 인터페이스(GUI)를 활용하면 이 두 단계 모두 매우 간편하게 실행할 수 있습니다.

PHP MongoDB 확장 버전

ServBay는 지원하는 여러 PHP 버전에 맞춰 해당 MongoDB 확장을 제공합니다. 적용되는 확장 버전은 ServBay 업데이트에 따라 달라질 수 있지만, 일반적으로 각 PHP 버전에 가장 안정적인 버전을 제공합니다. 아래는 ServBay에서 주로 제공하는 PHP별 MongoDB 확장 버전 예시입니다(실제 ServBay 버전에 따라 상이할 수 있음).

PHP 5.6, 7.0: MongoDB 1.7.5
PHP 7.1, 7.2, 7.3, 7.4: MongoDB 1.11.1
PHP 8.0, 8.1, 8.2, 8.3: MongoDB 1.15.0
PHP 8.4: MongoDB 1.19.1

참고: PHP 확장(mongodb.so)은 PHP가 MongoDB와 통신할 수 있게 해 주지만, 실제 PHP 코드에서 MongoDB와 상호작용하려면 공식 MongoDB PHP 드라이버가 필요합니다. 이 드라이버는 일반적으로 Composer를 통해 설치합니다.

PHP MongoDB 확장 활성화

환경의 경량화를 위해 ServBay의 일부 PHP 확장은 기본적으로 비활성화되어 있을 수 있습니다. MongoDB 확장 모듈을 활성화하는 가장 권장하는 방법은 ServBay의 GUI를 이용하는 것입니다.

ServBay GUI를 통한 활성화

가장 쉽고 빠른 방법입니다.

ServBay 앱을 실행합니다.
왼쪽 내비게이션에서 **언어(Languages)**를 클릭한 다음 PHP를 선택합니다.
MongoDB 확장을 활성화하려는 PHP 버전(예: PHP 8.4)을 선택합니다.
오른쪽 패널에서 확장(Extensions) 탭을 찾습니다.
아래로 스크롤하여 MongoDB 확장을 찾습니다.
MongoDB 확장 왼쪽의 스위치를 클릭해서 비활성화(회색)에서 활성화(녹색)로 변경합니다.
패널 하단의 저장(Save) 버튼을 클릭합니다.

ServBay는 자동으로 적합한 PHP 설정 파일을 수정하고, 변경 사항을 적용하기 위해 관련 PHP 서비스를 자동으로 재시작합니다.

설정 파일 직접 수정(선택 사항)

수동으로 구성하거나 고급 설정이 필요한 경우 PHP 설정 파일을 직접 편집할 수 있습니다. 하지만 GUI로 충분히 대부분의 설정이 가능합니다.

활성화할 PHP 버전의 conf.d 디렉터리를 찾습니다. 예를 들어, PHP 8.3용 MongoDB 확장을 활성화하려면 아래와 같은 경로가 됩니다.
bash
```
/Applications/ServBay/etc/php/8.3/conf.d/mongodb.ini
```
1
사용하는 PHP 버전과 ServBay 설치 경로에 맞게 위 경로를 조정하세요.
텍스트 편집기로 mongodb.ini 파일을 엽니다.

다음 항목을 찾으세요.

ini

[MongoDB]
; Uncomment the following line to enable MongoDB
;extension = mongodb.so

extension = mongodb.so 앞의 세미콜론(;)을 제거하여 주석을 해제합니다.
ini
```
[MongoDB]
; Uncomment the following line to enable MongoDB
extension = mongodb.so
```
1
2
3
파일을 저장합니다.
중요: 설정 파일을 수동으로 변경한 후에는 해당 PHP 서비스를 직접 재시작해야 변경 사항이 적용됩니다. ServBay GUI에서 왼쪽 내비게이션의 **패키지(Packages)**로 가서 수정한 PHP 버전을 찾고, 오른쪽의 재시작(대개 원형 화살표 아이콘) 버튼을 클릭하면 됩니다.

MongoDB 데이터베이스 서비스 시작

PHP 확장 모듈을 활성화해도 PHP가 MongoDB “대화”를 할 수 있게만 할 뿐, 데이터를 처리·저장할 실질적인 MongoDB 인스턴스가 필요합니다. ServBay는 MongoDB 데이터베이스 역시 패키지로 제공하므로 GUI에서 간단히 시작할 수 있습니다.

ServBay 앱을 실행합니다.
왼쪽 내비게이션에서 **패키지(Packages)**를 선택합니다.
패키지 목록에서 데이터베이스(Databases) 범주를 찾습니다.
MongoDB 패키지를 찾습니다.
MongoDB 패키지 왼쪽의 스위치를 클릭해 비활성(회색)에서 활성(녹색, 실행중)으로 전환합니다.

MongoDB 데이터베이스 서비스는 기본적으로 포트 27017에서 동작합니다.

MongoDB 모듈 및 DB 연결 확인

위 과정까지 완료했다면, PHP의 MongoDB 확장 모듈이 정상적으로 로드됐는지와 MongoDB 데이터베이스 서비스가 정상 작동 중인지 다음과 같이 확인할 수 있습니다.

PHP 확장 모듈 로드 확인

간단한 PHP 파일을 만들어 phpinfo() 출력에서 MongoDB 항목을 확인합니다.

ServBay 웹사이트 루트 디렉터리(예: /Applications/ServBay/www)에 phpinfo.php 등 새 PHP 파일을 작성합니다.
아래 내용을 추가하세요.
php
```
<?php
phpinfo();
?>
```
1
2
3
브라우저로 해당 파일을 접근합니다. 예: https://servbay.demo/phpinfo.php (servbay.demo가 ServBay의 www 디렉터리를 가리키는 사이트라고 가정).
열린 phpinfo 페이지에서 "MongoDB"로 검색. 정상적으로 로드됐다면 "mongodb" 섹션과 확장 버전 등 정보를 확인할 수 있습니다.

(참고: 스크린샷은 ServBay 버전이나 UI에 따라 다를 수 있습니다)

데이터베이스 연결 테스트

로컬에 실행 중인 MongoDB 데이터베이스에 연결을 시도하는 간단한 PHP 스크립트를 만들어 테스트해봅니다.

프로젝트에 공식 MongoDB PHP 드라이버가 Composer로 설치되어 있는지 확인합니다. 없다면 프로젝트 폴더에서 터미널로 아래 명령을 실행합니다.
bash
```
composer require mongodb/mongodb
```
1
프로젝트에 test_mongodb.php 등 PHP 스크립트 파일을 하나 만듭니다.

아래 코드를 추가합니다.

php

<?php

require __DIR__ . '/vendor/autoload.php'; // 프로젝트 구조에 따라 경로를 조정

echo "Attempting to connect to MongoDB...\n";

try {
    // 로컬의 기본 포트 27017에서 실행 중인 MongoDB 인스턴스에 연결
    $client = new MongoDB\Client("mongodb://localhost:27017");

    // 데이터베이스 목록을 조회해 연결이 정상인지 확인
    $listDatabases = $client->listDatabases();

    echo "Successfully connected to MongoDB!\n";
    echo "Available databases:\n";
    foreach ($listDatabases as $databaseInfo) {
        echo "- " . $databaseInfo->getName() . "\n";
    }

} catch (\MongoDB\Driver\Exception\Exception $e) {
    echo "Failed to connect to MongoDB: " . $e->getMessage() . "\n";
}

?>

이 스크립트를 터미널(ServBay에서 해당 PHP 버전으로 실행) 또는 웹에서 접속해 실행합니다. 연결에 성공하면 성공 메시지와 DB 목록을 볼 수 있으며, 실패 시에는 오류 메시지로 원인을 확인할 수 있습니다(예: MongoDB 서비스 미실행 등).

PHP 코드에서 MongoDB 사용하기

PHP MongoDB 확장이 활성화되어 있고 MongoDB 데이터베이스 서비스가 실행 중이라면, Composer로 설치한 MongoDB PHP 드라이버를 통해 다양한 데이터베이스 연산을 프로젝트에서 구현할 수 있습니다.

MongoDB PHP 드라이버 설치

앞에서 언급한 대로, 공식 드라이버는 Composer로 설치하는 것이 가장 권장되는 방법입니다.

bash

composer require mongodb/mongodb

이 명령은 mongodb/mongodb 패키지 및 의존성을 설치하고, vendor/autoload.php 파일을 생성합니다.

코드 예제

아래는 MongoDB에 연결해 Document를 삽입하고, 검색·수정하는 기본 사용 예시입니다.

php

<?php

require __DIR__ . '/vendor/autoload.php'; // Composer 오토로더 필수

echo "Connecting to MongoDB...\n";

try {
    // 로컬 MongoDB 인스턴스에 연결
    $client = new MongoDB\Client("mongodb://localhost:27017");

    // 데이터베이스 및 컬렉션 선택
    // 해당 데이터베이스나 컬렉션이 없으면 최초 쓰기 작업 시 자동 생성됨
    $collection = $client->servbay_demo_db->users; // 예시 DB명: servbay_demo_db

    echo "Connected. Performing operations...\n";

    // Document 삽입
    $insertResult = $collection->insertOne([
        'name' => 'Alice ServBay', // 브랜드명이 포함된 예시 데이터
        'email' => '[email protected]',
        'age' => 30,
        'createdAt' => new MongoDB\BSON\UTCDateTime(time() * 1000) // BSON 날짜 타입 사용
    ]);

    printf("Inserted document with ID: %s\n", $insertResult->getInsertedId());

    // Document 조회
    $document = $collection->findOne(['name' => 'Alice ServBay']);

    echo "Found document:\n";
    if ($document) {
        print_r($document);
    } else {
        echo "Document not found.\n";
    }

    // Document 업데이트(선택 사항)
    $updateResult = $collection->updateOne(
        ['name' => 'Alice ServBay'],
        ['$set' => ['age' => 31, 'status' => 'updated']]
    );
    printf("Matched %d document(s) for update, modified %d document(s).\n", $updateResult->getMatchedCount(), $updateResult->getModifiedCount());

    // 업데이트된 Document 조회(선택 사항)
     $updatedDocument = $collection->findOne(['name' => 'Alice ServBay']);
     echo "Updated document:\n";
     if ($updatedDocument) {
         print_r($updatedDocument);
     }

    // Document 삭제(선택 사항)
    // $deleteResult = $collection->deleteOne(['name' => 'Alice ServBay']);
    // printf("Deleted %d document(s).\n", $deleteResult->getDeletedCount());


} catch (\MongoDB\Driver\Exception\Exception $e) {
    echo "An error occurred: " . $e->getMessage() . "\n";
} catch (\Exception $e) {
    echo "An unexpected error occurred: " . $e->getMessage() . "\n";
}

echo "Script finished.\n";

?>

위 코드를 PHP 파일로 저장한 뒤, ServBay의 PHP CLI로 실행하거나, ServBay 웹서버 구성을 통해 웹에서 접근하여 사용할 수 있습니다.

유의사항 및 베스트 프랙티스

MongoDB 서비스 상태: ServBay GUI에서 MongoDB 패키지가 반드시 “실행 중”이어야 정상적으로 연결됩니다.
기본 포트: MongoDB는 기본적으로 27017 포트에서 동작합니다. 다른 포트로 연결해야 할 경우, 연결 문자열에 직접 지정할 수 있으며, ServBay GUI에서 패키지 설정 정보를 확인·수정할 수 있습니다.
확장 vs. 드라이버: PHP의 mongodb.so 확장은 저수준 통신 기능을 제공하며, mongodb/mongodb Composer 패키지는 편리한 객체지향 API를 통해 실제 데이터베이스 연산을 구현할 수 있습니다. 대부분의 현대 PHP 프로젝트에서는 두 가지를 모두 사용합니다.
ServBay User CA/Public CA: ServBay는 자체 내장 인증기관(CA)을 통해 SSL 인증서를 발급하는 기능을 지원합니다. 로컬 개발 중에 실제 프로덕션 환경의 HTTPS 연결을 시뮬레이션 할 수 있어 보안 테스트에 유용합니다. 단, 로컬 MongoDB 연결 자체는 기본적으로 SSL이 필요하지 않지만, 복잡한 구성이 필요한 경우 활용할 수 있습니다. 이 외에도 ServBay는 ACME 프로토콜 기반의 실 인증서 신청, 데이터 백업, 데이터베이스 비밀번호 초기화 등 다양한 기능을 제공합니다.
데이터베이스 관리 도구: ServBay에는 MongoDB 그래픽 관리 도구가 포함되어 있지 않을 수 있습니다. 공식 MongoDB Compass를 다운로드하거나, 커맨드라인 mongo/mongosh 도구로 ServBay가 실행 중인 로컬 MongoDB 인스턴스를 관리할 수 있습니다.

자주 묻는 질문(FAQ)

Q: PHP MongoDB 확장 모듈을 활성화했는데도 PHP 스크립트가 MongoDB에 연결되지 않습니다. 어떻게 해야 하나요?
A: ServBay GUI에서 MongoDB 데이터베이스 서비스도 반드시 실행되어야 합니다. PHP 확장은 단순히 인터페이스일 뿐이고, 데이터베이스 서비스가 실제로 구동되어야만 정상적으로 연결됩니다. 연결 문자열(주로 mongodb://localhost:27017)이 올바른지도 확인해 주세요.

Q: mongodb.so 확장과 mongodb/mongodb Composer 패키지는 어떤 차이가 있나요?
A: mongodb.so는 PHP 엔진에 로드되는 저수준 확장으로, PHP와 MongoDB C 드라이버(libmongoc)간 통신 기능을 제공합니다. 반면, mongodb/mongodb Composer 패키지는 이 확장을 기반으로 동작하는 PHP용 라이브러리로, 데이터베이스 CRUD/집계 등 고수준의 객체지향 API를 제공합니다. 실무 PHP 개발에서는 보통 두 가지 모두 필요합니다.

Q: MongoDB의 포트나 다른 설정은 어떻게 바꾸나요?
A: ServBay GUI에서 MongoDB 패키지의 설정 메뉴에서 포트 등 주요 옵션을 확인·변경할 수 있습니다. 더 복잡한 설정이 필요하다면 ServBay 내에서 MongoDB 설정 파일(경로는 패키지 상세 보기에서 확인 가능)을 직접 수정해야 하며, 수정 후 MongoDB 서비스를 재시작해야 적용됩니다.

요약

ServBay는 PHP 개발자에게 매우 간편한 MongoDB 개발 환경을 제공합니다. ServBay의 직관적인 GUI를 통해 PHP의 MongoDB 확장 모듈을 손쉽게 활성화하고 MongoDB 데이터베이스 서비스를 시작할 수 있습니다. Composer로 설치한 공식 PHP 드라이버와 연동하면, 로컬에서 최적의 PHP+MongoDB 개발 환경을 빠르게 구축할 수 있어 애플리케이션 로직 개발에 집중할 수 있습니다. ServBay는 환경 세팅의 번거로움을 줄여 개발 및 테스트 효율을 극대화할 수 있도록 돕습니다.

ServBay에서 MongoDB 사용하기 (PHP 확장 및 데이터베이스 서비스 연동) ​

개요: ServBay와 MongoDB ​

PHP MongoDB 확장 버전 ​

PHP MongoDB 확장 활성화 ​

ServBay GUI를 통한 활성화 ​

설정 파일 직접 수정(선택 사항) ​

MongoDB 데이터베이스 서비스 시작 ​

MongoDB 모듈 및 DB 연결 확인 ​

PHP 확장 모듈 로드 확인 ​

데이터베이스 연결 테스트 ​

PHP 코드에서 MongoDB 사용하기 ​

MongoDB PHP 드라이버 설치 ​

코드 예제 ​

유의사항 및 베스트 프랙티스 ​

자주 묻는 질문(FAQ) ​

요약 ​