Cài đặt NextPDF và kết xuất PDF đầu tiên của bạn

NextPDF là một thư viện PHP tạo ra các tệp PDF (Portable Document Format). Trong hướng dẫn này, bạn cài đặt nó vào một thư mục trống và kết xuất tài liệu một trang đầu tiên của mình. Bạn cần một terminal và khoảng mười phút.

Những gì bạn sẽ xây dựng

Bạn sẽ xây dựng một dự án nhỏ chứa một script, 01-hello.php. Script này kết xuất một trang đơn với một dòng tiêu đề in đậm và một đoạn văn. Nó lưu kết quả thành out/hello.pdf. Trong quá trình đó, bạn sẽ học được hai lệnh xác nhận rằng bản cài đặt của bạn hoạt động tốt.

Trang này hướng dẫn một cách cài đặt: một thư mục trống cộng với gói engine. Cũng có những cách khác, chẳng hạn như các bộ chuyển đổi framework, các trình kết xuất dựa trên trình duyệt, và ứng dụng khách Python. Chúng nằm trong Cài đặt và Chọn hướng đi của bạn. Hôm nay bạn không cần đến chúng.

Bước 1: Tạo một dự án và cài đặt NextPDF

Composer là trình quản lý gói cho PHP. Nó tải các thư viện về dự án của bạn và tạo ra một autoloader. Autoloader là một tệp PHP nhỏ tự tìm các lớp thư viện cho bạn, nhờ đó bạn không bao giờ phải viết những danh sách include dài.

Mở một terminal và chạy ba lệnh sau:

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

Composer in ra tiến trình trong khi nó phân giải và tải các gói. Các dòng cụ thể sẽ khác nhau tùy phiên bản Composer và bộ nhớ đệm cục bộ của bạn. Một lần cài đặt thành công kết thúc mà không có văn bản lỗi và trông đại khái như thế này:

./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

Điều gì vừa xảy ra

Composer đã tạo ba thứ trong thư mục của bạn. composer.json ghi lại rằng dự án của bạn phụ thuộc vào engine. composer.lock cố định chính xác phiên bản mà nó đã cài, nhờ đó một lần cài đặt sau này sẽ phân giải ra cùng một mã nguồn. Thư mục vendor/ chứa các gói đã tải về, bao gồm vendor/autoload.php. Script của bạn nạp đúng một tệp đó, và mọi lớp của engine trở nên khả dụng.

Composer cũng đã kiểm tra thiết lập PHP của bạn trong quá trình cài đặt. Engine khai báo các phần mở rộng PHP mà nó cần. Phần mở rộng là các mô-đun tùy chọn được tích hợp sẵn trong PHP. Nếu thiếu một phần mở rộng, Composer sẽ dừng lại và nêu tên nó thay vì bỏ mặc bạn với một bản cài đặt hỏng.

Bước 2: Kết xuất PDF đầu tiên của bạn

Tạo một tệp tên 01-hello.php bên cạnh composer.json. Dán chương trình hoàn chỉnh này vào:

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

Chạy nó:

php 01-hello.php

Bạn sẽ thấy đúng một dòng:

Wrote out/hello.pdf

Mở out/hello.pdf trong bất kỳ trình xem PDF nào. Bạn sẽ thấy dòng tiêu đề in đậm với đoạn văn bên dưới, và hầu hết các trình xem hiển thị “Hello from NextPDF” trên thanh tiêu đề cửa sổ của chúng.

Điều gì vừa xảy ra

Xem qua script từ trên xuống dưới:

• require nạp autoloader của Composer, nhờ đó lớp Document được phân giải.
• @mkdir tạo thư mục out/. Dấu @ ở đầu giữ cho script im lặng khi thư mục đã tồn tại, nhờ đó bạn có thể chạy lại nó.
• Document::createStandalone() trả về một tài liệu mới. Nó được tạo ra cho những script dòng lệnh ngắn đúng như cái này.
• setTitle() đặt tiêu đề tài liệu, thứ mà các trình xem hiển thị trên thanh tiêu đề cửa sổ.
• addPage() thêm một trang trống và đặt con trỏ ở góc trên bên trái.
• setFont() chọn một họ phông chữ, một kiểu dáng, và một cỡ chữ tính theo point. Point là đơn vị chuẩn cho cỡ phông chữ trong in ấn. 'B' nghĩa là in đậm, và '' nghĩa là thường. Họ phông chữ tên helvetica được tích hợp sẵn, nên bạn không cần tệp phông chữ nào.
• cell() viết một dòng văn bản tại con trỏ. Chiều rộng bằng 0 nghĩa là “giãn đến lề phải”. newLine: true di chuyển con trỏ xuống dưới sau đó, giống như nhấn Enter.
• save() dựng PDF hoàn chỉnh và ghi nó ra đĩa.

Một tài liệu tạo ra một tệp. Khi bạn cần một PDF thứ hai, hãy tạo một tài liệu mới thay vì tái sử dụng tài liệu cũ.

Bước 3: Xác minh thiết lập của bạn

Hai lần kiểm tra nhanh xác nhận rằng bản cài đặt này sẽ tiếp tục hoạt động ngoài phạm vi một script.

Đầu tiên, liệt kê các phần mở rộng đi kèm với PHP của bạn:

php -m

Quét danh sách để tìm curl, gd, intl, mbstring, openssl, và zlib. Engine dựa vào sáu phần mở rộng này. Composer đã kiểm tra chúng ở Bước 1, nên tất cả đều sẽ xuất hiện.

Thứ hai, chạy bài kiểm tra sức khỏe của chính engine:

vendor/bin/nextpdf doctor

Trên Windows, thay vào đó hãy gọi vendor\bin\nextpdf doctor. Lệnh này kiểm tra phiên bản PHP, các phần mở rộng, thư mục tạm, và cấu hình của bạn. Mỗi lần kiểm tra in ra [OK], [WARN], hoặc [FAIL], theo sau là một kết luận tổng thể.

Điều gì vừa xảy ra

Hãy đọc khối Extensions trước. Sáu dòng [OK] mang tên curl, gd, intl, mbstring, openssl, và zlib nghĩa là bản cài đặt của bạn đã sẵn sàng cho mọi hướng dẫn tiếp theo.

Báo cáo cũng liệt kê các khả năng của engine. Trên bản cài đặt Core miễn phí, các khả năng thuộc về những gói thương mại sẽ in ra [FAIL] kèm một thông báo nêu tên gói cung cấp chúng. Điều đó là bình thường ở đây, và nó có thể khiến kết luận tổng thể chuyển thành UNHEALTHY dù thiết lập Core của bạn vẫn ổn. Với các hướng dẫn này, khối Extensions mới là tín hiệu quan trọng.

Nếu có điều gì đó không ổn

Trước tiên hãy đối chiếu triệu chứng của bạn với những trường hợp phổ biến sau:

• composer: command not found nghĩa là Composer bị thiếu hoặc không nằm trên PATH của bạn. Hãy cài đặt nó từ getcomposer.org, rồi lặp lại Bước 1.
• Failed opening required '.../vendor/autoload.php' nghĩa là script đã chạy bên ngoài thư mục dự án, hoặc quá trình cài đặt chưa hoàn tất. Hãy chuyển vào thư mục ở Bước 1 và chạy composer install.
• Nếu Composer dừng lại trong Bước 1 và nêu tên một phần mở rộng PHP bị thiếu, hãy bật phần mở rộng đó trong php.ini của bạn. Xác nhận nó bằng php -m, rồi lặp lại quá trình cài đặt.
• Một dòng [FAIL] trong khối Extensions của doctor nêu tên một phần mở rộng PHP bị thiếu. Hãy bật nó trong php.ini, xác nhận bằng php -m, và chạy lại doctor. Các dòng [FAIL] về khả năng có nêu tên một gói thương mại là điều bình thường trên bản cài đặt Core và không cần hành động gì ở đây.

Với mọi trường hợp khác, hãy bắt đầu từ cơ sở kiến thức khắc phục sự cố. Nếu một script phát sinh một exception, hãy tra cứu lớp của nó trong tài liệu tham chiếu lỗi; phần lớn các lỗi của người mới bắt đầu xuất hiện trong các lỗi chung.

Tiếp theo

Bạn đã có một bản cài đặt hoạt động và tệp được kết xuất đầu tiên của mình. Hãy tiếp tục với Văn bản, phông chữ, và những điều cơ bản về trang để kiểm soát kích thước trang, các phông chữ tích hợp sẵn, màu sắc, và căn chỉnh.