Premium エディション

Composer で NextPDF Premium のプライベートパッケージをインストールして認証する

概要

NextPDF のプレミアムパッケージ――nextpdf/pro、nextpdf/enterprise、および nextpdf/premium メタパッケージ――は、公開 Packagist インデックスには公開されていません。これらはアカウントに紐づくプライベートな Composer リポジトリに存在するため、素の composer require nextpdf/premium では、Composer に 2 つのこと―― どこにリポジトリがあるか、そしてどのように認証するか――を伝えるまで、これらを見つけることができません。

このページは、ライセンスとアクティベーションの続きから始まります。認証情報を入手したら、Composer を一度設定し、パッケージをインストールして検証します。ここで扱う内容はすべて標準的な Composer の動作であり、NextPDF 固有のツールは一切ありません。ライセンスページが署名済みライセンスエンベロープを扱うのとまったく同様に、リポジトリトークンは API キーと同じように扱い、公開バージョン管理の外に保ってください。

認証情報の入手元

プライベートリポジトリの URL、ユーザー名、トークンは、ライセンスを取得した後に―― Merchant of Record 経由で購入するか、評価版を開始するかのいずれかで―― ライセンスポータルから発行されます。購入経路、2 契約モデル（購入とライセンス）、および請求と製品ヘルプのそれぞれの連絡先については、購入とライセンスを参照してください。

1. プレミアムパッケージの所在

ライセンスポータルは、インストールのために 2 つのものを発行します。

プライベートな Composer リポジトリの URL ――プレミアムパッケージを提供する認証済みエンドポイントです。
そのエンドポイント向けのユーザー名とトークン（HTTP Basic 認証情報のペア）です。

このページでリポジトリのホストを示している箇所はすべて、ライセンスポータルのリポジトリ URL に置き換えてください。ユーザー名やトークンを示している箇所はすべて、アカウントに発行された認証情報に置き換えてください。NextPDF は単一の共有 URL を公開しておらず、エンドポイントと認証情報はサブスクリプションごとに固有です。

2. composer.json にプライベートリポジトリを追加する

プロジェクトのルートで実行する 1 つのコマンドで、リポジトリを Composer に伝えます。

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

https://repo.example.com/nextpdf をポータルの URL に置き換えてください。 composer リポジトリタイプは、Composer 形式のインデックス（packages.json）を指し示すもので、これがプライベートパッケージエンドポイントが提供するものです。

このコマンドは composer.json に repositories ブロックを書き込みます。手作業で追加することもできます。

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

リポジトリ定義はシークレットではありません。場所を指定しているだけなので、コミットしても安全です。次のステップの認証情報こそが保護すべきものです。

3. 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 プロバイダーのシークレットストア（マスク済み変数、シークレット、または vault バインディング）から 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）に保存します。これはそのユーザーとしてビルドするすべてのプロジェクトに適用されるため、認証情報を 1 つのプロジェクトやパイプラインにスコープすべき場合は方法 A または B を優先してください。

4. 認証情報をバージョン管理外に保つ

リポジトリ URL はコミットしても安全ですが、トークンはそうではありません。次の 2 つのルールがシークレットを履歴の外に保ちます。

ローカルの認証ファイルを無視する。 プロジェクトローカルの認証情報が決してコミットされないように、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

プロジェクトが明示的な制約を好む場合はメジャーバージョンを固定してください――たとえば composer require nextpdf/pro:^3 で、Pro モジュールのページが使用している制約に一致します。

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 リファレンスを開き、文書化された公開クラスを任意に 1 つ選んで、それが解決されることをテストします。探すべきクラスはエディションによって異なります―― あるエディションに同梱されるクラスが別のエディションには存在しない場合があり、単一のクラスがオートロードされることは、そのエディションが存在することを証明するだけで、すべてのエディションがインストールされていることを証明するものではありません。

<?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 したパッケージやエディションを含まない有効な認証情報を示します――サブスクリプションが require しているパッケージ名を付与しているか確認してください。

パッケージが見つからない/「could not find a matching version」

これは通常、Composer がプライベートインデックスを使用しなかったか到達しなかった（そのため公開 Packagist のみを検索した）こと、またはインデックスには到達したが一致するインストール可能なパッケージやバージョンが見つからなかったことを意味します。このプロジェクトの composer.json に repositories.nextpdf ブロックが "type": "composer" と正しい URL で存在すること、そして正確なパッケージ名（nextpdf/pro、 nextpdf/enterprise、または nextpdf/premium）を require していることを確認してください。composer config repositories を実行すると Composer が認識している内容が出力されます。URL のタイプミスやリポジトリブロックの欠落はよくある原因ですが、 バージョン制約が公開バージョンと一致すること、プロジェクトの PHP プラットフォーム要件（および minimum-stability）がパッケージを許可すること、そして トークンのエンタイトルメントが require しているパッケージを実際にカバーしていることも確認してください。

トークンはローカルでは機能するが CI で失敗する

ローカルの auth.json はランナー上に存在しません。ファイルに頼るのではなく CI シークレットストアから COMPOSER_AUTH（方法 B）を設定し、変数が composer install の実行前にエクスポートされていることを確認してください。コンテナ化されたビルドでは、シークレットをイメージレイヤーに残さずにビルド時に渡してください。

誤ったホストキー

認証情報はホストで照合されます。リポジトリ URL が https://repo.example.com/nextpdf であれば、キーは repo.example.com でなければなりません――完全な URL でもサブパスでもありません。キーが一致しないと Composer はリクエストを未認証で送信し、それが 401 として現れます。