Skonfiguruj NextPDF i wyrenderuj swój pierwszy plik PDF

NextPDF to biblioteka PHP, która tworzy pliki PDF (Portable Document Format). W tym samouczku zainstalujesz ją w pustym folderze i wyrenderujesz swój pierwszy jednostronicowy dokument. Potrzebujesz terminala i około dziesięciu minut.

Co zbudujesz

Zbudujesz mały projekt zawierający jeden skrypt, 01-hello.php. Skrypt renderuje pojedynczą stronę z pogrubionym wierszem tytułu i jednym akapitem. Zapisuje wynik jako out/hello.pdf. Po drodze poznasz dwa polecenia, które potwierdzają, że instalacja działa prawidłowo.

Ta strona uczy jednej ścieżki instalacji: pusty folder oraz pakiet silnika. Istnieją też inne ścieżki, takie jak adaptery frameworków, renderery przeglądarkowe oraz klient Python. Znajdziesz je w sekcjach Instalacja oraz Wybierz swoją ścieżkę. Dziś nie będą potrzebne.

Krok 1: Utwórz projekt i zainstaluj NextPDF

Composer to menedżer pakietów dla PHP. Pobiera biblioteki do projektu i generuje autoloader. Autoloader to niewielki plik PHP, który odnajduje za Ciebie klasy bibliotek, dzięki czemu nigdy nie piszesz długich list instrukcji include.

Otwórz terminal i uruchom te trzy polecenia:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer wypisuje postęp podczas rozwiązywania zależności i pobierania pakietów. Dokładne wiersze zależą od wersji Composera i lokalnej pamięci podręcznej. Udana instalacja kończy się bez komunikatów o błędach i wygląda mniej więcej tak:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Co się właśnie stało

Composer utworzył w folderze trzy rzeczy. Plik composer.json zapisuje, że projekt zależy od silnika. Plik composer.lock przypina dokładną zainstalowaną wersję, dzięki czemu późniejsza instalacja rozwiązuje ten sam kod. Folder vendor/ przechowuje pobrane pakiety, w tym vendor/autoload.php. Twój skrypt ładuje ten jeden plik i każda klasa silnika staje się dostępna.

Podczas instalacji Composer sprawdził również konfigurację PHP. Silnik deklaruje rozszerzenia PHP, których potrzebuje. Rozszerzenia to opcjonalne moduły wbudowane w PHP. Jeśli któregoś brakuje, Composer zatrzymuje się i wskazuje je zamiast pozostawiać Cię z zepsutą instalacją.

Krok 2: Wyrenderuj swój pierwszy plik PDF

Utwórz plik o nazwie 01-hello.php obok composer.json. Wklej ten kompletny program:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

$document->save(__DIR__ . '/out/hello.pdf');

echo "Wrote out/hello.pdf\n";

Uruchom go:

php 01-hello.php

Zobaczysz dokładnie jeden wiersz:

Wrote out/hello.pdf

Otwórz out/hello.pdf w dowolnej przeglądarce plików PDF. Zobaczysz pogrubiony wiersz tytułu z akapitem pod nim, a większość przeglądarek pokazuje „Hello from NextPDF” w tytule okna.

Co się właśnie stało

Prześledź skrypt od góry do dołu:

require ładuje autoloader Composera, dzięki czemu klasa Document zostaje odnaleziona.
@mkdir tworzy folder out/. Wiodący znak @ wycisza skrypt, gdy folder już istnieje, więc możesz uruchomić go ponownie.
Document::createStandalone() zwraca nowy dokument. Jest przeznaczony do krótkich skryptów wiersza poleceń, dokładnie takich jak ten.
setTitle() ustawia tytuł dokumentu, który przeglądarki pokazują w tytule okna.
addPage() dodaje jedną pustą stronę i umieszcza kursor w lewym górnym rogu.
setFont() wybiera rodzinę czcionek, styl i rozmiar w punktach. Punkty to standardowa jednostka rozmiaru czcionek w druku. 'B' oznacza pogrubienie, a '' oznacza styl zwykły. Rodzina o nazwie helvetica jest wbudowana, więc nie potrzebujesz żadnych plików czcionek.
cell() zapisuje jeden wiersz tekstu w miejscu kursora. Szerokość 0 oznacza „rozciągnij do prawego marginesu”. newLine: true przesuwa kursor w dół po zapisaniu, jak naciśnięcie klawisza Enter.
save() buduje gotowy plik PDF i zapisuje go na dysku.

Jeden dokument tworzy jeden plik. Gdy potrzebujesz drugiego pliku PDF, utwórz nowy dokument, zamiast ponownie wykorzystywać stary.

Krok 3: Zweryfikuj konfigurację

Dwie szybkie kontrole potwierdzają, że ta instalacja będzie działać dłużej niż tylko przy jednym skrypcie.

Najpierw wyświetl listę rozszerzeń dostępnych w Twoim PHP:

php -m

Przejrzyj listę w poszukiwaniu curl, gd, intl, mbstring, openssl oraz zlib. Silnik opiera się na tych sześciu. Composer sprawdził je już w Kroku 1, więc wszystkie powinny się pojawić.

Po drugie, uruchom wbudowaną w silnik kontrolę stanu:

vendor/bin/nextpdf doctor

W systemie Windows wywołaj zamiast tego vendor\bin\nextpdf doctor. Polecenie sprawdza wersję PHP, rozszerzenia, folder tymczasowy oraz konfigurację. Każda kontrola wypisuje [OK], [WARN] lub [FAIL], a następnie jeden ogólny werdykt.

Co się właśnie stało

Przeczytaj najpierw blok Extensions. Sześć wierszy [OK] o nazwach curl, gd, intl, mbstring, openssl oraz zlib oznacza, że instalacja jest gotowa na każdy kolejny samouczek.

Raport wymienia również możliwości silnika. W darmowej instalacji Core możliwości należące do komercyjnych pakietów wypisują [FAIL] wraz z komunikatem wskazującym pakiet, który je udostępnia. Jest to tutaj oczekiwane i może zmienić ogólny werdykt na UNHEALTHY, mimo że Twoja konfiguracja Core jest w porządku. W tych samouczkach istotnym sygnałem jest blok Extensions.

Jeśli coś poszło nie tak

Najpierw dopasuj swój objaw do tych typowych przypadków:

composer: command not found oznacza, że Composera brakuje lub nie ma go na ścieżce PATH. Zainstaluj go ze strony getcomposer.org, a następnie powtórz Krok 1.
Failed opening required '.../vendor/autoload.php' oznacza, że skrypt został uruchomiony poza folderem projektu albo instalacja nie została ukończona. Przejdź do folderu z Kroku 1 i uruchom composer install.
Jeśli Composer zatrzyma się podczas Kroku 1 i wskaże brakujące rozszerzenie PHP, włącz to rozszerzenie w pliku php.ini. Potwierdź to poleceniem php -m, a następnie powtórz instalację.
Wiersz [FAIL] w bloku Extensions narzędzia doctor wskazuje brakujące rozszerzenie PHP. Włącz je w php.ini, potwierdź poleceniem php -m i uruchom doctor ponownie. Wiersze [FAIL] dotyczące możliwości, które wskazują komercyjny pakiet, są oczekiwane w instalacji Core i nie wymagają tutaj żadnych działań.

W przypadku czegokolwiek innego zacznij od bazy wiedzy o rozwiązywaniu problemów. Jeśli skrypt zgłasza wyjątek, odszukaj jego klasę w dokumentacji błędów; większość błędów początkujących pojawia się w błędach ogólnych.

Dalej

Masz działającą instalację i swój pierwszy wyrenderowany plik. Kontynuuj z Tekst, czcionki i podstawy stron, aby kontrolować rozmiary stron, wbudowane czcionki, kolory i wyrównanie.