Конфигурация пакета NextPDF для Laravel

Кратко

config/nextpdf.php публикуется командой php artisan vendor:publish --tag=nextpdf-config. Для каждого ключа предусмотрены переменная окружения для переопределения и жёстко заданное значение по умолчанию. На этой странице ключи перечислены в том виде, в каком они присутствуют в файле config/nextpdf.php пакета.

Установка

php artisan vendor:publish --tag=nextpdf-config

В register() провайдер также объединяет значения по умолчанию пакета под ключом конфигурации nextpdf. После этого незаданные ключи используют значения, приведённые ниже, даже до публикации файла конфигурации.

Концептуальный обзор

Большинство переменных окружения поддерживают либо имя NEXTPDF_*, либо устаревшее имя TCPDF_*. Устаревший префикс доступен в течение переходного периода, описанного в UPGRADE.md. Для новых развёртываний используйте NEXTPDF_*. Файл конфигурации определяет значения в таком порядке: переменная окружения → значение из опубликованного файла → значение по умолчанию пакета.

Поверхность API — ключи конфигурации

Макет документа

Ключ	Env (основная)	По умолчанию	Эффект
page_format	NEXTPDF_PAGE_FORMAT	A4	Формат страницы по умолчанию: A4, A3, A5, Letter, Legal или Tabloid
orientation	NEXTPDF_ORIENTATION	P	Книжная (P) или альбомная (L) ориентация
unit	NEXTPDF_UNIT	mm	Единица измерения: pt, mm, cm или in
defaults.creator	NEXTPDF_CREATOR	NextPDF	Метаданные о создателе документа; применяются к PdfDocumentInterface-привязке
defaults.author	NEXTPDF_AUTHOR	(пусто)	Метаданные автора; применяются только если значение непустое
defaults.language	NEXTPDF_LANG	en	Язык документа; применяется к привязке документа
defaults.margin_top / _right / _bottom / _left	—	10	Поля по умолчанию
defaults.font_family	—	dejavusans	Семейство шрифтов по умолчанию
defaults.font_size	—	12	Размер шрифта по умолчанию
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] в пунктах или null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] в пунктах или null

Провайдер применяет defaults.creator, defaults.language и (если задан) defaults.author к каждому заново разрешённому документу. Если значение пустое, провайдер пропускает defaults.author.

Архивирование и цвет

Ключ	Env (основная)	По умолчанию	Эффект
pdfa	NEXTPDF_PDFA	null	Уровень архивирования PDF/A: null, 4, 4e или 4f. Ненулевое значение включает PDF/A для привязки документа и требует nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Каталог для дополнительных шрифтов TrueType; задаёт путь поиска реестра шрифтов
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Каталог кэша разобранных шрифтов и временных файлов
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Путь к ICC-профилю RGB; обязателен для PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Необязательный ICC-профиль CMYK для печатных процессов
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Использовать flock для кэша шрифтов, чтобы предотвратить повреждение из-за одновременной записи параллельными обработчиками очереди

Ненулевое значение pdfa требует Premium. Без nextpdf/premium разрешение привязки документа с заданным pdfa вызывает ошибку “класс не найден” для типа версии PDF/A. Эта страница не описывает поведение архивирования Premium. См. документацию Premium.

Память обработчика (долгоживущие среды выполнения)

Ключ	Env (основная)	По умолчанию	Эффект
preload_fonts	—	[]	Абсолютные пути к файлам шрифтов, разбираемым при запуске обработчика. После прогрева реестр шрифтов блокируется
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Бюджет кэша изображений по схеме «вытеснение давно неиспользуемых» (LRU) в мегабайтах (МБ). 0 отключает кэширование. На уровне провайдера верхняя граница не задаётся

Провайдер не задаёт верхнюю границу для бюджета кэша изображений. Чтобы ограничить его, используйте лимит памяти контейнера или php.inimemory_limit. Файл конфигурации рекомендует практический максимум 256 МБ.

Цифровая подпись (Premium)

Ключ	Env (основная)	По умолчанию	Эффект
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Когда значение false или сертификат пуст, SignerInterface разрешается в null
signature.certificate	NEXTPDF_SIGN_CERT	null	Путь к сертификату подписи
signature.private_key	NEXTPDF_SIGN_KEY	null	Путь к закрытому ключу
signature.password	NEXTPDF_SIGN_PASSWORD	(пусто)	Парольная фраза для ключа
signature.extra_certs	—	[]	Пути к сертификатам промежуточных ЦС
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Базовый уровень усовершенствованной электронной подписи для PDF (PAdES), передаваемый в модуль подписи

Описываемый здесь пакет Core не поставляет реализацию модуля подписи; SignerInterface разрешается в null, пока его не предоставит nextpdf/premium. При наличии Premium level: B-B создаёт базовую подпись PAdES B-B. Более высокие базовые уровни PAdES зависят от настроенной службы меток времени и возможностей Premium; эта страница их не описывает.

Служба меток времени

Ключ	Env (основная)	По умолчанию	Эффект
tsa.url	NEXTPDF_TSA_URL	null	Конечная точка службы меток времени (TSA). Когда значение пусто, TsaClient разрешается в null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(пусто)	HTTP-учётные данные TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Клиентский сертификат / ключ для взаимной аутентификации TLS (mTLS) при подключении к TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	HTTP-таймаут в секундах для клиента PSR-18
tsa.pinned_public_keys	—	[]	Закрепления (pins) SubjectPublicKeyInfo (SPKI) в формате Base64 SHA-256 (RFC 7469). Пустое значение отключает закрепление
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Выводить предупреждение, когда TSA предъявляет незакреплённый SPKI
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Разрешить незашифрованный HTTP при подключении к TSA. В продакшене оставляйте false

Кэш ответов OCSP

Ключ	Env (основная)	По умолчанию	Эффект
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Кэшировать ответы протокола статуса сертификата в реальном времени (OCSP) во время проверки
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL кэша в секундах
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Каталог кэша; null держит кэш только в памяти

Очередь

Ключ	Env (основная)	По умолчанию	Эффект
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Подключение очереди; null использует подключение по умолчанию
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Очередь, в которую GeneratePdfJob помещается для выполнения
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Таймаут на задачу в секундах

Рендерер Chrome CDP (расширение Artisan)

Ключ	Env (основная)	По умолчанию	Эффект
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	значение из окружения или не задано	Путь к исполняемому файлу Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Таймаут рендеринга в секундах
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(пусто)	CSS по умолчанию, внедряемый в отрисованный HTML
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Отключить песочницу Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Максимальный размер входных HTML-данных в байтах

Раздел artisan применяется к привязке документа только при наличии класса фабрики браузера Chrome (расширение nextpdf/artisan). Когда этот класс отсутствует, раздел игнорируется.

Пример кода — продакшен

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

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

• signature.enabled = true с пустым signature.certificate всё равно разрешает SignerInterface в null; необходимо задать оба значения.
• tsa.url = null принудительно устанавливает TsaClient в null, даже если другие ключи tsa.* заполнены.
• signature.level = null сбрасывается к PAdES B-B в модуле подписи.
• image_cache_mb, установленный в null (а не 0), возвращается к значению по умолчанию 50 МБ; 0 явно отключает кэширование.
• Устаревшие переменные окружения TCPDF_* по-прежнему читаются, но объявлены устаревшими. Перейдите на NEXTPDF_*.

Производительность

Чтение конфигурации выполняется через доступ к массиву за O(1). preload_fonts добавляет однократный разбор за O(f) при запуске обработчика, зато снижает задержку первого запроса. Увеличение image_cache_mb уменьшает повторное декодирование изображений ценой памяти, постоянно занятой процессом.

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

tsa.allow_insecure_http ослабляет доверие к меткам времени и в продакшене должен оставаться false. URL-адреса TSA берите только из доверенной конфигурации. Если вы задаёте их через административный интерфейс, используйте межсетевой экран для исходящего трафика или DNS-политику, чтобы снизить риск подделки запросов. См. /integrations/laravel/security-and-operations/.

Соответствие

Форму файла конфигурации не регулирует ни один нормативный стандарт. Все ключи проверены по файлу config/nextpdf.php пакета в документированной ревизии. Семантику уровней подписи определяет Premium, что выходит за рамки этой страницы Core.

Коммерческий контекст

Разделы signature и tsa управляют подписанием в Premium, когда установлен nextpdf/premium. Эта необязательная возможность уровня Enterprise не требует изменений кода в пакете Core. См. https://nextpdf.dev/get-license/?intent=laravel-signing.

См. также

• /integrations/laravel/install/ — опубликовать файл конфигурации
• /integrations/laravel/production-usage/ — посмотреть применение конфигурации в реальном контроллере
• /integrations/laravel/security-and-operations/ — усилить настройки TSA и очереди
• /integrations/laravel/boot-and-discovery/ — посмотреть, какую привязку определяет каждый ключ