Справочник API CodeIgniter

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

Пакет CodeIgniter предоставляет небольшой API для контроллеров. В него входят библиотека-обёртка Pdf для одного документа (Services::pdf() и глобальная pdf()), вспомогательные функции ответа, которые преобразуют готовый документ в DownloadResponse (PdfResponse), Services и стоящие за ними фабрики (реестры шрифтов и изображений, фабрика документов, а также необязательные сервис подписания и клиент службы меток времени (TSA)), класс конфигурации NextPdf и GeneratePdfJob для асинхронной генерации из статических вызываемых построителей.

Начните с основного сценария контроллера: вызовите Services::pdf() (или вспомогательную функцию pdf()), добавьте содержимое в $pdf->document() и верните $pdf->download('file.pdf'). Этот сценарий покрывает самый частый случай. Справочные таблицы сгруппированы по областям API; раздел “Распространённые задачи” сначала показывает готовые к запуску варианты.

Распространённые задачи

Это самые распространённые рабочие сценарии. Каждый пример проверен по исходному коду nextpdf/codeigniter.

Используйте канонический путь отрисовки, чтобы вернуть из контроллера PDF-файл для загрузки в формате PDF (Portable Document Format):

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

        return $pdf->download("invoice-{$id}.pdf");
    }
}

Что делает: создаёт новую обёртку Pdf вокруг нового Document, записывает одну ячейку и возвращает DownloadResponse с attachment и заголовками безопасности пакета.

Чтобы предварительно просмотреть PDF в браузере, используйте ту же обёртку и inline() вместо download():

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

Что делает: использует глобальную вспомогательную функцию pdf() (эквивалент Services::pdf()) и возвращает DownloadResponse с inline, поэтому браузер показывает PDF, а не скачивает его.

Сгенерируйте PDF асинхронно в очереди с помощью GeneratePdfJob и статического построителя:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

Что делает: ставит генерацию в очередь. Обработчик проверяет построитель (это должен быть статический вызываемый App\PdfBuilders\...::method) и путь вывода (он должен разрешаться внутри WRITEPATH/pdfs/ и заканчиваться на .pdf), создаёт новый документ и сохраняет его.

Обёртка-библиотека

Используйте эту таблицу, когда у вас есть обёртка Pdf и нужны её методы ответа или сохранения.

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с	Примечания
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: новый документ ядра.	Оборачивает переданный документ для одной операции ответа или сохранения.	`Pdf`	Не ожидается.	Не используйте обёртку повторно после вывода.
`Pdf::document()`	нет.	Возвращает обёрнутый документ.	`NextPDF\Core\Document`	Не ожидается.	Используйте это для вызова API создания документов ядра.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: имя файла ответа.	Использует встроенное (inline) расположение в браузере.	`CodeIgniter\HTTP\DownloadResponse`	Ошибки сериализации ядра.	Делегирует `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: имя файла ответа.	Использует расположение “вложение” (attachment) в браузере.	`DownloadResponse`	Ошибки сериализации ядра.	Делегирует `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: имя файла ответа.	Обеспечивает совместимость API с пакетами других фреймворков.	`DownloadResponse`	Ошибки сериализации ядра.	CodeIgniter обрабатывает двоичный вывод штатно.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: имя файла ответа.	Обеспечивает совместимость API с пакетами других фреймворков.	`DownloadResponse`	Ошибки сериализации ядра.	Используйте те же средства управления размером, что и для непотоковых ответов.
`Pdf::save(string $path)`	`path`: целевой путь в файловой системе.	Записывает обёрнутый документ.	`void`	Ошибки файловой системы или записи ядра.	Проверяйте корневые каталоги хранилища перед сохранением.

Сервисы и вспомогательные функции

Используйте эту таблицу, когда вам нужна конкретная фабрика сервиса или глобальная вспомогательная функция, включая поведение совместного использования и тип возвращаемого значения.

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с	Примечания
`Services::fontRegistry(bool $getShared = true)`	`getShared`: флаг общего сервиса CodeIgniter.	Возвращает общий реестр, прогревает его настроенными шрифтами, затем блокирует.	`FontRegistryInterface`	`RuntimeException` при отсутствии расширений или небезопасном пути к шрифтам.	Отклоняет обёртки потоков и нулевые байты в `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: флаг общего сервиса.	Возвращает общий ограниченный реестр изображений по принципу вытеснения наименее недавно использованных (LRU).	`ImageRegistry`	Не ожидается.	Размер кэша управляется параметром `imageCacheMb`.
`Services::documentFactory(bool $getShared = true)`	`getShared`: флаг общего сервиса.	Возвращает общую фабрику, использующую общие реестры.	`DocumentFactoryInterface`	Ошибки настройки реестра.	Фабрику можно использовать повторно, документы — нет.
`Services::tsaClient(bool $getShared = true)`	`getShared`: флаг общего сервиса.	Возвращает `null`, когда `tsa.url` пуст.	`TsaClient	null`	Ошибки HTTP-клиента или конфигурации TSA.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: флаг общего сервиса.	Возвращает `null`, когда подписание отключено.	`SignerInterface	null`	Ошибки сертификата или уровня подписи.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: флаг общего сервиса.	Создаёт новый документ, применяет значения по умолчанию и при необходимости настраивает PDF/A или Artisan.	`Document`	Ошибки необязательного расширения или конфигурации документа.	Сохраняйте значение по умолчанию `false` для безопасности запроса.
`Services::pdf(bool $getShared = false)`	`getShared`: флаг общего сервиса.	Создаёт новую обёртку `Pdf` вокруг нового документа.	`NextPDF\CodeIgniter\Libraries\Pdf`	Ошибки настройки документа.	Основной сервис для контроллеров.
`Services::eInvoiceEmbedder()`	нет.	Возвращает `null`, если класс встраивания электронных счетов из Premium Pro недоступен.	`EmbedderInterface	null`	Ошибки создания необязательного пакета.
`Services::eInvoiceValidator()`	нет.	Возвращает `null`, если класс валидатора из Premium Enterprise недоступен.	`ValidatorInterface	null`	Ошибки создания необязательного пакета.
`Services::eInvoiceProfile()`	нет.	Возвращает профиль EN16931, когда установлен Premium Pro.	`ProfileInterface	null`	Ошибки необязательного пакета.
`Services::schematronRunner()`	нет.	Возвращает `null`, если класс валидатора Schematron из Premium Enterprise недоступен.	`SchematronRunnerInterface	null`	Ошибки создания необязательного пакета.
`Registrar::Autoload()`	нет.	Добавляет вспомогательную функцию пакета в конфигурацию автозагрузки CodeIgniter.	`array`	Не ожидается.	Включает `pdf()` и `pdf_document()`, когда модуль загружен.
`pdf()`	нет.	Вызывает `Services::pdf(false)`.	`Pdf`	Ошибки настройки документа.	Удобная вспомогательная функция для контроллеров.
`pdf_document()`	нет.	Вызывает `Services::pdfDocument(false)`.	`Document`	Ошибки настройки документа.	Удобная вспомогательная функция, когда предпочтительнее API документа ядра.

Ответы HTTP

Используйте эту таблицу, когда у вас уже есть готовый Document и вы хотите самостоятельно сформировать DownloadResponse вместо использования обёртки Pdf.

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с	Примечания
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: готовый документ; `filename`: имя файла ответа.	Обеспечивает расширение `.pdf` и встроенное (inline) расположение.	`DownloadResponse`	Ошибки сериализации ядра.	Добавляет тип содержимого PDF и защитные заголовки.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Так же, как `inline`; расположение — “вложение” (attachment).	Обеспечивает расширение `.pdf`.	`DownloadResponse`	Так же, как `inline`.	Используйте для загрузок в браузере.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Так же, как `inline`.	Поведение такое же, как у `inline` в CodeIgniter 4 (CI4).	`DownloadResponse`	Так же, как `inline`.	Существует для совместимости API между фреймворками.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Так же, как `download`.	Поведение такое же, как у `download` в CI4.	`DownloadResponse`	Так же, как `download`.	Существует для совместимости API между фреймворками.

Задание очереди

Используйте эту таблицу, когда настраиваете асинхронную генерацию и вам нужны точные ключи данных задания и контракт вызываемого построителя.

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с	Примечания
`GeneratePdfJob::process()`	Ключи данных задания: `builder`, `outputPath` и необязательный `context`.	Если контекст отсутствует, использует пустой массив.	`void`	`InvalidArgumentException` при небезопасном построителе или пути вывода; ошибки записи ядра.	Построитель должен быть `App\PdfBuilders\...\*::method`.
Вызываемый построитель	`Document $doc`, `array $context`.	По умолчанию контекста нет, кроме данных задания.	`Document`	Исключения, специфичные для построителя.	Требует статического вызываемого, поскольку полезные нагрузки очереди CI4 — это сериализованные данные.

Конфигурация

Используйте эту таблицу, когда меняете в классе конфигурации NextPdf значения по умолчанию для формата страницы, путей, подписания, TSA или метаданных документа.

Свойство	Тип	Поведение по умолчанию	Примечания
`pageFormat`	`string`	`A4`.	Задаёт формат страницы по умолчанию.
`orientation`	`string`	`P`.	Задаёт ориентацию по умолчанию.
`unit`	`string`	`mm`.	Задаёт единицу измерения по умолчанию.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` и `WRITEPATH . 'cache/nextpdf'`.	Храните пути внутри хранилища, контролируемого приложением.
`signature`	`array`	Отключено с уровнем `B-B`.	Сертификат, ключ, пароль, дополнительные сертификаты и уровень.
`tsa`	`array`	Отключено, когда URL равен `null`; тайм-аут 30 секунд.	Учётные данные, файлы взаимного TLS (mTLS), привязки открытых ключей и политика HTTP.
`ocspCache`	`array`	Включено со временем жизни (TTL) 86400 секунд.	Используется при наличии в процессах проверки подписи.
`preloadFonts`	`list<string>`	Пусто.	Прогревается перед блокировкой реестра.
`imageCacheMb`	`int`	`50`.	Управляет кэшем изображений на время жизни процесса.
`fontCacheLocking`	`bool`	`true`.	Удерживает изменения реестра шрифтов вне обработки запроса.
`artisan`	`array`	Отрисовщик Chrome отключён, пока не настроен и не установлен.	Сопоставляется с `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Создатель `NextPDF`, пустой автор, язык `en`, поля по умолчанию и шрифт по умолчанию.	`Services::pdfDocument()` применяет только `creator`, `language` и (если не пусто) `author`; `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box` и `bleed_box` заданы как значения по умолчанию, но в настоящее время не применяются.

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

GeneratePdfJob ограничивает вывод каталогом WRITEPATH . 'pdfs' и требует .pdf.
Вызываемые построители за пределами App\PdfBuilders отклоняются, чтобы исключить произвольное выполнение кода из изменённых полезных нагрузок очереди.
Используйте service('pdf') или вспомогательную функцию пакета в потоках контроллера; для длительной генерации используйте задания очереди.