NextPDF Pro hızlı başlangıç

Bir bakışta

Bir NextPDF Pro lisans zarfınız var. Bu öğretici, onu dört kısa adımda ilk doğrulanmış sonuca dönüştürür. Özel depodan nextpdf/pro paketini kurar, lisansınızı etkinleştirir, çalışma zamanının çözümlediği yetkiyi onaylar, ardından şablonlu bir PDF oluşturup imzalarsınız. Her adım görmeniz gereken çıktıyı gösterir.

Bu yetenek NextPDF Pro (nextpdf/pro) ile gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Ön koşullar

• PHP 8.4 ve Composer 2. Premium paketler PHP >=8.4 <9.0 gerektirir.
• Özel depo kimlik bilgileri. Portalınız bir depo URL’si, kullanıcı adı ve token verir. Kurulum, Kurulum ve kimlik doğrulama sayfasında ele alınır.
• Lisans zarfınız. app.getnextpdf.com adresindeki hesabınızda oturum açın, lisans sözleşmesini imzalayın ve dağıtımınız için imzalı zarfı indirin. Onu bir API anahtarı gibi ele alın.
• ionCube Loader (yalnızca kodlanmış yapılar). Pro denemesi ile ücretli, ionCube ile kodlanmış Pro yapısı, PHP 8.4 için Loader’a ihtiyaç duyar — bkz. ionCube kurulumu.

1. Kurulum ve etkinleştirme

Composer’ı özel deponuza yönlendirin, kimlik doğrulaması yapın ve paketi require edin:

composer config repositories.nextpdf composer https://repo.example.com/nextpdf
composer config --auth http-basic.repo.example.com your-username your-token
composer require nextpdf/pro:^3

Depo URL’sini ve kimlik bilgilerini portalınızdakilerle değiştirin. Üç kimlik doğrulama yönteminin tümü (proje auth.json, COMPOSER_AUTH, global auth) Kurulum ve kimlik doğrulama sayfasında açıklanır.

Ardından, imzalı lisans zarfını yapılandırma kuralınıza uyarak dağıtımınızın onu yüklediği yere yerleştirin ve entegrasyonunuzun etkinleştirme adımını çalıştırın — çoğu framework bunu bir konsol komutu olarak sunar. Örtük olarak, çevrimiçi etkinleştirme, lisanslama yüzeyinde tek bir çağrıdır:

public function activate(string $licenseJws, string $deploymentId, ?string $machineFingerprintHash = null, ?string $expectedLicenseId = null, ?string $clientNonce = null): StatusResponse

Şu durumlarda hata fırlatır veya başarısız olur: bir aktarım hatası, 200 dışı bir durum ya da hatalı sağlanan bir nonce durumunda NextPDF\Enterprise\Licensing\LicenseClientException ve herhangi bir imzalı durum doğrulama hatasında NextPDF\Accelerator\Exception\SpectrumAuthenticationException. ionCube kanalında lisans ayrıca düzenli olarak çevrimiçi doğrulanır; signed-source kanalı yerel olarak doğrular — bkz. İki teslim kanalı.

2. Yetkinizi doğrulayın

Yetki değerlendiricisine — lisans kararlarının tek yetkilisi — zarfınızın neye çözümlendiğini sorun. $license, entegrasyonunuzun lisanslama bootstrap’inin sunduğu doğrulanmış NextPDF\Enterprise\Licensing\LicenseKey’dir; null, fail-closed lisanssız sonucunu gösterir.

use NextPDF\Enterprise\Licensing\EntitlementEvaluator;

$result = (new EntitlementEvaluator())->evaluate($license);

printf("status:   %s\n", $result->status->value);
printf("edition:  %s\n", $result->edition?->value ?? '(none)');
printf("channel:  %s\n", $result->channel->value);
printf("branding: %s\n", $result->brandingMode->value);
printf("runtime:  %s\n", $result->runtimeAllowed ? 'allowed' : 'disabled');

Arkasındaki metot (hata fırlatmaz):

public function evaluate(?LicenseKey $license, ?DateTimeImmutable $now = null): EntitlementResult

Etkin, ücretli bir Pro lisansıyla şunu beklersiniz:

status:   active
edition:  pro
channel:  paid
branding: none
runtime:  allowed

Bir deneme veya değerlendirme lisansında bunun yerine channel: evaluation ve branding: evaluation beklersiniz. Her Pro yeteneği yine de çalışır ve oluşturulan çıktı, tasarım gereği görünür bir değerlendirme filigranı taşır. Ücretli bir lisans, kod değişikliği olmadan bunu kaldırır — bkz. Deneme ve değerlendirme markalaması.

3. İlk sonuç

Şimdi eğlenceli kısım: bir JSON şablonunu ayrıştırın, verinizi tür duyarlı biçimlendirmeyle bağlayın, bağlanan değerleri oluşturun ve belgeyi imzalayın. Bunu vendor/ dizininizin yanına quickstart.php olarak kaydedin ve php quickstart.php komutunu çalıştırın. PKCS#12 dosyası (signing-cert.p12) olarak bir imzalama sertifikasına ihtiyacınız var; bu öğretici için kendinden imzalı bir tanesi yeterlidir. Üretim imzalaması, uygun şekilde korunan bir özel anahtar, gerçek bir sertifika zinciri ve alıcılarınızın kabul ettiği bir güven politikası gerektirir — kendinden imzalı imzalar, güvenilir alıcı iş akışları için uygun değildir.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

// Parse a JSON template: one A4 page, three positioned placeholders.
$template = (new TemplateParser())->parse(<<<'JSON'
{
    "name": "welcome-letter",
    "pageSize": "A4",
    "orientation": "P",
    "placeholders": [
        {"name": "customer", "type": "text",     "x": 25, "y": 60, "width": 160, "height": 10},
        {"name": "issued",   "type": "date",     "x": 25, "y": 72, "width": 80,  "height": 10},
        {"name": "total",    "type": "currency", "x": 25, "y": 84, "width": 80,  "height": 10, "format": "EUR "}
    ]
}
JSON);

// Bind data. Keys match placeholder names case-insensitively.
$binding = (new TemplateDataBinder())->bind($template, [
    'customer' => 'Aurora Paper Co.',
    'issued'   => '2026-07-03',
    'total'    => 1249.5,
]);

printf(
    "Bound %d of %d placeholders (%d missing, %d warnings)\n",
    $binding->count(),
    count($template->placeholders),
    count($binding->missingFields),
    count($binding->warnings),
);

// Render the bound values with the Core document API.
$doc = Document::createStandalone();
$doc->setTitle('Welcome letter');
$doc->addPage();
$doc->setFont('helvetica', '', 12);

foreach ($binding->bindings as $bound) {
    $doc->text($bound->placeholder->x, $bound->placeholder->y, $bound->formattedValue);
}

// Apply a PAdES B-B baseline signature, then save once.
$doc->setSignature(
    CertificateInfo::fromPkcs12(__DIR__ . '/signing-cert.p12', (string) getenv('NEXTPDF_P12_PASSWORD')),
    SignatureLevel::PAdES_B_B,
);

$doc->save(__DIR__ . '/welcome-letter-signed.pdf');

echo "Created: welcome-letter-signed.pdf\n";

Beklenen çıktı:

Bound 3 of 3 placeholders (0 missing, 0 warnings)
Created: welcome-letter-signed.pdf

welcome-letter-signed.pdf dosyasını bir PDF okuyucuda açın: üç bağlı değer şablon konumlarında görünür (issued, Y-m-d biçiminde; total, EUR 1,249.50 olarak) ve okuyucunun imza paneli tek bir imza gösterir. Yayılan yapı, PAdES taban B-B profilini izler; NextPDF bunu bir sertifikasyon olarak değil, bir yetenek olarak belgeler — kapsam ve uygunluk duruşu PAdES seviyeleri sayfasında yer alır. Şablon JSON’u hatalı biçimlendirilmişse, TemplateParser::parse(), Template validation failed: önekli bir mesajla InvalidArgumentException fırlatır.

Az önce kullandığınız temel imzalar, birebir:

public function parse(string $json): TemplateDefinition
public function bind(TemplateDefinition $template, array $data): BindingResult
public static function fromPkcs12(string $p12Path, #[SensitiveParameter] string $password = ''): self
public function setSignature(CertificateInfo $certInfo, SignatureLevel $level = SignatureLevel::PAdES_B_B, ?TsaClient $tsaClient = null, ?ClientInterface $httpClient = null): static
public function save(string $path): void

Şu durumlarda hata fırlatır veya başarısız olur: parse() — JSON geçersiz olduğunda veya beklenen yapıya uymadığında InvalidArgumentException; fromPkcs12() — dosya okunamadığında veya ayrıştırılamadığında NextPDF\Exception\SignatureException; setSignature() — doğrusallaştırma zaten etkinleştirilmişse NextPDF\Exception\InvalidConfigException (PAdES ve Fast Web View birbirini dışlar); save() — dosya yazılamadığında NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException veya NextPDF\Exception\CompressionException. bind() hata fırlatmaz; bunun yerine missingFields ve warnings bildirir.

4. Bir şey başarısız olduğunda

Composer nextpdf/pro paketini bulamıyor veya getiremiyor

composer require sırasında bir 401/403 ya da “could not be found” hatası, özel deponun veya kimlik bilgilerinin bu proje için yapılandırılmadığı anlamına gelir. auth.json içindeki host anahtarı, depo URL’sinin host’uyla tam olarak eşleşmelidir. Kurulum ve kimlik doğrulama sayfasını baştan sona uygulayın.

Çalışma zamanı lisans olmadığını bildiriyor

2. adım status: no_license, runtime: disabled ve değerlendiricinin uyarısını yazdırır — ham premium çalışma zamanı mesajı (her iki sürüm tarafından paylaşılır) şudur: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Premium özellikler, doğrulanmış bir zarf olmadan fail-closed olur. Mevcut ama bozuk bir zarf dosyası hiçbir zaman yok sayılmaz — License file is present but unreadable: ... veya License file is present but empty: ... gibi mesajlarla NextPDF\Enterprise\Licensing\Storage\LicenseStorageException fırlatır. Zarfı yapılandırılmış yola yerleştirin ve PHP işlem kullanıcısı tarafından okunabilir yapın.

İmzalama sertifikası yüklenmiyor

CertificateInfo::fromPkcs12(), .p12 dosyası okunamadığında veya ayrıştırılamadığında NextPDF\Exception\SignatureException fırlatır. Olağan nedenler yanlış bir yol, yanlış bir parola (NEXTPDF_P12_PASSWORD değerini kontrol edin) ya da gerçekte PKCS#12 olmayan bir dosyadır. openssl pkcs12 -info -in signing-cert.p12 -noout ile doğrulayın.

Bundan sonra nereye gidilir

• Şablon — tam şablon tanımı ve bağlama referansı.
• Bir PDF’i PAdES B-B ile imzalayın, ardından PAdES B-T’ye genişletin — imzanıza bir RFC 3161 zaman damgası ekleyin.
• NextPDF Pro yetenekleri — Pro lisansınızın içerdiği her şey.
• İki teslim kanalı — ionCube çevrimiçi kiralama ile tamamen çevrimdışı signed source karşılaştırması.
• Deneme ve değerlendirme markalaması — değerlendirme filigranının nasıl göründüğü ve ücretli bir lisansın onu nasıl kaldırdığı.