Core / Fachada Document

Visão geral

Document é a fachada final para todas as chamadas de autoria do NextPDF. Ela compõe 21 concern traits e grava um arquivo Portable Document Format (PDF) 2.0 em uma única passagem por streaming.

Instalação

composer require nextpdf/core:^3

Visão conceitual

NextPDF\Core\Document é declarada como final class Document implements PdfDocumentInterface. Seu corpo permanece deliberadamente enxuto: mantém o RenderingContext, o modelo DocumentData, o PdfWriter e os subengines eager, além de alguns auxiliares privados. Todos os métodos públicos de autoria vêm dos 21 traits que ela compõe por meio de use Concerns\Has*:

HasMetadata, HasPages, HasTypography, HasColors, HasTextOutput, HasDrawing, HasTransforms, HasLayout, HasNavigation, HasImages, HasBarcodes, HasFormFields, HasLayers, HasTemplates, HasTransactions, HasFileAttachments, HasJavaScript, HasViewerPreferences, HasSecurity, HasOutput, HasWarnings.

Essa composição é intencional. Uma mudança no comportamento de texto pertence a HasTextOutput; uma mudança no tratamento de páginas pertence a HasPages. Document.php permanece pequeno, o que mantém cada mudança restrita a um único trait. A entrada Core do .ai/manifest.json marca Document.php como zona de perigo por esse motivo: a fachada tem alcance amplo, portanto edições estruturais passam pelo plan mode.

O ciclo de vida é de uso único. O docblock da classe afirma isso diretamente: cada instância de Document é descartável; nunca a reutilize nem a redefina. Não há método reset(), e o RenderingContext, que carrega o cursor, a página ativa, o estado gráfico e a seleção de fonte, também não tem equivalente. Para workers de longa duração, mantenha o FontRegistry e o ImageRegistry ativos no escopo do processo e crie uma nova instância de Document para cada requisição por meio do DocumentFactory. O documento lê esses registros, mas nunca os modifica, de modo que uma falha em uma requisição não possa vazar para a seguinte.

O construtor recebe FontRegistryInterface $fontRegistry, ImageRegistryInterface $imageRegistry e um Config opcional. Quando $config é omitido, o construtor usa um Config padrão. Ele cria os engines eager: FontMetrics, DrawingEngine, TransformEngine, TextRenderer, HeaderFooter, ColumnLayout, BookmarkManager, LinkManager, TocBuilder, AnnotationManager, PageManager. Quase todo documento precisa deles. Os engines opcionais permanecem null até o primeiro acesso.

O conteúdo da página é emitido como content streams. Cada página é representada por um ou mais content streams (ISO 32000-2:2020 §7.8.2). A árvore de páginas conecta as páginas por meio de arrays Kids com referências indiretas (§7.7.3).

Superfície da API

Símbolo	Tipo	Estabilidade	Desde
final class Document implements PdfDocumentInterface	classe	estável	1.0.0
Document::createStandalone(?Config $config = null): self	fábrica estática	estável	1.0.0
Document::__construct(FontRegistryInterface, ImageRegistryInterface, ?Config)	construtor	estável	1.0.0
Document::addTextPreprocessor(TextPreprocessorInterface): static	método	estável	1.9.0
Document::fontMetrics(): FontMetrics	método	estável	1.0.0
Document::setDPartRoot(DPartRoot): static	método	estável	1.12.0
Document::strictPdf20FontEmbedding(): static	método	estável	2.5.0
Document::allowNonEmbeddedBase14(): static	método	estável	2.5.0

Exemplo de código — Início rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'This is a minimal PDF generated with NextPDF.', newLine: true);
$doc->save(__DIR__ . '/output/01-hello-world.pdf');

echo "Created: output/01-hello-world.pdf\n";

Fonte: examples/01-hello-world.php.

Exemplo de código — Produção

PdfFactory é um builder imutável. Cada chamada with*() retorna uma nova factory, de modo que um único builder configurado pode produzir vários documentos independentes.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\PdfFactory;
use NextPDF\ValueObjects\{Margin, PageSize};

// Build a configured factory — each with*() returns a new instance
$factory = PdfFactory::new()
    ->withPageSize(PageSize::A4())
    ->withMargins(new Margin(15.0, 15.0, 15.0, 15.0))
    ->withCompress(true)
    ->withLang('en');

// Create a document from the factory
$doc = $factory->create();
$doc->setTitle('PdfFactory Example');
$doc->setAuthor('NextPDF');
$doc->addPage();
$doc->setFont('helvetica', '', 16);
$doc->cell(0, 12, 'Created via PdfFactory', newLine: true);

// The same factory can create multiple independent documents
$doc2 = $factory->create();
$doc2->addPage();
$doc2->setFont('helvetica', '', 12);
$doc2->cell(0, 10, 'Second document from the same factory.');

$doc->save(__DIR__ . '/output/02-pdf-factory.pdf');

Fonte: examples/02-pdf-factory.php.

Casos extremos e pegadinhas

• Document é final. Estenda o comportamento compondo um novo concern trait ou encapsulando a fachada, não por meio de subclasses.
• A fachada implementa PdfDocumentInterface. No código da aplicação, dependa da interface para manter a vinculação dos workers substituível.
• createStandalone() cria registros efêmeros com o cache desativado; é adequado apenas para a interface de linha de comando (CLI) e o PHP FastCGI Process Manager (PHP-FPM). Use o DocumentFactory em RoadRunner, Swoole ou Octane.
• setChromeRendererConfig() e writeHtmlChrome() exigem a extensão nextpdf/artisan; sem ela, a chamada lança InvalidConfigException.
• addTextPreprocessor() registra pré-processadores que interceptam o texto antes da disposição dos glifos, do subsetting de fontes e do pipeline da árvore de estrutura. A execução respeita a ordem de registro.

Desempenho

A construção é O(engines eager) e não aloca memória de página até addPage(). A fachada não adiciona sobrecarga por chamada além do despacho dos métodos de trait. O pico de memória acompanha o conteúdo porque não há árvore de documento retida (Architecture Decision Record, ADR-001). Orçamento: 1500 ms / 64 MB para o início rápido canônico.

Notas de segurança

O documento recebe os dois registros por injeção e os trata como somente leitura, o que confina as falhas a uma única requisição. A política de incorporação de fontes é explícita. strictPdf20FontEmbedding() segue a exigência da ISO 32000-2:2020 §9.6.2: referências Base 14 não incorporadas lançam exceção no momento da gravação. allowNonEmbeddedBase14() fixa o caminho legado de aviso consultivo. A saída por meio de HasOutput::save() é atômica. A criptografia e a assinatura ficam na trait de segurança.

Conformidade

Afirmação	Fonte	Cláusula	reference_id
Cada página é representada por um ou mais content streams	ISO 32000-2:2020	§7.8.2
A árvore de páginas vincula os filhos por meio de arrays Kids de referências indiretas	ISO 32000-2:2020	§7.7.3

As cláusulas são parafraseadas; nenhum texto normativo é reproduzido.

Veja também

• /modules/core/core/ — Visão geral do módulo Core e do modelo de composição de concern traits
• /modules/core/core/has-pages/ — HasPages: ciclo de vida de páginas conduzido pela fachada
• /modules/core/core/has-text-output/ — HasTextOutput: o maior concern de autoria na fachada
• /modules/core/core/has-security/ — HasSecurity: delegação de criptografia e assinatura
• /modules/core/core/has-output/ — HasOutput: etapa final de serialização
• /modules/core/contracts/ — PdfDocumentInterface implementada pela fachada
• /modules/core/valueobjects/ — PageSize e Margin usados pelo exemplo de produção <!— evidence: src/Core/Document.php (final class Document implements PdfDocumentInterface; 21 use Concerns\Has* enumerated; class docblock “Disposable: each Document is use-once. Never reuse or reset.”; __construct(FontRegistryInterface,ImageRegistryInterface,?Config), eager engines list; createStandalone; addTextPreprocessor @since 1.9.0; fontMetrics(); setDPartRoot @since 1.12.0; strictPdf20FontEmbedding/allowNonEmbeddedBase14 @since 2.5.0 ISO §9.6.2; setChromeRendererConfig throws InvalidConfigException w/o nextpdf/artisan); src/Core/PdfFactory.php (immutable builder, new/with*/create, @since 3.1.0); .ai/manifest.json Core (Document.php danger_zone “Facade with 21 concern traits”); ADR-001; examples/01-hello-world.php, examples/02-pdf-factory.php; glossary Document/Concern trait. RAG iso32000_2_sec7 §7.8.2 , §7.7.3 >