Настройка пакета NextPDF для Symfony

Кратко

Поведение пакета настраивается в файле config/packages/nextpdf.yaml через корневой ключ nextpdf. Для каждого ключа задано значение по умолчанию, поэтому достаточно указывать только значения, которые вы хотите изменить. Эта страница в точности отражает Configuration.php.

Дерево конфигурации

NextPDF\Symfony\DependencyInjection\Configuration описывает схему. Недопустимые значения вызывают ошибку на этапе сборки контейнера: Symfony выбрасывает исключение InvalidConfigurationException.

Ключи верхнего уровня

Ключ	Тип	По умолчанию	Валидация
page_format	enum	A4	одно из A4, A3, A5, Letter, Legal, Tabloid
orientation	enum	P	одно из P, L
unit	enum	mm	одно из pt, mm, cm, in
pdfa	скаляр (scalar)	null	одно из null, 4, 4e, 4f
fonts_path	скаляр (scalar)	%kernel.project_dir%/resources/fonts	—
cache_path	скаляр (scalar)	%kernel.cache_dir%/nextpdf	—
image_cache_mb	целое число (integer)	50	минимум 0
font_cache_locking	boolean	true	—
preload_fonts	список строк	[]	—

icc_profile

Ключ	Тип	По умолчанию
icc_profile.rgb	скаляр (scalar)	null
icc_profile.cmyk	скаляр (scalar)	null

defaults

Применяется ко всем документам, которые создаёт PdfFactory.

Ключ	Тип	По умолчанию
defaults.creator	скаляр (scalar)	NextPDF
defaults.author	скаляр (scalar)	(пусто)
defaults.language	скаляр (scalar)	en
defaults.margin_top	float	10.0
defaults.margin_right	float	10.0
defaults.margin_bottom	float	10.0
defaults.margin_left	float	10.0
defaults.font_family	скаляр (scalar)	dejavusans
defaults.font_size	float	12.0
defaults.trim_box	переменная (variable)	null
defaults.bleed_box	переменная (variable)	null

PdfFactory считывает creator, author и language из этого раздела и применяет их к каждому новому документу. Остальные ключи пакет сохраняет в параметрах контейнера для использования движком.

artisan

Применяется только если nextpdf/artisan установлен и обнаружен.

Ключ	Тип	По умолчанию
artisan.chrome_binary	скаляр (scalar)	null
artisan.render_timeout	целое число (integer)	30
artisan.default_css	скаляр (scalar)	(пусто)
artisan.no_sandbox	boolean	false
artisan.max_html_size	целое число (integer)	5000000

signature

Применяется только если установлен nextpdf/premium. Если пакет присутствует и доступен уровень Pro, поддерживается конфигурация подписи профиля baseline B-B. Узел level принимает приведённые ниже строковые значения, чтобы схема оставалась совместимой с более широким семейством конфигураций NextPDF. Этот пакет предоставляет подпись уровня B-B. Профили выше B-B описаны отдельно в документации NextPDF Premium и здесь не заявлены.

Ключ	Тип	По умолчанию	Валидация
signature.enabled	boolean	false	—
signature.certificate	скаляр (scalar)	null	—
signature.private_key	скаляр (scalar)	null	—
signature.password	скаляр (scalar)	(пусто)	—
signature.extra_certs	список строк	[]	—
signature.level	enum	B-B	допустимый набор: B-B, B-T, B-LT, B-LTA (B-B предоставляется; B-T/B-LT/B-LTA — значения для совместимости схемы, а не предоставляемая возможность Pro)

Проход компилятора регистрирует сервис подписи только тогда, когда signature.enabled равен true и задан signature.certificate; в противном случае раздел остаётся неактивным.

tsa

Конфигурация клиента службы меток времени (TSA), которую использует подпись Pro при наличии настройки.

Ключ	Тип	По умолчанию
tsa.url	скаляр (scalar)	null
tsa.username	скаляр (scalar)	(пусто)
tsa.password	скаляр (scalar)	(пусто)
tsa.cert	скаляр (scalar)	null
tsa.key	скаляр (scalar)	null
tsa.timeout	целое число (integer)	30
tsa.allow_insecure_http	boolean	false
tsa.pinned_public_keys	список строк	[]
tsa.warn_on_key_rotation	boolean	true

Пакет регистрирует сервис клиента TSA только тогда, когда задан tsa.url.

ocsp_cache

Ключ	Тип	По умолчанию
ocsp_cache.enabled	boolean	true
ocsp_cache.ttl	целое число (integer)	86400
ocsp_cache.directory	скаляр (scalar)	null

messenger

Настройки асинхронной генерации, которые применяются, если установлен symfony/messenger.

Ключ	Тип	По умолчанию
messenger.transport	скаляр (scalar)	async
messenger.timeout	целое число (integer)	120
messenger.retries	целое число (integer)	3

Эталонная конфигурация

Файл конфигурации, показывающий каждый раздел с его значениями по умолчанию:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Сервисы и псевдонимы контейнера

Пакет загружает определения своих сервисов из config/services.php. Таблица ниже точно соответствует этому файлу.

Идентификатор сервиса	Разделяемый	Публичный	Примечания
NextPDF\Typography\FontRegistry	да	—	создаётся на основе nextpdf.fonts_path; необязательный логгер PHP Standard Recommendation 3 (PSR-3)
NextPDF\Contracts\FontRegistryInterface	(псевдоним)	да	псевдоним FontRegistry
NextPDF\Graphics\ImageRegistry	да	—	ограниченный кэш с вытеснением наименее недавно использованных элементов (LRU); помечен тегом kernel.reset (reset)
NextPDF\Core\DocumentFactory	да	—	использует оба реестра совместно
NextPDF\Contracts\DocumentFactoryInterface	(псевдоним)	да	псевдоним DocumentFactory
NextPDF\Symfony\Service\PdfFactory	да	да	считывает defaults, pdfa и artisan из параметров
NextPDF\Contracts\PdfDocumentInterface	нет	да	фабрика [PdfFactory, create]
NextPDF\Core\Document	(псевдоним)	—	псевдоним PdfDocumentInterface
nextpdf.document	(псевдоним)	да	псевдоним PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	да	хелпер без состояния

Пакет также регистрирует привязки контрактов EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) только если существуют соответствующие классы реализации Premium. Каждый такой сервис неразделяемый, поэтому вызывающий код получает новый экземпляр. Состояние парсера отдельного вызова никогда не переносится между запросами.

Разделяемые и неразделяемые сервисы

nextpdf.document (и его псевдонимы) является неразделяемым: при каждом разрешении контейнер возвращает отдельный документ. Согласно PHP Standard Recommendation 11 (PSR-11), контейнер может возвращать разные значения при последовательных вызовах get() с одним и тем же идентификатором; см. PSR-11 §1.1.2. Реестр шрифтов является разделяемым и блокируется после прогрева. Структурные данные шрифта разбираются один раз за процесс и не могут быть изменены в середине запроса.

Сервисы FontRegistry и ImageRegistry принимают необязательный Psr\Log\LoggerInterface; Symfony связывает его с помощью nullOnInvalid(). Логгер остаётся необязательным участником взаимодействия, который можно заменить в соответствии с контрактом логгера PSR-3.

Автоматическое связывание

PdfFactory, PdfResponse, интерфейс фабрики документов и интерфейс реестра шрифтов являются публичными. Их можно получить из контейнера или указать в типизированных параметрах контроллеров и сервисов с автоматическим связыванием. Рекомендуемая точка входа — внедрение NextPDF\Symfony\Service\PdfFactory через конструктор.

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

• pdfa задан без Pro — значение сохраняется, но игнорируется. PdfFactory применяет Portable Document Format/Archival (PDF/A) только тогда, когда расширение Pro обнаружено на этапе компиляции.
• image_cache_mb: 0 — допустимо; отключает LRU-кэш изображений. Отрицательные значения отклоняются на этапе сборки.
• signature.enabled: true без signature.certificate — сервис подписи не регистрируется; конфигурация по замыслу остаётся неактивной без сообщения.
• Подстановки %kernel.*% — значения по умолчанию fonts_path и cache_path используют параметры контейнера Symfony; переопределяйте их абсолютными путями только тогда, когда нужен буквальный путь.

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

Каждая строка в этой таблице — нормативное утверждение на этой странице, связанное с полным 64-символьным шестнадцатеричным reference_id из закрытого корпуса организации по разработке стандартов (SDO). Происхождение, включая манифест корпуса и механизм извлечения, указано в _sidecars/rag-citations.yaml.

Спецификация	Пункт	Идентификатор ссылки (reference_id)	Утверждение
PSR-11	psr_11_container#1.1.2.p3.b		get() может возвращать разные значения при каждом разрешении
PSR-3	psr_3_logger#x3.p17		Необязательный участник взаимодействия LoggerInterface

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

Разделы signature и tsa применяются только тогда, когда установлен nextpdf/premium (Pro). Эта необязательная возможность Pro не требует изменений кода в описанном здесь пакете Core. См. </get-license/?intent=symfony-pro>.

См. также

• /integrations/symfony/install/ — установка и регистрация пакета.
• /integrations/symfony/overview/ — сводный обзор возможностей.
• /integrations/symfony/production-usage/ — безопасность воркеров и асинхронные паттерны.
• /integrations/symfony/boot-and-discovery/ — как конфигурация разрешается во время загрузки.