Premium edisi

Memasang dan mengautentikasi paket premium NextPDF privat dengan Composer

Sekilas pandang

Paket premium NextPDF — nextpdf/pro, nextpdf/enterprise, dan metapaket nextpdf/premium — tidak dipublikasikan pada indeks Packagist publik. Paket-paket itu berada di repositori Composer privat yang terikat pada akun Anda, sehingga composer require nextpdf/premium biasa tidak dapat menemukannya sampai Anda memberi tahu Composer dua hal: di mana repositori berada, dan bagaimana mengautentikasi ke sana.

Halaman ini melanjutkan dari titik yang ditinggalkan Pelisensian dan aktivasi. Setelah Anda memiliki kredensial, Anda mengonfigurasi Composer sekali, memasang paket, dan memverifikasinya. Semua yang ada di sini adalah perilaku Composer standar; tidak ada satu pun yang merupakan perkakas khusus NextPDF. Perlakukan token repositori Anda seperti API key, persis seperti halaman lisensi memperlakukan amplop lisensi yang ditandatangani: jaga agar tetap di luar version control publik.

Dari mana kredensial Anda berasal

URL repositori privat, username, dan token Anda diterbitkan setelah Anda memperoleh sebuah lisensi — baik dengan membeli melalui Merchant of Record kami maupun dengan memulai sebuah evaluasi — dari portal lisensi. Untuk jalur pembelian, model dua kontrak (pembelian dibandingkan lisensi), serta siapa yang harus dihubungi untuk urusan penagihan dibandingkan bantuan produk, lihat Pembelian dan pelisensian.

1. Di mana paket premium berada

Portal lisensi Anda menerbitkan dua hal untuk pemasangan:

Sebuah URL repositori Composer privat — endpoint terautentikasi yang menyajikan paket premium.
Sebuah username dan token (pasangan kredensial HTTP Basic) untuk endpoint tersebut.

Di mana pun halaman ini menampilkan host repositori, gantilah dengan URL repositori dari portal lisensi Anda. Di mana pun halaman ini menampilkan username atau token, gantilah dengan kredensial yang diterbitkan untuk akun Anda. NextPDF tidak mempublikasikan satu URL bersama; endpoint dan kredensial bersifat spesifik untuk langganan Anda.

2. Tambahkan repositori privat ke composer.json

Beri tahu Composer tentang repositori dengan satu perintah, dijalankan di root proyek Anda:

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

Ganti https://repo.example.com/nextpdf dengan URL dari portal Anda. Tipe repositori composer mengarahkan Composer ke indeks berformat Composer (sebuah packages.json), yang merupakan apa yang disajikan oleh endpoint paket privat.

Perintah itu menulis sebuah blok repositories ke dalam composer.json. Anda juga dapat menambahkannya secara manual:

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

Definisi repositori bukan rahasia — ia hanya menamai sebuah lokasi, sehingga aman untuk di-commit. Kredensial pada langkah berikutnyalah yang harus Anda lindungi.

3. Autentikasi dengan salah satu dari tiga metode standar

Composer membaca kredensial HTTP Basic untuk sebuah host dari beberapa tempat. Pilih metode yang sesuai dengan tempat Anda melakukan pemasangan.

Metode A — auth.json (pengembangan lokal)

Untuk mesin pengembang, simpan kredensial dalam berkas auth.json di samping composer.json. Gunakan host dari URL repositori Anda sebagai kunci:

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

Ini membuat (atau memperbarui) sebuah auth.json lokal proyek:

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

Kunci host (repo.example.com) harus sama persis dengan host pada URL repositori — Composer mencocokkan kredensial dengan permintaan berdasarkan host.

Metode B — variabel lingkungan COMPOSER_AUTH (CI/CD)

Pada continuous integration biasanya Anda tidak menginginkan berkas di disk. Composer membaca kredensial yang sama dari variabel lingkungan COMPOSER_AUTH, yang nilainya adalah string JSON dengan bentuk yang sama seperti auth.json:

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

Injeksikan COMPOSER_AUTH dari secret store penyedia CI Anda (masked variable, secret, atau vault binding) sehingga token tidak pernah muncul dalam definisi pipeline atau dalam build log.

Metode C — auth per-pengguna global (workstation bersama)

Untuk mengautentikasi setiap proyek bagi pengguna saat ini tanpa berkas per-proyek, tulis kredensial ke dalam auth.json global milik Composer:

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

Ini menyimpan kredensial di bawah direktori home Composer Anda (COMPOSER_HOME, misalnya ~/.composer/auth.json atau ~/.config/composer/auth.json). Kredensial ini berlaku untuk semua proyek yang Anda build sebagai pengguna tersebut, jadi lebih utamakan Metode A atau B ketika sebuah kredensial sebaiknya dicakupkan ke satu proyek atau pipeline.

4. Jaga kredensial tetap di luar version control

URL repositori aman untuk di-commit; token tidak. Dua aturan menjaga rahasia tetap di luar riwayat Anda:

Abaikan berkas auth lokal. Tambahkan auth.json ke .gitignore sehingga kredensial lokal proyek tidak pernah di-commit:
```
/auth.json
```
Injeksikan token di CI/CD. Sediakan COMPOSER_AUTH (Metode B) dari secret store pipeline Anda alih-alih meng-commit auth.json ke repositori atau menanamkannya ke dalam sebuah layer image kontainer.

Jika sebuah token pernah di-commit atau ter-print, rotasikan melalui portal lisensi Anda — perlakukan sebagai terbongkar, persis seperti yang akan Anda lakukan pada API key yang bocor.

5. Pasang dan verifikasi

Setelah repositori dan kredensial tersedia, require edisi yang menjadi hak lisensi Anda:

# 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

Pin sebuah versi major jika proyek Anda lebih menyukai constraint eksplisit — misalnya composer require nextpdf/pro:^3, sesuai dengan constraint yang digunakan oleh halaman modul Pro.

Verifikasi bahwa Composer me-resolve paket privat dan bahwa autoloader-nya bekerja. Pertama, konfirmasikan paket terpasang dengan menjalankan composer show <installed-package> untuk edisi mana pun yang Anda require — misalnya composer show nextpdf/pro, composer show nextpdf/enterprise, atau 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

Jika composer show melaporkan paket dan versinya, paket privat ter-resolve. Menjalankan ulang composer dump-autoload kemudian akan meregenerasi autoloader secara bersih, sehingga kelas-kelas paket dapat ditemukan:

composer dump-autoload

Sebagai pemeriksaan opsional di tingkat kode, Anda dapat mengonfirmasi bahwa sebuah kelas dari edisi yang Anda pasang ter-autoload. Jangan menebak nama kelas: buka referensi API untuk edisi yang Anda pasang dan pilih kelas publik mana pun yang terdokumentasi, lalu uji bahwa ia ter-resolve. Kelas yang harus dicari bergantung pada edisi Anda — sebuah kelas yang dikirim pada satu edisi mungkin tidak ada pada edisi lain, dan satu kelas yang ter-autoload hanya membuktikan bahwa edisi miliknya tersedia, bukan bahwa setiap edisi terpasang.

<?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));

Memasang paket tidak sama dengan mengaktifkannya. Paket itu sendiri tidak memberikan kapabilitas Pro atau Enterprise — lisensi yang ditandatangani dan Anda aktifkan-lah yang memilih edisi aktif. Setelah pemasangan berhasil, ikuti Pelisensian dan aktivasi untuk menempatkan dan mengaktifkan amplop lisensi, dan, untuk build yang dienkode ionCube, siapkan ionCube Loader.

Penanganan masalah

401 Unauthorized atau 403 Forbidden

Composer berhasil mencapai repositori tetapi kredensial ditolak atau tidak mencukupi. Konfirmasikan bahwa kunci host pada auth.json / COMPOSER_AUTH sama persis dengan host repositori (tanpa skema, tanpa path, tanpa garis miring penutup), bahwa username dan token masih berlaku, dan bahwa token belum kedaluwarsa atau dirotasi di portal Anda. 401 menunjuk pada kredensial yang salah atau hilang; 403 menunjuk pada kredensial valid yang cakupan-nya tidak mencakup paket atau edisi yang Anda minta — periksa bahwa langganan Anda memang berhak atas nama paket yang Anda require.

Paket tidak ditemukan / “could not find a matching version”

Ini biasanya berarti Composer tidak menggunakan atau tidak mencapai indeks privat (sehingga ia hanya mencari di Packagist publik), atau ia mencapai indeks tetapi tidak menemukan paket atau versi yang dapat dipasang yang cocok. Konfirmasikan bahwa blok repositories.nextpdf ada di composer.json proyek ini dengan "type": "composer" dan URL yang benar, dan bahwa Anda me-require nama paket yang tepat (nextpdf/pro, nextpdf/enterprise, atau nextpdf/premium). Jalankan composer config repositories untuk mencetak apa yang dilihat Composer. Salah ketik pada URL atau blok repositori yang hilang adalah penyebab umum, tetapi periksa juga bahwa version constraint Anda cocok dengan versi yang dipublikasikan, bahwa PHP platform requirement proyek Anda (dan minimum-stability) mengizinkan paket, dan bahwa entitlement token Anda benar-benar mencakup paket yang Anda require.

Token berfungsi secara lokal tetapi gagal di CI

auth.json lokal tidak ada di runner. Atur COMPOSER_AUTH dari secret store CI Anda (Metode B) alih-alih mengandalkan sebuah berkas, dan pastikan variabel ter-export sebelum composer install berjalan. Pada build berbasis kontainer, teruskan secret saat build time tanpa mempertahankannya ke dalam sebuah layer image.

Kunci host yang salah

Kredensial dicocokkan berdasarkan host. Jika URL repositori adalah https://repo.example.com/nextpdf, kuncinya harus repo.example.com — bukan URL penuh dan bukan subpath. Kunci yang tidak cocok membuat Composer mengirim permintaan tanpa autentikasi, yang muncul sebagai 401.