Установка NextPDF Artisan

Краткий обзор

Установите nextpdf/artisan через Composer. Composer также установит runtime-зависимость chrome-php/chrome. Затем обеспечьте PHP-процессу доступ к исполняемому файлу Chrome или Chromium.

Установка

composer require nextpdf/artisan

Пакет объявляет следующие ограничения в composer.json:

Зависимость	Ограничение	Примечания
php	>=8.4 <9.0	Только PHP 8.4
nextpdf/core	^3.0 || ^5.2	Движок NextPDF с открытым исходным кодом
chrome-php/chrome	^1.15	Клиентская библиотека для Chrome DevTools Protocol (CDP); подключается транзитивно
psr/log	^3.0	Необязательная точка внедрения логгера

Composer автоматически подключает chrome-php/chrome. Composer никогда не устанавливает сам исполняемый файл Chrome; этот файл является системной зависимостью.

Подготовка исполняемого файла Chrome

Для моста нужен исполняемый файл Chrome или Chromium. По умолчанию chrome-php/chrome ищет его по стандартным путям. Чтобы закрепить явный путь, задайте его в конфигурации. См. /integrations/artisan/configuration/ и отдельную страницу /integrations/artisan/chrome-renderer-setup/.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Прежде чем подключать исполняемый файл к приложению, убедитесь, что он запускается в безголовом режиме:

chromium --headless --dump-dom about:blank

При успешном запуске команда выводит пустой документ объектной модели документа (DOM) и завершается с кодом 0. Ненулевой код завершения означает, что отсутствует сам исполняемый файл или его разделяемые библиотеки. Устраните это, прежде чем продолжать: во время отрисовки мост проявит тот же сбой как ChromeRenderException.

Проверка подключения пакета

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

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

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

Этот код создаёт средство отрисовки и считывает политику безопасности языка гипертекстовой разметки (HTML) по умолчанию без запуска Chrome. Так вы проверяете, что автозагрузка и привязки контрактов nextpdf/core работают. (Поведение проверяется тестом tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Установка в контейнерах

В Docker песочница Chrome обычно не может запуститься как процесс с идентификатором (PID) 1 / root без дополнительных привилегий ядра. Для этого случая пакет предоставляет переключатель noSandbox. Отключение песочницы Chrome имеет реальную цену с точки зрения безопасности. Страницы /integrations/artisan/security-and-operations/ и /integrations/artisan/chrome-renderer-setup/ описывают эту цену и явно указывают её пределы. Не включайте этот переключатель, не прочитав указанный раздел.

Граничные случаи и подводные камни

• chrome-php/chrome присутствует, но исполняемого файла нет. Composer завершится успешно; уже первая отрисовка выбросит ChromeRenderException и обернёт сбой запуска. Проверка библиотеки отделена от проверки исполняемого файла.
• chrome-php/chrome отсутствует. Если библиотека удалена из автозагрузчика, BrowserPool::getBrowser() выбросит ChromeNotAvailableException с точной командой для устранения проблемы. (Проверяется тестом tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
• Ограничение версии. nextpdf/core: ^3.0 || ^5.2 — Artisan поддерживает обе старшие линии core. Закрепите ту версию core, на которую рассчитано ваше приложение.

Замечания по безопасности

Установка моста добавляет внешний процесс (Chrome) в границу доверия. Изучите /integrations/artisan/security-and-operations/, прежде чем открывать любой путь отрисовки для HTML, предоставленного пользователем.

См. также

• Обзор Artisan: /integrations/artisan/overview/
• Конфигурация Artisan: /integrations/artisan/configuration/
• Быстрый старт Artisan: /integrations/artisan/quickstart/
• Настройка отрисовщика Chrome: /integrations/artisan/chrome-renderer-setup/
• Безопасность и эксплуатация: /integrations/artisan/security-and-operations/