Composer에서 로컬 패키지 사용 방법: PHP 개발자를 위한 가이드

Source: Dev.to

PHP 프로젝트를 작업할 때 Packagist에 공개된 외부 라이브러리에 의존하는 경우가 흔합니다. Composer를 사용하면 이러한 의존성을 손쉽게 설치하고 관리할 수 있습니다. 하지만 Packagist가 아닌 로컬에서 의존성을 작업해야 한다면 어떻게 할까요?

로컬 경로 저장소를 사용하는 이유

• 빠른 반복 – 새 버전을 배포하거나 GitHub에 푸시하지 않고도 라이브러리의 변경 사항을 즉시 테스트할 수 있습니다.
• 깊은 디버깅 – 로깅을 추가하거나 내부 상태를 확인하고, 라이브러리 코드를 단계별로 추적할 수 있습니다.
• 풀‑리퀘스트 테스트 – 실제 프로젝트에서 변경 사항을 검증한 뒤 PR을 제출할 수 있습니다.
• 오프라인 개발 – GitHub나 Packagist 접근이 차단된 환경에서도 유용합니다.
• 실험적인 작업 – 공개 없이 파괴적인 변경이나 내부 API를 시도해 볼 수 있습니다.
• 버전 관리 편의성 – 빠르게 반복하면서 의미론적 버전을 올릴 필요가 없습니다.

전형적인 시나리오

프로젝트의 composer.json은 다음과 같이 보일 수 있습니다:

{
  "require": {
    "storyblok/php-management-api-client": "@dev",
    "vlucas/phpdotenv": "^5.6"
  },
  "repositories": [
    {
      "type": "path",
      "url": "../php-management-api-client"
    }
  ]
}

"type": "path"가 지정된 repositories 항목은 Composer에게 Packagist에서 패키지를 다운로드하는 대신 ../php-management-api-client에 있는 복사본을 사용하도록 지시합니다. 이렇게 하면 라이브러리를 프로젝트 옆에 클론하고 수정한 내용을 즉시 확인할 수 있습니다.

로컬 패키지 설정하기

1. 프로젝트 근처에 라이브러리 배치

   ~/Projects/my-project
   ~/Projects/php-management-api-client   ← 클론한 라이브러리

   폴더 이름은 패키지 이름과 일치할 필요가 없으며, composer.json에 정의된 URL과 경로만 일치하면 됩니다.

2. symlink 옵션을 포함한 경로 저장소 추가

   // composer.json (excerpt)
   "repositories": [
     {
       "type": "path",
       "url": "../php-management-api-client",
       "options": {
         "symlink": true
       }
     }
   ]

   "symlink": true를 사용하면 심볼릭 링크가 생성되어 라이브러리의 변경 사항이 재설치 없이 바로 반영됩니다.

3. 개발 버전 요구

   Composer가 안정 버전이 아닌 개발 브랜치를 사용하도록 해야 합니다. 가장 확실한 방법은 특정 개발 브랜치, 예를 들어 dev-main을 요구하는 것입니다:

   "require": {
     "storyblok/php-management-api-client": "dev-main"
   }

마주칠 수 있는 버전 제약

로컬 의존성 업데이트

다음 명령을 실행하여 로컬 패키지를 설치하거나 업데이트합니다:

composer update storyblok/php-management-api-client

모범 사례

• 로컬 클론을 깔끔하게 유지 – 임시 디버그 코드를 커밋하지 않도록 합니다.
• 개발이 끝나면 Packagist 버전으로 전환합니다.
• 팀 전체 개발 흐름이 아니라면 로컬 경로 설정을 저장소에 커밋하지 않도록 합니다.

이 절차를 따르면 메인 프로젝트와 나란히 의존성을 작업할 수 있어 개발 속도가 빨라지고 디버깅이 간편해집니다.