Конфигурация NextPDF для CodeIgniter 4

Кратко

Конфигурация NextPDF находится в NextPDF\CodeIgniter\Config\NextPdf — подклассе CodeIgniter BaseConfig. Значения можно переопределить, расширив этот класс в app/Config/ или задав ключи .env с префиксом nextpdf.. Значения по умолчанию работают без дополнительной настройки.

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

NextPdf — это типизированный BaseConfig. Он намеренно не финальный. В CodeIgniter конфигурация приложения расширяет класс из пакета, поэтому ваше приложение может переопределить значения по умолчанию. Когда CodeIgniter создаёт конфигурацию, BaseConfig разрешает переопределения из окружения для каждого публичного свойства, включая вложенные ключи массивов.

Пути к шрифтам и кэшу по умолчанию используют константу CodeIgniter WRITEPATH: WRITEPATH . 'fonts' и WRITEPATH . 'cache/nextpdf'.

Ключи конфигурации

Каждый ключ ниже — публичное свойство NextPdf. Значения по умолчанию сверены с исходным кодом пакета.

Значения по умолчанию для страницы и документа

Ключ	Тип	По умолчанию	Описание
`pageFormat`	`string`	`A4`	Формат страницы.
`orientation`	`string`	`P`	`P` — книжная ориентация, `L` — альбомная.
`unit`	`string`	`mm`	Единица измерения.
`defaults.creator`	`string`	`NextPDF`	Метаданные создателя в формате Portable Document Format (PDF).
`defaults.author`	`string`	`''`	Метаданные автора; пропускаются, если значение пустое.
`defaults.language`	`string`	`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`	`string`	`dejavusans`	Семейство шрифтов по умолчанию.
`defaults.font_size`	`float`	`12.0`	Размер шрифта по умолчанию.
`defaults.trim_box`	`list<float>\|null`	`null`	Trim box, если задан.
`defaults.bleed_box`	`list<float>\|null`	`null`	Bleed box, если задан.

Пакет применяет defaults.creator и defaults.language к каждому документу. defaults.author применяется только тогда, когда значение непустое.

Пути и кэш

Ключ	Тип	По умолчанию	Описание
`fontsPath`	`string`	`WRITEPATH/fonts`	Каталог файлов шрифтов.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Каталог кэша.
`preloadFonts`	`list<string>`	`[]`	Абсолютные пути к шрифтам, которые прогреваются при загрузке.
`imageCacheMb`	`int`	`50`	Бюджет кэша изображений по принципу наименее недавно использованных (LRU) в мегабайтах (МБ).
`fontCacheLocking`	`bool`	`true`	Блокировать кэш шрифтов после прогрева.

Реестр шрифтов отклоняет любой fontsPath, содержащий обёртку потока (://) или нулевой байт, и вызывает ошибку времени выполнения. См. /integrations/codeigniter/security-and-operations/.

Архивирование и цвет (NextPDF Pro)

Ключ	Тип	По умолчанию	Описание
`pdfa`	`string\|null`	`null`	Версия PDF/A: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Путь к ICC-профилю для красного, зелёного и синего (RGB) Международного консорциума по цвету (ICC).
`iccProfile.cmyk`	`string\|null`	`null`	Путь к ICC-профилю для голубого, пурпурного, жёлтого и чёрного (CMYK).

pdfa действует только тогда, когда установлен NextPDF Pro и доступна возможность архивирования. В одном лишь core этот ключ игнорируется.

Цифровая подпись (NextPDF Pro / Enterprise)

Ключ	Тип	По умолчанию	Описание
`signature.enabled`	`bool`	`false`	Включает службу подписания.
`signature.certificate`	`string\|null`	`null`	Путь к файлу сертификата.
`signature.private_key`	`string\|null`	`null`	Путь к файлу закрытого ключа.
`signature.password`	`string`	`''`	Пароль закрытого ключа.
`signature.extra_certs`	`list<string>`	`[]`	Пути к дополнительным сертификатам цепочки.
`signature.level`	`string`	`B-B`	Идентификатор уровня подписи.

Services::pdfSigner() возвращает null, если только signature.enabled не равно true и signature.certificate непустой. Уровень по умолчанию — B-B. NextPDF Pro предоставляет базовую подпись B-B. Уровни долгосрочной проверки — отдельная возможность Enterprise; они описаны в справочнике Premium, а не здесь.

Усовершенствованные электронные подписи PDF (PAdES) B-T создаются ядром Core. Интеграция с CodeIgniter сама по себе не добавляет B-T, а Pro поставляет только базовый уровень B-B. Эта документация будет обновлена, если и когда выйдет Pro B-T.

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

Ключ	Тип	По умолчанию	Описание
`tsa.url`	`string\|null`	`null`	URL конечной точки службы меток времени (TSA).
`tsa.username`	`string`	`''`	Имя пользователя для базовой аутентификации TSA.
`tsa.password`	`string`	`''`	Пароль для базовой аутентификации TSA.
`tsa.cert`	`string\|null`	`null`	Путь к клиентскому сертификату.
`tsa.key`	`string\|null`	`null`	Путь к клиентскому ключу.
`tsa.timeout`	`int`	`30`	Тайм-аут запроса в секундах.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Закреплённые открытые ключи TSA.
`tsa.warn_on_key_rotation`	`bool`	`true`	Предупреждать о смене ключа TSA.
`tsa.allow_insecure_http`	`bool`	`false`	Разрешает незашифрованный HTTP к TSA.

Services::tsaClient() возвращает null, когда tsa.url равен null или пустой строке. Когда вы выбираете уровень подписи, требующий метки времени, модуль подписания автоматически подключает клиент TSA.

Кэш OCSP

Ключ	Тип	По умолчанию	Описание
`ocspCache.enabled`	`bool`	`true`	Включает кэш ответов протокола интерактивного статуса сертификата (OCSP).
`ocspCache.ttl`	`int`	`86400`	Время жизни кэша (TTL) в секундах.
`ocspCache.directory`	`string\|null`	`null`	Каталог кэша; при null применяется значение движка по умолчанию.

Отрисовщик HTML в Chrome (NextPDF Artisan)

Ключ	Тип	По умолчанию	Описание
`artisan.chrome_binary`	`string\|null`	`null`	Путь к исполняемому файлу Chrome/Chromium.
`artisan.render_timeout`	`int`	`30`	Тайм-аут отрисовки в секундах.
`artisan.default_css`	`string`	`''`	Таблица стилей по умолчанию.
`artisan.no_sandbox`	`bool`	`false`	Передаёт `--no-sandbox` в Chrome.
`artisan.max_html_size`	`int`	`5000000`	Максимальный размер входного HTML в байтах.

Отрисовщик Chrome настраивается для документа только тогда, когда artisan.chrome_binary задан и установлен nextpdf/artisan.

Переопределение через `.env`

BaseConfig разрешает переопределения из окружения для каждого свойства. Ключ поиска — краткое имя класса в нижнем регистре, nextpdf, за которым следует путь к свойству. Используйте точки для обращения к вложенным ключам массивов. Допустимы обе формы: с точкой и с подчёркиванием.

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

Префикс — краткое имя класса в нижнем регистре. Он остаётся nextpdf, несмотря на то что класс записан как NextPdf. Можно также использовать полностью квалифицированную форму (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Переопределение путём расширения класса

Для типизированной конфигурации под контролем версий расширьте класс из пакета в app/Config/. CodeIgniter загружает класс приложения вместо значения из пакета по умолчанию. Этот файл объявляет класс и не вызывает побочных эффектов. Это сохраняет соответствие требованию PSR-1: файл либо объявляет символы, либо выполняет логику с побочными эффектами, но не то и другое одновременно (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

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

Переопределение одного вложенного ключа через .env меняет только этот ключ; остальная часть массива сохраняет своё значение по умолчанию.
.env содержит строковые значения. CodeIgniter приводит типы true/false и числовые строки. Заключайте в кавычки значения, которые должны оставаться буквальными строками.
Расширение класса с частичным массивом defaults заменяет весь массив. Включайте каждый ключ, как показано выше.

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

Не храните пути к сертификату и ключу в системе контроля версий. Передавайте их через .env или менеджер секретов. tsa.allow_insecure_http должен оставаться false в production. См. /integrations/codeigniter/security-and-operations/.

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

Файл расширения конфигурации приложения объявляет один класс и не вызывает побочных эффектов (PSR-1 §x1.x1.p3).

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

NextPDF core распространяется под лицензией Apache-2.0. Ключи signature.* и pdfa действуют только тогда, когда установлен NextPDF Pro или Enterprise. Пакет CodeIgniter предоставляет соответствующие методы служб. Эти методы возвращают null, пока вы не установите подходящий пакет Premium. См. </get-license/?intent=codeigniter-signing>.

См. также

/integrations/codeigniter/install/ — установка пакета.
/integrations/codeigniter/quickstart/ — первый PDF.
/integrations/codeigniter/production-usage/ — контроллеры с внедрением зависимостей и задания очередей.
/integrations/codeigniter/security-and-operations/ — усиление настройки подписания и путей.