ServBay 내장 Composer로 PHP 프로젝트 관리하는 방법

ServBay는 강력한 로컬 웹 개발 환경으로, 개발자를 위해 Composer를 기본 내장하고 있어 PHP 프로젝트의 의존성 관리 과정을 크게 간소화합니다. Composer는 현대 PHP 개발에서 빼놓을 수 없는 필수 의존성 관리자 도구로, 서드파티 라이브러리 통합과 복잡한 의존성 문제 자동 해결, 편리한 자동 로딩 기능을 제공합니다. ServBay를 사용하면 별도의 설치나 추가 설정 없이 Composer의 모든 기능을 즉시 활용하여 PHP 개발 워크플로우를 가속화할 수 있습니다.

Composer란?

Composer는 PHP 프로젝트의 의존성을 관리하는 도구입니다. 개발자가 프로젝트에서 필요한 외부 라이브러리(패키지라고도 부름)를 선언하면, Composer가 이 패키지들을 자동으로 설치하고 최신 상태로 업데이트합니다. PHP 라이브러리뿐만 아니라, 다양한 프레임워크, 컴포넌트, 플러그인까지 폭넓게 관리할 수 있습니다.

주요 특징

의존성 관리: Composer는 프로젝트가 필요로 하는 모든 라이브러리와 그 버전의 호환성을 자동으로 판단하여 관리하고, 잠재적인 충돌도 해결합니다.
자동 로딩: 모두가 작성한 클래스를 Composer가 자동으로 로딩할 수 있도록 통합된 autoload 파일을 생성하므로, 개발자는 별도의 include나 require 처리를 신경 쓸 필요가 없습니다.
버전 제어: composer.json 파일에서 패키지 버전 제약을 지정할 수 있고, Composer는 이 조건에 맞는 버전을 설치합니다. 현재 환경의 정확한 라이브러리 버전은 composer.lock 파일로 고정돼, 팀원이나 다른 환경에서도 동일한 환경을 보장합니다.
패키지 관리: Composer는 대표적인 중앙 저장소인 Packagist를 통해 거의 모든 인기 PHP 라이브러리를 찾아서 사용할 수 있습니다.
커뮤니티 지원: 활발한 개발자 커뮤니티와 방대한 공식 문서가 있어 학습 및 문제 해결이 용이합니다.

ServBay에 통합된 Composer

ServBay에는 다양한 PHP 버전과 함께 Composer가 미리 설치되어 있습니다. 즉, 별도로 Composer를 다운로드하거나 환경을 추가로 설정할 필요가 없으며, ServBay가 시스템 환경 변수 설정 및 각 PHP 버전과의 연동까지 자동으로 처리합니다. 터미널에서 바로 composer 혹은 composer-2.2 명령어를 사용할 수 있습니다.

주의

Composer는 최신 버전(Composer 2.8.x)과 구형 PHP 버전 호환 목적인 Composer 2.2.x LTS 두 가지 버전이 제공됩니다. 각각 대응 PHP 버전은 아래와 같습니다.

Composer 2.8.x: PHP 7.2 이상 지원
Composer 2.2.x LTS: PHP 5.3 ~ PHP 7.1 지원

ServBay는 기본적으로 Composer 2.8.x가 내장되어 있으며, PHP 7.2 이상에서 사용하면 됩니다.

만약 PHP 5.3 ~ 7.1 환경이 필요하다면, [소프트웨어 패키지] 메뉴에서 Composer 2.2.x LTS를 설치하세요. 설치 후에는 명령어 composer-2.2로 실행하면 됩니다. 두 버전은 서로 충돌하지 않습니다.

Composer로 의존성 관리하기

Composer는 프로젝트 루트 디렉터리에 위치한 composer.json 파일을 바탕으로 라이브러리 의존성을 관리합니다. 아래의 과정을 따라 composer.json 파일을 만들고 사용하는 기본 방법을 알아보겠습니다.

1. `composer.json` 파일 생성

PHP 프로젝트 루트 폴더에 composer.json 파일을 만듭니다. 예를 들어 /Applications/ServBay/www/my_php_project 디렉터리에서 작업한다면, 그 경로에 파일을 생성하세요.

composer.json은 JSON 형식의 오브젝트이며, require라는 키에 필요한 패키지를 명시합니다. 키는 패키지명(벤더명/패키지명), 값은 버전 제약입니다.

아래는 Monolog(인기 PHP 로깅 라이브러리) 버전 2.0 이상을 요구하는 예시입니다:

json

{
    "require": {
        "monolog/monolog": "^2.0"
    }
}

여기서 ^2.0은 최소 2.0.0 이상이면서, 3.0.0 미만의 모든 버전을 허용한다는 의미입니다.

2. 의존성 설치

composer.json이 있는 프로젝트 루트에서 터미널을 열고 다음 명령어를 실행하세요:

composer install

실행되면 다음이 진행됩니다:

Composer가 composer.json을 읽어옵니다.
직접 명시한 라이브러리와 그 하위 의존성을 계산합니다.
모든 의존성 패키지는 프로젝트 루트의 vendor 폴더에 설치됩니다.
모든 실제 설치 버전은 composer.lock 파일에 기록됩니다. 이 파일은 꼭 버전 관리(Git 등)에 포함되어야 팀원과 환경별로 동일 버전을 사용할 수 있습니다.
자동 로딩 파일인 vendor/autoload.php가 생성됩니다.

설치가 끝나면 프로젝트 폴더에 vendor와 composer.lock 파일이 추가됩니다.

Composer의 자동 로딩 사용하기

Composer의 중요한 장점 중 하나는 자동 로딩입니다. 다양한 표준(PSR-0, PSR-4)을 지원하여, 클래스명과 파일 경로를 매핑한 통합 자동 로딩 파일을 만들어줍니다.

아래는 자동 로딩 구성 및 사용하는 방법입니다.

1. `autoload` 항목 추가

composer.json 내에 autoload를 추가 또는 수정합니다. 예를 들어 PSR-4 표준으로 App\ 네임스페이스를 루트의 src/ 디렉터리와 연결하려면 아래와 같이 설정합니다:

json

{
    "require": {
        "monolog/monolog": "^2.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

이렇게 하면 App\로 시작하는 클래스명은 src/ 폴더의 하위 구조에 따라 클래스를 자동으로 로드할 수 있습니다. (예: App\MyClass → src/MyClass.php)

2. 자동 로딩 파일 생성

autoload 구성을 추가/수정했다면 아래 명령어를 실행해 자동 로딩 맵을 갱신하세요:

composer dump-autoload

이 명령어는 vendor/autoload.php 파일을 새로 만듭니다. 만약 의존성만 추가·업데이트했을 뿐 autoload는 변하지 않았다면, composer install 또는 composer update 실행 시에도 자동 반영됩니다.

3. 코드에서 자동 로딩 파일 불러오기

PHP 스크립트 첫 부분에서 Composer 자동 로딩 파일을 가져옵니다:

php

<?php

// Composer 자동 로딩 파일 불러오기
require __DIR__ . '/vendor/autoload.php';

// 이제 Composer로 설치한 라이브러리나 autoload에 설정한 클래스들을 자유롭게 사용할 수 있습니다.
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use App\MyClass; // App\ 네임스페이스 자동 로딩을 설정했다면 사용 가능

// Monolog 사용 예시
$log = new Logger('name');
$log->pushHandler(new StreamHandler('your.log', Logger::WARNING));
$log->warning('이것은 경고 메시지입니다!');

// 직접 만든 클래스 사용 예시(autoload를 설정했다면)
// $myObject = new MyClass();
// $myObject->doSomething();

?>

require __DIR__ . '/vendor/autoload.php'; 코드 한 줄만으로, 앞으로 모든 Composer 관리 클래스를 곧바로 사용할 수 있어 복잡한 require/include 처리에서 해방됩니다.

의존성 패키지 업데이트

프로젝트가 커가거나 패키지 최신 버전이 출시되면, 의존성을 최신으로 맞출 필요가 있습니다.

터미널에서 프로젝트 루트에서 다음 명령어를 입력하세요:

composer update

composer update는 composer.json의 각 의존성의 최신 버전을 확인하고, 버전 제약에 맞는 경우 다운로드 및 설치합니다.
설치 후, 모든 실제 설치 정보를 composer.lock으로 갱신하게 됩니다.

중요 포인트:

composer install과 composer update의 차이:
- composer install: 프로젝트 세팅이나 기존 프로젝트에서 의존성 설치 시 사용하며, 무조건 composer.lock에 기록된 버전을 설치하여 환경 불일치를 방지합니다.
- composer update: 모든(혹은 일부) 패키지를 최신 버전으로 맞추고, 그 결과를 composer.lock에 반영합니다. 협업 또는 배포 환경에서는 변경이 필요한 경우에만 사용하고, 변경된 composer.json과 composer.lock을 함께 커밋해야 동일 환경이 구성됩니다.

ServBay 환경에서 Composer 사용할 때 참고사항

ServBay는 로컬 개발의 편의를 제공하지만, Composer 사용 시 아래를 참고하세요:

터미널 환경: ServBay로 PHP/Composer를 사용 중이라면, ServBay가 PATH 환경 변수에 올바른 PHP 버전 경로를 추가합니다. 만약 command not found 에러가 뜬다면, 터미널을 재실행하거나 ServBay가 실행 중인지 확인하세요.
PHP 버전: ServBay 패널에서 PHP 버전을 쉽게 변경할 수 있습니다. composer는 ServBay에서 현재 활성화한 PHP로 실행됩니다. 특정 버전의 PHP로 Composer를 실행해야 한다면(예: 구버전 PHP만 지원하는 라이브러리 설치 시) 먼저 ServBay에서 적절한 PHP 버전을 활성화하세요.
프로젝트 경로: 웹 프로젝트는 ServBay 기본 사이트 루트 /Applications/ServBay/www의 하위 폴더에 두는 것이 바람직하며, ServBay 패널에서 해당 폴더를 사이트로 연결해 관리하면 편리합니다. 각 프로젝트 폴더에서 Composer를 실행하면 됩니다.

실전 예제: GuzzleHttp 라이브러리 사용

아래는 ServBay 환경에서 Composer를 통해 GuzzleHttp(대표적인 PHP HTTP 클라이언트)를 설치·사용하는 과정을 단계별로 소개합니다.

프로젝트 폴더 생성 및 이동: ServBay 웹사이트 루트에서 신규 디렉터리 생성 후 이동하세요:
sh
```
cd /Applications/ServBay/www
mkdir guzzle_demo.servbay.demo
cd guzzle_demo.servbay.demo
```
1
2
3
ServBay 도메인 네이밍 권장규칙에 맞춰 예시 디렉터리명을 사용했습니다.
composer.json 파일 작성: guzzle_demo.servbay.demo 폴더에 아래와 같이 composer.json 파일을 만듭니다:
json
```
{
    "require": {
        "guzzlehttp/guzzle": "^7.0"
    },
    "autoload": {
         "psr-4": {
             "App\\": "src/"
         }
     }
}
```
1
2
3
4
5
6
7
8
9
10
PSR-4 자동 로딩까지 설정했지만 예제에서는 사용하지 않더라도 추후 확장성과 관례상 추가하는 것이 좋습니다.
의존성 설치: 아래 명령어로 의존성 설치를 진행하세요:
sh
```
composer install
```
1
Composer는 GuzzleHttp와 관련 라이브러리를 vendor 폴더에 설치하고, composer.lock도 생성합니다.

PHP에서 라이브러리 사용하기: 아래와 같이 index.php 파일을 작성하세요:

php

<?php
// Composer 자동 로딩 파일 불러오기
require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

echo "<h1>GuzzleHttp Demo</h1>";
echo "<pre>";

try {
    // Guzzle 클라이언트 인스턴스 생성
    $client = new Client();

    // GET 요청 보내기
    $response = $client->request('GET', 'https://httpbin.org/get', [
        'query' => ['param1' => 'value1', 'param2' => 'value2']
    ]);

    // 응답 본문 읽기
    $body = $response->getBody()->getContents();
    echo "Response Body:\n";
    echo $body;

    // 응답 상태코드 출력
    $statusCode = $response->getStatusCode();
    echo "\n\nStatus Code: " . $statusCode;

} catch (RequestException $e) {
    // 요청 예외 처리
    echo "Request Exception:\n";
    echo $e->getMessage();
    if ($e->hasResponse()) {
        echo "\nResponse Status: " . $e->getResponse()->getStatusCode();
        echo "\nResponse Body: " . $e->getResponse()->getBody()->getContents();
    }
} catch (\Exception $e) {
    // 기타 예외 처리
    echo "An error occurred:\n";
    echo $e->getMessage();
}

echo "</pre>";
?>

자동 로딩 파일을 불러오고, GuzzleHttp 클라이언트로 테스트 API에 요청해 결과를 출력합니다.

ServBay 사이트 등록: ServBay 콘솔에서 "사이트" 탭(기존 "호스트")으로 이동 → "추가" 버튼 클릭 → 사이트 경로를 /Applications/ServBay/www/guzzle_demo.servbay.demo로 지정, 도메인은 guzzle_demo.servbay.demo로 입력 후 저장 및 웹서버(Caddy/Nginx 등) 재시작.
브라우저 접속: 브라우저에서 http://guzzle_demo.servbay.demo/로 접속하면 PHP 코드 실행 결과와 함께 httpbin API에서 반환된 데이터를 볼 수 있습니다.

자주 묻는 질문(FAQ)

Q: PHP 5.6을 사용 중인데 Composer가 제대로 동작하지 않습니다. 어떻게 해야 하나요?

A: ServBay는 메인 Composer(2.8.x)와 구형 PHP 호환 Composer(2.2.x LTS) 두 가지를 제공합니다. PHP 5.6을 위한 Composer 2.2 LTS를 설치하고, 명령어 composer-2.2로 실행하세요.

Q: 터미널에서 composer 명령어가 command not found라고 나올 때는 어떻게 해야 하나요?

ServBay 앱이 정상 동작 중인지 확인하세요.
터미널을 재시작해 보세요. ServBay는 시작 시 환경변수를 설정하므로, 새 터미널에서 제대로 인식될 수 있습니다.
ServBay 패널에서 PHP 버전이 적어도 하나 이상 활성화되어 있는지 확인하세요.
문제가 계속되면, ServBay에서 제공하는 PHP 실행 파일 전체 경로와 Composer 경로를 조합해서 실행하는 방법도 있습니다.
(예시: /Applications/ServBay/php/8.2/bin/php /usr/local/bin/composer install
실제 경로는 자신의 환경에 따라 달라질 수 있습니다. 원칙적으로는 그냥 composer 명령만으로 충분하도록 설계되었습니다.)

Q: ServBay의 특정 PHP 버전에서 Composer를 사용하고 싶으면 어떻게 해야 합니까?

A: Composer는 ServBay 콘솔에서 활성화한 PHP 버전으로 실행됩니다. PHP 탭에서 원하는 버전을 선택 후, 새 터미널을 열고 composer를 실행하면 해당 PHP 버전이 자동 적용됩니다.

Q: composer.lock 파일의 의미와 Git 커밋 여부는?

A: composer.lock 파일은 마지막 설치/업데이트 시점에 실제 설치된 각 라이브러리의 정확한 버전을 기록합니다.
반드시 로컬 및 협업을 위한 버전 관리(Git 등)에 커밋해야 하며, 이렇게 해야 팀이나 테스트·운영환경에서도 '내 컴퓨터에서만 되는 문제' 없이 동일한 버전 세팅이 보장됩니다.
다른 사용자가 CI나 서버에서 composer install 명령을 실행할 때, composer.lock에 따라 정확히 같은 버전이 설치됩니다.

마무리

ServBay는 Composer를 미리 내장하여, PHP 개발자가 여러 버전의 PHP로 손쉽게 의존성 관리와 자동 로딩을 경험할 수 있도록 최고의 환경을 제공합니다.
설정 걱정 대신 코드에 집중하고, 더 빠르고 안정적인 프로젝트 개발과 협업을 이끌어 보세요.
ServBay와 Composer의 조합은 현대 PHP 개발의 표준이며, 여러분의 개발 생산성과 프로젝트 품질을 크게 향상시켜 드릴 것입니다.

ServBay 내장 Composer로 PHP 프로젝트 관리하는 방법 ​

Composer란? ​

주요 특징 ​

ServBay에 통합된 Composer ​

Composer로 의존성 관리하기 ​

1. composer.json 파일 생성 ​

2. 의존성 설치 ​

Composer의 자동 로딩 사용하기 ​

1. autoload 항목 추가 ​

2. 자동 로딩 파일 생성 ​

3. 코드에서 자동 로딩 파일 불러오기 ​

의존성 패키지 업데이트 ​

ServBay 환경에서 Composer 사용할 때 참고사항 ​

실전 예제: GuzzleHttp 라이브러리 사용 ​

자주 묻는 질문(FAQ) ​

마무리 ​