프로젝트 폴더 구조

컴포저를 통해 외부 의존성 패키지를 설치하게 되면, 사전에 정해진 일정한 폴더 아키텍처 규칙에 따라 관련 파일들이 프로젝트 내부에 배치됩니다.

이 장에서는 컴포저 설치 시 생성되는 디렉터리의 내부 레이아웃과 개별 구성 파일의 구체적인 역할 및 호출 매커니즘을 상세히 분석합니다.

1. 컴포저 기본 폴더 트리 (Directory Layout)

기본적으로 컴포저는 외부 라이브러리 소스코드를 관리하기 위해 프로젝트 루트 디렉터리에 vendor/라는 특수한 서브 디렉터리를 자동 생성합니다. 표준적인 컴포저 연동 프로젝트의 폴더 및 파일 배치는 다음과 같습니다.

my-project/
├── composer.json               # 프로젝트 패키지 설정서
├── composer.lock               # 패키지 최종 설치 버전 잠금 파일
├── index.php                   # 진입점 소스 코드
├── src/                        # 내가 직접 개발하는 애플리케이션 코드 소스 디렉터리
│   └── Controller/
└── vendor/                     # 컴포저 관리 격리 설치 디렉터리
    ├── autoload.php            # 오토로드 부트스트랩 허브 파일
    ├── bin/                    # 패키지들이 제공하는 CLI 명령어 실행 링크 (예: phpunit)
    ├── composer/               # 오토로드 매핑 구현 소스 및 메타 파일들이 위치하는 핵심 폴더
    │   ├── autoload_classmap.php
    │   ├── autoload_files.php
    │   ├── autoload_namespaces.php
    │   ├── autoload_psr4.php
    │   └── autoload_real.php
    └── [vendor-name]/          # 벤더(배포 개발자/단체)명 기준으로 서브 격리
        └── [package-name]/     # 설치된 패키지 이름
            ├── composer.json   # 해당 패키지의 설정 및 개별 오토로드 규칙 기술서
            └── src/            # 패키지 구동용 실제 라이브러리 코드

2. 핵심 구성 요소 설명

2.1 vendor/autoload.php

컴포저 폴더의 대문 역할을 하는 PHP 파일입니다. 이 파일은 복잡하게 분산된 클래스 탐색 로직을 모두 감춘 채 내부적으로 vendor/composer/autoload_real.php를 로드하여 오토로더 인스턴스를 초기화하고 리턴합니다.

• 개발자는 애플리케이션의 최초 실행 파일이나 공통 설정 파일의 최상단에서 이 파일 하나만 불러오면 모든 의존 라이브러리 클래스를 자유롭게 호출할 수 있습니다.

  require_once __DIR__ . '/vendor/autoload.php';
  

2.2 vendor/composer/ 디렉터리

컴포저가 패키지를 분석해 동적으로 생성해 주는 오토로드 매핑 캐시 파일들이 위치합니다.

• autoload_psr4.php: PSR-4 규약을 만족하는 네임스페이스 접두사(Prefix)와 실제 물리 디렉터리 경로의 연결 관계를 연상 배열(Map) 형태로 담고 있습니다.
• autoload_classmap.php: 클래스맵 방식을 사용할 때 모든 개별 클래스 이름과 해당 파일의 절대경로를 일대일로 통째로 기록한 해시 테이블 배열 파일입니다.
• autoload_files.php: 네임스페이스와 무관하게 항상 인클루드해야 하는 전역 공통 함수 정의 파일들의 파일 경로들을 보관합니다.
• autoload_namespaces.php: 레거시 규약인 PSR-0 방식으로 설계된 패키지들의 물리 맵 정보를 기록합니다.

2.3 vendor/bin/ 디렉터리

설치한 패키지 중에서 외부 실행기를 포함하고 있는 경우(예: PHPUnit, PHP CodeSniffer 등), 해당 유틸리티를 프로젝트 경로에서 바로 실행할 수 있도록 가상 바로가기 심볼릭 링크(Symbolic Link) 또는 배치 파일을 모아두는 실행기 보관 영역입니다.

3. 벤더(vendor)와 패키지(package) 네이밍 아키텍처

컴포저는 물리적인 파일 겹침과 충돌을 원천 차단하기 위해 vendor/[벤더명]/[패키지명] 형태의 깊이 있는 2차 서브 디렉터리 구조를 고수합니다.

3.1 벤더명 (vendor-name)

네임스페이스의 첫 번째 최상위 식별자 역할을 감당합니다. 개발 회사명, GitHub ID, 개인 도메인 등이 사용됩니다. 전 세계 벤더명은 유일해야 하며, Packagist에 등록할 때 중복 여부가 체크됩니다.

3.2 패키지명 (package-name)

해당 벤더가 배포하는 제품 고유의 이름입니다. 같은 벤더 하위라면 패키지 이름이 중복되지 않게 자유롭게 붙입니다.

3.3 서브 폴더 구성

다운로드된 각 패키지 내부에는 순수 동작 코드 외에도 문서(README.md), 예제(examples/), 단위 테스트용 코드(tests/)가 동봉되므로 패키지 폴더 안에서도 src/ 폴더 등을 따로 나누는 것이 표준적인 구성법입니다.

• 이와 같이 패키지가 서브 디렉터리를 포함하고 있다면, 해당 패키지의 자체 composer.json 파일에도 소스 코드의 실제 경향을 명시(예: "src/" 지정)해야 올바르게 동작합니다.