Premium 에디션

Composer로 비공개 NextPDF 프리미엄 패키지 설치 및 인증하기

한눈에 보기

NextPDF 프리미엄 패키지인 nextpdf/pro, nextpdf/enterprise, 그리고 nextpdf/premium 메타패키지는 공개 Packagist 인덱스에 게시되어 있지 않습니다. 이 패키지들은 사용자의 계정에 연결된 비공개 Composer 저장소에 존재하므로, Composer에 두 가지를 알려 주기 전까지는 단순한 composer require nextpdf/premium으로는 찾을 수 없습니다. 알려 주어야 하는 두 가지는 저장소가 어디에 있는지, 그리고 어떻게 인증하는지입니다.

이 페이지는 라이선스 및 활성화가 끝나는 지점에서 이어집니다. 자격 증명을 확보하고 나면 Composer를 한 번 구성하고, 패키지를 설치한 뒤 확인합니다. 여기에 나오는 모든 내용은 표준 Composer 동작이며, 어느 것도 NextPDF 고유의 도구가 아닙니다. 라이선스 페이지가 서명된 라이선스 봉투를 다루는 것과 정확히 동일하게, 저장소 토큰을 API 키처럼 취급하십시오. 공개 버전 관리 밖에 두어야 합니다.

자격 증명이 발급되는 위치

귀하의 비공개 저장소 URL, 사용자 이름, 토큰은 라이선스를 취득한 후에 — 공인 판매 사업자(Merchant of Record)를 통해 구매하거나 평가를 시작함으로써 — 라이선스 포털에서 발급됩니다. 구매 경로, 두 계약 모델(구매 대 라이선스), 그리고 청구 문의와 제품 지원의 연락 창구는 구매 및 라이선싱을 참조하십시오.

1. 프리미엄 패키지가 존재하는 위치

라이선스 포털은 설치에 필요한 두 가지를 발급합니다.

비공개 Composer 저장소 URL — 프리미엄 패키지를 제공하는 인증된 엔드포인트입니다.
해당 엔드포인트를 위한 사용자 이름과 토큰(HTTP Basic 자격 증명 쌍)입니다.

이 페이지가 저장소 호스트를 보여 주는 모든 곳에는 라이선스 포털에서 받은 저장소 URL을 대입하십시오. 사용자 이름이나 토큰을 보여 주는 모든 곳에는 사용자의 계정에 발급된 자격 증명을 대입하십시오. NextPDF는 공유되는 단일 URL을 게시하지 않습니다. 엔드포인트와 자격 증명은 사용자의 구독에 고유합니다.

2. composer.json에 비공개 저장소 추가하기

프로젝트 루트에서 실행하는 한 줄 명령으로 Composer에 저장소를 알려 주십시오.

composer config repositories.nextpdf composer https://repo.example.com/nextpdf

https://repo.example.com/nextpdf를 포털에서 받은 URL로 교체하십시오. composer 저장소 유형은 Composer가 Composer 형식의 인덱스(packages.json)를 가리키도록 하며, 이것이 바로 비공개 패키지 엔드포인트가 제공하는 것입니다.

이 명령은 composer.json에 repositories 블록을 작성합니다. 직접 손으로 추가할 수도 있습니다.

{
    "repositories": {
        "nextpdf": {
            "type": "composer",
            "url": "https://repo.example.com/nextpdf"
        }
    }
}

저장소 정의는 비밀 정보가 아닙니다 — 위치만 가리킬 뿐이므로 커밋해도 안전합니다. 보호해야 하는 것은 다음 단계의 자격 증명입니다.

3. 세 가지 표준 방법 중 하나로 인증하기

Composer는 호스트에 대한 HTTP Basic 자격 증명을 여러 위치에서 읽습니다. 설치 위치에 맞는 방법을 선택하십시오.

방법 A — auth.json (로컬 개발)

개발자 머신의 경우 자격 증명을 composer.json 옆의 auth.json 파일에 저장하십시오. 키로는 저장소 URL의 호스트를 사용하십시오.

composer config --auth http-basic.repo.example.com your-username your-token

이렇게 하면 프로젝트 로컬 auth.json이 생성(또는 갱신)됩니다.

{
    "http-basic": {
        "repo.example.com": {
            "username": "your-username",
            "password": "your-token"
        }
    }
}

호스트 키(repo.example.com)는 저장소 URL의 호스트와 정확히 일치해야 합니다. Composer는 호스트를 기준으로 자격 증명을 요청에 매칭합니다.

방법 B — COMPOSER_AUTH 환경 변수 (CI/CD)

지속적 통합에서는 보통 디스크에 파일을 두고 싶지 않습니다. Composer는 COMPOSER_AUTH 환경 변수에서 동일한 자격 증명을 읽으며, 그 값은 auth.json과 동일한 형태의 JSON 문자열입니다.

export COMPOSER_AUTH='{"http-basic":{"repo.example.com":{"username":"your-username","password":"your-token"}}}'
composer install

토큰이 파이프라인 정의나 빌드 로그에 절대 나타나지 않도록, CI 공급자의 비밀 정보 저장소(마스킹된 변수, 시크릿 또는 볼트 바인딩)에서 COMPOSER_AUTH를 주입하십시오.

방법 C — 사용자별 전역 인증 (공유 워크스테이션)

프로젝트별 파일 없이 현재 사용자의 모든 프로젝트를 인증하려면, 자격 증명을 Composer의 전역 auth.json에 기록하십시오.

composer config --global --auth http-basic.repo.example.com your-username your-token

이렇게 하면 자격 증명이 Composer 홈 디렉터리(COMPOSER_HOME, 예를 들어 ~/.composer/auth.json 또는 ~/.config/composer/auth.json) 아래에 저장됩니다. 해당 사용자로 빌드하는 모든 프로젝트에 적용되므로, 자격 증명을 하나의 프로젝트나 파이프라인으로 한정해야 할 때는 방법 A나 B를 선호하십시오.

4. 자격 증명을 버전 관리 밖에 두기

저장소 URL은 커밋해도 안전하지만 토큰은 그렇지 않습니다. 두 가지 규칙이 비밀 정보를 이력 밖에 둡니다.

로컬 auth 파일을 무시하십시오. 프로젝트 로컬 자격 증명이 절대 커밋되지 않도록 auth.json을 .gitignore에 추가하십시오.
```
/auth.json
```
CI/CD에서 토큰을 주입하십시오. auth.json을 저장소에 체크인하거나 컨테이너 이미지 레이어에 구워 넣는 대신, 파이프라인의 비밀 정보 저장소에서 COMPOSER_AUTH(방법 B)를 제공하십시오.

토큰이 한 번이라도 커밋되거나 출력되면 라이선스 포털을 통해 교체하십시오 — 유출된 API 키와 정확히 마찬가지로 손상된 것으로 취급하십시오.

5. 설치 및 확인

저장소와 자격 증명이 준비되면, 라이선스가 부여하는 에디션을 require하십시오.

# Pick the package for your entitlement:
composer require nextpdf/pro
# or
composer require nextpdf/enterprise
# or the metapackage, which the licensing page uses:
composer require nextpdf/premium

프로젝트가 명시적인 제약을 선호한다면 메이저 버전을 고정하십시오 — 예를 들어 Pro 모듈 페이지가 사용하는 제약과 일치하는 composer require nextpdf/pro:^3처럼 지정하십시오.

Composer가 비공개 패키지를 해석했는지, 그리고 그 오토로더가 동작하는지 확인하십시오. 먼저 require한 에디션에 대해 composer show <installed-package>를 실행하여 패키지가 설치되었는지 확인하십시오 — 예를 들어 composer show nextpdf/pro, composer show nextpdf/enterprise, 또는 composer show nextpdf/premium입니다.

# Use the package name you actually required:
composer show nextpdf/pro
# or
composer show nextpdf/enterprise
# or
composer show nextpdf/premium

composer show가 패키지와 그 버전을 보고하면 비공개 패키지가 해석된 것입니다. 이어서 composer dump-autoload를 다시 실행하면 오토로더가 깔끔하게 재생성되어 패키지의 클래스를 발견할 수 있게 됩니다.

composer dump-autoload

선택적인 코드 수준 확인으로, 설치한 에디션의 클래스가 오토로드되는지 확인할 수 있습니다. 클래스 이름을 추측하지 마십시오. 설치한 에디션의 API 레퍼런스를 열고 문서화된 공개 클래스를 아무거나 선택한 뒤 그것이 해석되는지 테스트하십시오. 확인할 클래스는 에디션에 따라 다릅니다 — 한 에디션에 포함된 클래스가 다른 에디션에는 없을 수 있으며, 단일 클래스가 오토로드된다는 것은 해당 에디션이 존재함을 증명할 뿐, 모든 에디션이 설치되었음을 증명하지는 않습니다.

<?php
require __DIR__ . '/vendor/autoload.php';

// Replace the placeholder with a documented public class from YOUR edition's
// API reference. Do not hardcode a class from a different edition.
$class = 'Your\\Installed\\Edition\\DocumentedClass';
var_dump(class_exists($class));

패키지를 설치하는 것은 활성화하는 것과 같지 않습니다. 패키지만으로는 Pro나 Enterprise 기능이 부여되지 않습니다 — 활성화하는 서명된 라이선스가 활성 에디션을 선택합니다. 설치에 성공한 뒤에는 라이선스 및 활성화를 따라 라이선스 봉투를 배치하고 활성화하십시오. 또한 ionCube로 인코딩된 빌드의 경우 ionCube Loader를 설정하십시오.

문제 해결

401 Unauthorized 또는 403 Forbidden

Composer가 저장소에 도달했지만 자격 증명이 거부되었거나 충분하지 않습니다. auth.json / COMPOSER_AUTH의 호스트 키가 저장소 호스트와 정확히 일치하는지 (스킴 없음, 경로 없음, 후행 슬래시 없음), 사용자 이름과 토큰이 현재 유효한지, 그리고 토큰이 만료되었거나 포털에서 교체되지 않았는지 확인하십시오. 401은 잘못되었거나 누락된 자격 증명을 가리키며, 403은 유효하지만 그 범위가 요청한 패키지나 에디션을 포함하지 않는 자격 증명을 가리킵니다 — 구독이 require하려는 패키지 이름에 대한 자격을 부여하는지 확인하십시오.

패키지를 찾을 수 없음 / “could not find a matching version”

이는 보통 Composer가 비공개 인덱스를 사용하지 않았거나 도달하지 못했음(그래서 공개 Packagist만 검색함)을, 또는 인덱스에는 도달했지만 일치하는 설치 가능한 패키지나 버전을 찾지 못했음을 의미합니다. repositories.nextpdf 블록이 이 프로젝트의 composer.json에 "type": "composer"와 올바른 URL로 존재하는지, 그리고 정확한 패키지 이름(nextpdf/pro, nextpdf/enterprise, 또는 nextpdf/premium)을 require하고 있는지 확인하십시오. Composer가 보고 있는 내용을 출력하려면 composer config repositories를 실행하십시오. URL의 오타나 누락된 저장소 블록이 흔한 원인이지만, 버전 제약이 게시된 버전과 일치하는지, 프로젝트의 PHP 플랫폼 요구 사항(및 minimum-stability)이 패키지를 허용하는지, 그리고 토큰의 자격이 실제로 require하려는 패키지를 포함하는지도 확인하십시오.

로컬에서는 토큰이 작동하지만 CI에서 실패함

로컬 auth.json이 러너에 존재하지 않습니다. 파일에 의존하는 대신 CI 비밀 정보 저장소에서 COMPOSER_AUTH(방법 B)를 설정하고, composer install이 실행되기 전에 변수가 export되었는지 확인하십시오. 컨테이너화된 빌드에서는 비밀 정보를 이미지 레이어에 지속시키지 않으면서 빌드 시점에 전달하십시오.

잘못된 호스트 키

자격 증명은 호스트를 기준으로 매칭됩니다. 저장소 URL이 https://repo.example.com/nextpdf라면 키는 repo.example.com이어야 합니다 — 전체 URL도 아니고 하위 경로도 아닙니다. 키가 일치하지 않으면 Composer는 요청을 인증되지 않은 상태로 보내며, 이는 401로 나타납니다.