Руководство разработчика для CodeIgniter

Кратко

Пакет CodeIgniter предоставляет фабрики сервисов, вспомогательные функции и небольшую библиотечную обёртку Pdf для одного документа в формате Portable Document Format (PDF). Используйте обёртку в контроллерах. Для очередей используются статические вызываемые построители, поскольку полезная нагрузка очереди CodeIgniter должна состоять из сериализуемых данных.

Используйте это руководство, когда проектируете потоки контроллеров, сервисов, построителей очередей и тестов на основе nextpdf/codeigniter.

Граница архитектуры

Слой	Владелец	Ответственность	Не размещайте здесь
Контроллер	Приложение	Авторизация, вызов построителя или сервиса и возврат DownloadResponse.	Общую логику макета.
Библиотечная обёртка	nextpdf/codeigniter	Оборачивает один Document и предоставляет вспомогательные методы для ответа и сохранения.	Долгосрочное хранение документов.
Фабрика сервисов	nextpdf/codeigniter	Создаёт общие реестры и новые документы.	Бизнес-специфичные корневые каталоги хранения.
Построитель очереди	Приложение	Построение документа из статического вызываемого входа.	Объекты запроса или несериализуемое состояние.
Базовый движок	nextpdf/nextpdf	Построение и сериализация PDF.	Политику ответа или очереди CodeIgniter.

Жизненный цикл выполнения

Этап	Поведение	Действие разработчика
Регистрация автозагрузки	Registrar::Autoload() регистрирует загрузку вспомогательных функций модуля.	Загрузите модуль через конфигурацию CodeIgniter.
Разрешение сервиса	Services::pdf() по умолчанию возвращает обёртку для нового документа.	Разрешайте один раз за запрос.
Создание	Код приложения использует Pdf::document() для базовых вызовов документа.	Держите код построения документа в сервисах или построителях.
Ответ	PdfResponse возвращает DownloadResponse.	Дайте пакету установить заголовки PDF.
Выполнение в очереди	GeneratePdfJob::process() проверяет построитель и путь вывода, а затем сохраняет документ.	Размещайте построители очереди в App\PdfBuilders.

Рекомендуемая структура приложения

Путь	Назначение
app/PdfBuilders/*	Статические построители, безопасные для очереди и принимаемые GeneratePdfJob.
app/Libraries/*	Необязательные обёртки приложения для повторяющихся операций с документами.
app/Services/*	Политика получения и хранения доменных данных.
app/Config/NextPdf.php	Переопределения конфигурации пакета на стороне приложения.
tests/app/PdfBuilders/*	Тесты построителей и полезной нагрузки очереди.

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

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

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

Шаблон построителя очереди

Построители очереди должны быть статическими, детерминированными и располагаться в App\PdfBuilders. Держите массив контекста достаточно простым, чтобы его было легко сериализовать и проверять.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

Задание ограничивает вывод настроенным PDF-каталогом приложения. Если вашему приложению нужно хранение для конкретного арендатора, вынесите эту политику в один сервис и протестируйте её перед отправкой задания.

Точки расширения

Точка расширения	Используйте для	Ограничение
Services::pdfDocument()	Настройка создания документа.	Должен возвращать новый документ.
Services::fontRegistry()	Прогрев шрифтов и доступ к реестру.	Отклоняйте небезопасные пути и держите реестр заблокированным после прогрева.
Services::pdfSigner()	Включение необязательного цифрового подписания.	Возвращайте null, когда подписание отключено.
NextPDF\CodeIgniter\Libraries\Pdf	Оборачивание работы с документом на стороне контроллера.	Одна обёртка соответствует одному документу.
App\PdfBuilders::*	Безопасные для очереди построители документов.	Требуется строка статического вызываемого.
app/Config/NextPdf.php	Значения приложения по умолчанию и настройки интеграции.	Держите производственные значения явными.

Процесс разработки

1. Начните с контроллера, который вызывает pdf() или service('pdf').
2. Перенесите повторяющееся построение документа в app/PdfBuilders или сервис приложения.
3. Используйте GeneratePdfJob, когда генерация слишком медленна для пути запроса.
4. Держите контекст очереди сериализуемым и небольшим.
5. Сохраняйте вывод в утверждённом корневом каталоге хранения PDF, если только вы намеренно не расширяете эту политику.
6. Добавьте тесты для вспомогательных функций, сервисов, полезной нагрузки очереди и небезопасных путей.

Обработка сбоев

Сбой	Где это следует обрабатывать	Рекомендуемый ответ
Отсутствующее расширение или небезопасный путь к шрифту	Фабрика сервисов.	Откажите сразу при разрешении сервиса.
Недопустимый вызываемый построитель	Проверка задания очереди.	Отклоните задание и запишите в журнал строку построителя без секретов.
Небезопасный путь вывода	Сервис хранения и задание очереди.	Отклоните до отправки и сохраните проверку в задании.
Ошибка сериализации ответа	Обработка ошибок контроллера или фреймворка.	Не отправляйте частичное тело ответа.
Необязательный класс Premium недоступен	Возвращаемое значение метода сервиса.	Явно обрабатывайте null перед использованием необязательных функций электронных счетов.

Безопасные значения по умолчанию

Аспект	По умолчанию	Когда переопределять
Пространство имён построителя очереди	App\PdfBuilders.	Оставляйте значение по умолчанию, если только вы также не обновляете политику безопасности.
Корневой каталог вывода	WRITEPATH/pdfs.	Переопределяйте только с более строгим списком разрешений.
Имя файла ответа	document.pdf.	Используйте очищенные бизнес-имена файлов.
Методы потоковой передачи	Паритет интерфейса прикладного программирования (API) с другими фреймворками.	Не полагайтесь на потоковую передачу как на границу памяти в CodeIgniter.
Сервис документов	Новый по умолчанию.	Не запрашивайте общие документы из кода запроса.

Контрольный список тестирования

• Тесты сервиса проверяют, что каждое разрешение Services::pdf() возвращает независимый документ.
• Тесты вспомогательных функций проверяют, что pdf() и pdf_document() возвращают новые объекты.
• Тесты ответа проверяют заголовки и нормализацию имени файла.
• Тесты очереди охватывают недопустимые строки построителей и небезопасные пути вывода.
• Тесты построителей используют репрезентативные данные контекста.
• Тесты конфигурации охватывают путь к шрифтам, путь к кэшу, отключённое подписание и отключённые состояния центра отметок времени Time-Stamp Authority (TSA).