Premium edycja

Instalacja i uwierzytelnianie prywatnego pakietu NextPDF Premium za pomocą Composera

W skrócie

Pakiety NextPDF Premium — nextpdf/pro, nextpdf/enterprise oraz metapakiet nextpdf/premium — nie są publikowane w publicznym indeksie Packagist. Żyją w prywatnym repozytorium Composera powiązanym z Twoim kontem, więc zwykłe composer require nextpdf/premium nie odnajdzie ich, dopóki nie wskażesz Composerowi dwóch rzeczy: gdzie znajduje się repozytorium oraz jak się do niego uwierzytelnić.

Ta strona podejmuje wątek tam, gdzie kończy go Licencjonowanie i aktywacja. Gdy masz już poświadczenia, konfigurujesz Composer jednorazowo, instalujesz pakiet i go weryfikujesz. Wszystko, co tu opisano, to standardowe zachowanie Composera; nic z tego nie jest narzędziem specyficznym dla NextPDF. Traktuj token repozytorium jak klucz API, dokładnie tak, jak strona o licencjonowaniu traktuje podpisaną kopertę licencyjną: trzymaj go poza publicznym systemem kontroli wersji.

Skąd pochodzą Twoje poświadczenia

Adres URL Twojego prywatnego repozytorium, nazwa użytkownika i token są wydawane po uzyskaniu licencji — czy to przez zakup za pośrednictwem naszego Merchant of Record, czy przez rozpoczęcie ewaluacji — z portalu licencyjnego. Ścieżkę zakupu, model dwóch umów (zakup a licencja) oraz informacje o tym, do kogo zwrócić się w sprawach rozliczeń, a do kogo w sprawach produktu, znajdziesz w sekcji Zakup i licencjonowanie.

1. Gdzie żyją pakiety premium

Twój portal licencyjny wydaje dwie rzeczy potrzebne do instalacji:

Adres URL prywatnego repozytorium Composera — uwierzytelniony punkt końcowy, który udostępnia pakiety premium.
Nazwę użytkownika i token (parę poświadczeń HTTP Basic) dla tego punktu końcowego.

Wszędzie tam, gdzie ta strona pokazuje hosta repozytorium, podstaw adres URL repozytorium z Twojego portalu licencyjnego. Wszędzie tam, gdzie pokazuje nazwę użytkownika lub token, podstaw poświadczenia wydane dla Twojego konta. NextPDF nie publikuje jednego współdzielonego adresu URL; punkt końcowy i poświadczenia są specyficzne dla Twojej subskrypcji.

2. Dodaj prywatne repozytorium do composer.json

Powiadom Composer o repozytorium jednym poleceniem, uruchomionym w katalogu głównym projektu:

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

Zastąp https://repo.example.com/nextpdf adresem URL z Twojego portalu. Typ repozytorium composer wskazuje Composerowi indeks w formacie Composera (plik packages.json), czyli to, co udostępnia prywatny punkt końcowy pakietu.

To polecenie zapisuje blok repositories do composer.json. Możesz dodać go także ręcznie:

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

Definicja repozytorium nie jest sekretem — wskazuje jedynie lokalizację, więc bezpiecznie jest ją zatwierdzić w repozytorium. To poświadczenia z następnego kroku musisz chronić.

3. Uwierzytelnij się jedną z trzech standardowych metod

Composer odczytuje poświadczenia HTTP Basic dla hosta z kilku miejsc. Wybierz metodę odpowiadającą temu, gdzie przeprowadzasz instalację.

Metoda A — auth.json (programowanie lokalne)

Na maszynie deweloperskiej przechowuj poświadczenie w pliku auth.json obok composer.json. Jako klucza użyj hosta z adresu URL repozytorium:

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

To tworzy (lub aktualizuje) lokalny dla projektu plik auth.json:

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

Klucz hosta (repo.example.com) musi dokładnie pasować do hosta w adresie URL repozytorium — Composer dopasowuje poświadczenia do żądań po hoście.

Metoda B — zmienna środowiskowa COMPOSER_AUTH (CI/CD)

W ciągłej integracji zwykle nie chcesz pliku na dysku. Composer odczytuje te same poświadczenia ze zmiennej środowiskowej COMPOSER_AUTH, której wartością jest łańcuch JSON o tym samym kształcie co auth.json:

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

Wstrzyknij COMPOSER_AUTH z magazynu sekretów dostawcy CI (zamaskowana zmienna, sekret lub powiązanie z vaultem), aby token nigdy nie pojawił się w definicji potoku ani w dzienniku kompilacji.

Metoda C — globalne uwierzytelnianie per użytkownik (współdzielona stacja robocza)

Aby uwierzytelnić każdy projekt bieżącego użytkownika bez pliku na poziomie projektu, zapisz poświadczenie do globalnego pliku auth.json Composera:

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

To przechowuje poświadczenie w katalogu domowym Composera (COMPOSER_HOME, np. ~/.composer/auth.json lub ~/.config/composer/auth.json). Ma ono zastosowanie do wszystkich projektów, które kompilujesz jako ten użytkownik, więc preferuj Metodę A lub B, gdy poświadczenie powinno być ograniczone do jednego projektu lub potoku.

4. Trzymaj poświadczenia poza systemem kontroli wersji

Adres URL repozytorium można bezpiecznie zatwierdzić; tokenu — nie. Dwie reguły utrzymują sekrety poza Twoją historią:

Ignoruj lokalny plik auth. Dodaj auth.json do .gitignore, aby poświadczenie lokalne dla projektu nigdy nie zostało zatwierdzone:
```
/auth.json
```
Wstrzykuj token w CI/CD. Dostarczaj COMPOSER_AUTH (Metoda B) z magazynu sekretów potoku, zamiast zatwierdzać auth.json w repozytorium lub wpiekać go w warstwę obrazu kontenera.

Jeśli token kiedykolwiek zostanie zatwierdzony lub wypisany, zrotuj go przez portal licencyjny — traktuj go jako skompromitowany, dokładnie tak, jak zrobiłbyś to z wyciekniętym kluczem API.

5. Instalacja i weryfikacja

Mając na miejscu repozytorium i poświadczenia, dodaj jako zależność edycję, do której uprawnia Twoja licencja:

# 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

Przypnij główną wersję, jeśli Twój projekt preferuje jawne ograniczenia — na przykład composer require nextpdf/pro:^3, zgodnie z ograniczeniem stosowanym na stronach modułu Pro.

Sprawdź, czy Composer rozwiązał prywatny pakiet i czy działa jego autoloader. Najpierw potwierdź, że pakiet jest zainstalowany, uruchamiając composer show <installed-package> dla edycji, którą dodałeś jako zależność — na przykład composer show nextpdf/pro, composer show nextpdf/enterprise lub 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

Jeśli composer show raportuje pakiet i jego wersję, prywatny pakiet został rozwiązany. Ponowne uruchomienie composer dump-autoload regeneruje wtedy autoloader na czysto, dzięki czemu klasy pakietu stają się wykrywalne:

composer dump-autoload

Jako opcjonalną kontrolę na poziomie kodu możesz potwierdzić, że klasa z zainstalowanej edycji jest ładowana automatycznie. Nie zgaduj nazwy klasy: otwórz dokumentację API dla zainstalowanej edycji i wybierz dowolną udokumentowaną klasę publiczną, a następnie sprawdź, czy się rozwiązuje. Klasa, której należy szukać, zależy od edycji — klasa dostarczana w jednej edycji może nie być obecna w innej, a automatyczne załadowanie pojedynczej klasy dowodzi jedynie, że obecna jest jej edycja, a nie że zainstalowana jest każda edycja.

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

Zainstalowanie pakietu to nie to samo, co jego aktywacja. Sam pakiet nie przyznaje możliwości Pro ani Enterprise — podpisana licencja, którą aktywujesz, wybiera aktywną edycję. Po udanej instalacji wykonaj kroki z Licencjonowanie i aktywacja, aby umieścić i aktywować kopertę licencyjną, a w przypadku kompilacji zakodowanych przez ionCube skonfiguruj Loader ionCube.

Rozwiązywanie problemów

401 Unauthorized lub 403 Forbidden

Composer dotarł do repozytorium, ale poświadczenia zostały odrzucone lub były niewystarczające. Potwierdź, że klucz hosta w auth.json / COMPOSER_AUTH dokładnie pasuje do hosta repozytorium (bez schematu, bez ścieżki, bez końcowego ukośnika), że nazwa użytkownika i token są aktualne oraz że token nie wygasł ani nie został zrotowany w Twoim portalu. 401 wskazuje na błędne lub brakujące poświadczenie; 403 wskazuje na poprawne poświadczenie, którego zakres nie obejmuje pakietu lub edycji, o które prosisz — sprawdź, czy Twoja subskrypcja uprawnia do nazwy pakietu, który dodajesz jako zależność.

Nie znaleziono pakietu / „could not find a matching version”

Zwykle oznacza to, że Composer nie użył lub nie dotarł do prywatnego indeksu (więc przeszukał jedynie publiczny Packagist), albo dotarł do indeksu, lecz nie znalazł żadnego instalowalnego pakietu lub wersji, które pasują. Potwierdź, że blok repositories.nextpdf istnieje w pliku composer.json tego projektu z "type": "composer" i poprawnym adresem URL oraz że dodajesz jako zależność dokładną nazwę pakietu (nextpdf/pro, nextpdf/enterprise lub nextpdf/premium). Uruchom composer config repositories, aby wypisać to, co widzi Composer. Literówka w adresie URL lub brakujący blok repozytorium to częsta przyczyna, ale sprawdź też, czy Twoje ograniczenie wersji pasuje do opublikowanej wersji, czy wymaganie platformy PHP Twojego projektu (oraz minimum-stability) dopuszcza pakiet oraz czy uprawnienie Twojego tokenu faktycznie obejmuje pakiet, który dodajesz jako zależność.

Token działa lokalnie, ale zawodzi w CI

Lokalnego auth.json nie ma na runnerze. Ustaw COMPOSER_AUTH z magazynu sekretów CI (Metoda B), zamiast polegać na pliku, i upewnij się, że zmienna jest wyeksportowana przed uruchomieniem composer install. W kompilacjach kontenerowych przekazuj sekret w czasie kompilacji bez utrwalania go w warstwie obrazu.

Błędny klucz hosta

Poświadczenia dopasowywane są po hoście. Jeśli adres URL repozytorium to https://repo.example.com/nextpdf, kluczem musi być repo.example.com — nie pełny adres URL i nie podścieżka. Niedopasowany klucz sprawia, że Composer wysyła żądanie nieuwierzytelnione, co objawia się jako 401.