Premium Edition

Privates NextPDF-Premium-Paket mit Composer installieren und authentifizieren

Auf einen Blick

Die NextPDF-Premium-Pakete – nextpdf/pro, nextpdf/enterprise und das Metapaket nextpdf/premium – sind nicht im öffentlichen Packagist-Index veröffentlicht. Sie liegen in einem privaten Composer-Repository, das an Ihr Konto gebunden ist, sodass ein schlichtes composer require nextpdf/premium sie nicht finden kann, bis Sie Composer zwei Dinge mitteilen: wo sich das Repository befindet und wie es sich authentifiziert.

Diese Seite knüpft dort an, wo Lizenzierung und Aktivierung aufhört. Sobald Sie über Zugangsdaten verfügen, konfigurieren Sie Composer einmalig, installieren das Paket und überprüfen es. Alles hier ist Standardverhalten von Composer; nichts davon ist NextPDF-spezifisches Werkzeug. Behandeln Sie Ihr Repository-Token wie einen API-Schlüssel, genau wie die Lizenzierungsseite den signierten Lizenzumschlag behandelt: Halten Sie es aus der öffentlichen Versionsverwaltung heraus.

Woher Ihre Zugangsdaten stammen

Ihre private Repository-URL, Ihr Benutzername und Ihr Token werden ausgestellt, nachdem Sie eine Lizenz erhalten haben – entweder durch einen Kauf über unseren Merchant of Record oder durch das Starten einer Evaluierung – über das Lizenzportal. Den Kaufweg, das Zwei-Vertrags-Modell (Kauf versus Lizenz) sowie die zuständigen Ansprechpartner für Abrechnung versus Produktunterstützung finden Sie unter Kauf und Lizenzierung.

1. Wo die Premium-Pakete liegen

Ihr Lizenzportal stellt zwei Dinge für die Installation aus:

Eine URL des privaten Composer-Repositorys – den authentifizierten Endpunkt, der die Premium-Pakete bereitstellt.
Einen Benutzernamen und ein Token (ein HTTP-Basic-Zugangsdatenpaar) für diesen Endpunkt.

Wo immer diese Seite einen Repository-Host zeigt, setzen Sie die Repository-URL aus Ihrem Lizenzportal ein. Wo immer sie einen Benutzernamen oder ein Token zeigt, setzen Sie die für Ihr Konto ausgestellten Zugangsdaten ein. NextPDF veröffentlicht keine einzelne gemeinsame URL; der Endpunkt und die Zugangsdaten sind spezifisch für Ihr Abonnement.

2. Das private Repository zur composer.json hinzufügen

Teilen Sie Composer das Repository mit einem einzigen Befehl mit, ausgeführt im Wurzelverzeichnis Ihres Projekts:

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

Ersetzen Sie https://repo.example.com/nextpdf durch die URL aus Ihrem Portal. Der Repository-Typ composer weist Composer auf einen Index im Composer-Format (eine packages.json) hin, was ein privater Paket-Endpunkt bereitstellt.

Dieser Befehl schreibt einen repositories-Block in die composer.json. Sie können ihn auch von Hand hinzufügen:

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

Die Repository-Definition ist kein Geheimnis – sie benennt lediglich einen Ort, sodass es sicher ist, sie einzuchecken. Die Zugangsdaten im nächsten Schritt sind das, was Sie schützen müssen.

3. Mit einer von drei standardmäßigen Methoden authentifizieren

Composer liest HTTP-Basic-Zugangsdaten für einen Host aus mehreren Quellen. Wählen Sie die Methode, die zu dem Ort passt, an dem Sie installieren.

Methode A – auth.json (lokale Entwicklung)

Speichern Sie die Zugangsdaten für eine Entwicklermaschine in einer auth.json-Datei neben der composer.json. Verwenden Sie den Host Ihrer Repository-URL als Schlüssel:

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

Dies erstellt (oder aktualisiert) eine projektlokale auth.json:

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

Der Host-Schlüssel (repo.example.com) muss exakt mit dem Host in der Repository-URL übereinstimmen – Composer ordnet Zugangsdaten Anfragen anhand des Hosts zu.

Methode B – COMPOSER_AUTH-Umgebungsvariable (CI/CD)

In der Continuous Integration möchten Sie in der Regel keine Datei auf der Platte. Composer liest dieselben Zugangsdaten aus der Umgebungsvariablen COMPOSER_AUTH, deren Wert ein JSON-String mit derselben Form wie die auth.json ist:

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

Speisen Sie COMPOSER_AUTH aus dem Geheimnisspeicher Ihres CI-Anbieters ein (maskierte Variable, Secret oder Vault-Bindung), damit das Token niemals in der Pipeline-Definition oder im Build-Log auftaucht.

Methode C – globale Authentifizierung pro Benutzer (gemeinsam genutzte Workstation)

Um jedes Projekt für den aktuellen Benutzer ohne projektspezifische Datei zu authentifizieren, schreiben Sie die Zugangsdaten in Composers globale auth.json:

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

Dies speichert die Zugangsdaten unter Ihrem Composer-Home-Verzeichnis (COMPOSER_HOME, z. B. ~/.composer/auth.json oder ~/.config/composer/auth.json). Es gilt für alle Projekte, die Sie als dieser Benutzer bauen, sodass Methode A oder B vorzuziehen ist, wenn Zugangsdaten auf ein einzelnes Projekt oder eine einzelne Pipeline beschränkt sein sollen.

4. Zugangsdaten aus der Versionsverwaltung heraushalten

Die Repository-URL kann sicher eingecheckt werden; das Token nicht. Zwei Regeln halten Geheimnisse aus Ihrer Historie heraus:

Ignorieren Sie die lokale Auth-Datei. Fügen Sie auth.json zur .gitignore hinzu, damit projektlokale Zugangsdaten niemals eingecheckt werden:
```
/auth.json
```
Speisen Sie das Token in CI/CD ein. Stellen Sie COMPOSER_AUTH (Methode B) aus dem Geheimnisspeicher Ihrer Pipeline bereit, anstatt eine auth.json ins Repository einzuchecken oder sie in eine Container-Image-Schicht einzubacken.

Falls ein Token jemals eingecheckt oder ausgegeben wird, rotieren Sie es über Ihr Lizenzportal – behandeln Sie es als kompromittiert, genau wie Sie es bei einem durchgesickerten API-Schlüssel täten.

5. Installieren und überprüfen

Mit dem Repository und den Zugangsdaten an Ort und Stelle fordern Sie die Edition an, zu der Ihre Lizenz berechtigt:

# 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

Pinnen Sie eine Hauptversion, wenn Ihr Projekt explizite Constraints bevorzugt – zum Beispiel composer require nextpdf/pro:^3, passend zum Constraint, den die Pro-Modulseiten verwenden.

Überprüfen Sie, dass Composer das private Paket aufgelöst hat und dass dessen Autoloader funktioniert. Bestätigen Sie zunächst, dass das Paket installiert ist, indem Sie composer show <installed-package> für die jeweils angeforderte Edition ausführen – zum Beispiel composer show nextpdf/pro, composer show nextpdf/enterprise oder 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

Wenn composer show das Paket und seine Version meldet, wurde das private Paket aufgelöst. Ein erneuter Lauf von composer dump-autoload regeneriert den Autoloader anschließend sauber, sodass die Klassen des Pakets auffindbar sind:

composer dump-autoload

Als optionale Prüfung auf Code-Ebene können Sie bestätigen, dass eine Klasse aus Ihrer installierten Edition automatisch geladen wird. Raten Sie nicht bei einem Klassennamen: Öffnen Sie die API-Referenz für die installierte Edition und wählen Sie eine beliebige dokumentierte öffentliche Klasse, dann testen Sie, ob sie sich auflöst. Welche Klasse zu suchen ist, hängt von Ihrer Edition ab – eine Klasse, die in einer Edition ausgeliefert wird, ist in einer anderen möglicherweise nicht vorhanden, und eine einzelne ladbare Klasse beweist nur, dass ihre Edition vorhanden ist, nicht dass jede Edition installiert ist.

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

Das Installieren des Pakets ist nicht dasselbe wie das Aktivieren. Das Paket allein gewährt keine Pro- oder Enterprise-Funktionen – die signierte Lizenz, die Sie aktivieren, wählt die aktive Edition. Folgen Sie nach einer erfolgreichen Installation der Seite Lizenzierung und Aktivierung, um den Lizenzumschlag zu platzieren und zu aktivieren, und richten Sie für ionCube-codierte Builds den ionCube-Loader ein.

Fehlerbehebung

401 Unauthorized oder 403 Forbidden

Composer hat das Repository erreicht, aber die Zugangsdaten wurden abgelehnt oder waren unzureichend. Bestätigen Sie, dass der Host-Schlüssel in auth.json / COMPOSER_AUTH exakt mit dem Repository-Host übereinstimmt (kein Schema, kein Pfad, kein abschließender Schrägstrich), dass Benutzername und Token aktuell sind und dass das Token nicht abgelaufen oder in Ihrem Portal rotiert worden ist. Ein 401 weist auf falsche oder fehlende Zugangsdaten hin; ein 403 weist auf gültige Zugangsdaten hin, deren Geltungsbereich das angeforderte Paket oder die angeforderte Edition nicht umfasst – prüfen Sie, ob Ihr Abonnement zu dem von Ihnen angeforderten Paketnamen berechtigt.

Paket nicht gefunden / „could not find a matching version“

Das bedeutet meist, dass Composer den privaten Index nicht verwendet oder nicht erreicht hat (sodass nur das öffentliche Packagist durchsucht wurde) oder den Index erreicht, aber kein installierbares Paket bzw. keine passende Version gefunden hat. Bestätigen Sie, dass der repositories.nextpdf-Block in der composer.json dieses Projekts mit "type": "composer" und der korrekten URL vorhanden ist und dass Sie den exakten Paketnamen anfordern (nextpdf/pro, nextpdf/enterprise oder nextpdf/premium). Führen Sie composer config repositories aus, um auszugeben, was Composer sieht. Ein Tippfehler in der URL oder ein fehlender Repository-Block ist eine häufige Ursache, aber prüfen Sie auch, ob Ihr Versions-Constraint zu einer veröffentlichten Version passt, ob die PHP-Plattformanforderung Ihres Projekts (und minimum-stability) das Paket erlaubt und ob die Berechtigung Ihres Tokens das von Ihnen angeforderte Paket tatsächlich abdeckt.

Token funktioniert lokal, schlägt aber in CI fehl

Die lokale auth.json ist auf dem Runner nicht vorhanden. Setzen Sie COMPOSER_AUTH aus dem Geheimnisspeicher Ihres CI (Methode B), anstatt sich auf eine Datei zu verlassen, und stellen Sie sicher, dass die Variable exportiert wird, bevor composer install ausgeführt wird. Übergeben Sie das Geheimnis in containerisierten Builds zur Build-Zeit, ohne es in eine Image-Schicht zu übernehmen.

Falscher Host-Schlüssel

Zugangsdaten werden über den Host zugeordnet. Lautet die Repository-URL https://repo.example.com/nextpdf, muss der Schlüssel repo.example.com sein – nicht die vollständige URL und kein Unterpfad. Ein nicht passender Schlüssel veranlasst Composer, die Anfrage unauthentifiziert zu senden, was sich als 401 äußert.