API do Document
A classe Document (TcpdfNext\Core\Document) é o ponto de entrada principal para criação de documentos PDF. Ela compõe 12 traits, cada um contribuindo com um grupo de métodos relacionados. Todos os métodos mutáveis retornam static para encadeamento fluente.
php
use TcpdfNext\Core\Document;
$pdf = Document::create()
->setTitle('Invoice')
->addPage()
->setFont('Helvetica', size: 12)
->cell(width: 0, height: 10, text: 'Hello World')
->save('/output/invoice.pdf');HasMetadata
Métodos para definir metadados em nível de documento (Title, Author, Subject, Keywords, Creator).
setTitle(string $title): static
Definir o título do documento (aparece na barra de título do visualizador PDF e XMP dc:title).
setAuthor(string $author): static
Definir o autor do documento (XMP dc:creator).
setSubject(string $subject): static
Definir o assunto do documento (XMP dc:description).
setKeywords(string|array $keywords): static
Definir palavras-chave do documento. Aceita uma string separada por vírgulas ou um array de strings.
setCreator(string $creator): static
Definir o nome do aplicativo criador (XMP xmp:CreatorTool). Padrão: 'TCPDF-Next'.
HasPages
Métodos para adicionar, excluir, mover e configurar páginas.
addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static
Adicionar uma nova página. Opcionalmente, substitui o tamanho e orientação padrão da página apenas para esta página.
deletePage(int $pageNumber): static
Remover a página no índice baseado em 1. Lança OutOfRangeException se a página não existir.
movePage(int $from, int $to): static
Mover uma página de uma posição para outra. Ambos os índices são baseados em 1.
copyPage(int $pageNumber): static
Duplicar uma página e anexar a cópia após a última página.
setAutoPageBreak(bool $auto, float $margin = 0): static
Habilitar ou desabilitar quebras automáticas de página. Quando habilitado, uma nova página é adicionada quando o conteúdo atinge a margem inferior menos o valor da margem fornecido.
setMargins(float $left, float $top, float $right = -1, float $bottom = -1): static
Definir margens da página em unidades do usuário. Se right for -1, espelha left. Se bottom for -1, espelha top.
setLeftMargin(float $margin): static
Definir apenas a margem esquerda.
setTopMargin(float $margin): static
Definir apenas a margem superior.
setRightMargin(float $margin): static
Definir apenas a margem direita.
setCellPadding(float $padding): static
Definir o padding interno padrão da célula em unidades do usuário.
setPageSize(PageSize $size): static
Definir o tamanho de página padrão para novas páginas.
setOrientation(Orientation $orientation): static
Definir a orientação de página padrão para novas páginas.
pageCount(): int
Retornar o número total de páginas no documento.
currentPage(): int
Retornar o número da página atual (baseado em 1).
setPage(int $pageNumber): static
Mover o cursor para uma página existente.
HasTypography
Métodos para seleção de fonte, dimensionamento, espaçamento e medição de strings.
setFont(string $family, string $style = '', float $size = 0): static
Selecionar uma fonte pelo nome da família. Style pode ser '' (regular), 'B' (bold), 'I' (italic) ou 'BI'. Size 0 mantém o tamanho atual.
setFontSize(float $size): static
Definir o tamanho da fonte em pontos.
setFontSpacing(float $spacing): static
Definir espaçamento extra entre caracteres em unidades do usuário.
setFontStretching(float $percent): static
Definir escala horizontal da fonte como porcentagem (100 = normal).
getStringWidth(string $text, string $family = '', string $style = '', float $size = 0): float
Calcular a largura de uma string em unidades do usuário usando as configurações de fonte fornecidas (ou atuais).
getCharWidth(string $char): float
Retornar a largura de um único caractere em unidades do usuário.
getNumberOfLines(string $text, float $width): int
Estimar quantas linhas o texto ocupará na largura fornecida.
HasColors
Métodos para definir cores de traço, preenchimento e texto com transparência alfa opcional.
setDrawColor(int $r, int $g = -1, int $b = -1): static
Definir a cor de traço (draw). Passe um único valor para escala de cinza ou três valores para RGB.
setFillColor(int $r, int $g = -1, int $b = -1): static
Definir a cor de preenchimento para formas e fundos de células.
setTextColor(int $r, int $g = -1, int $b = -1): static
Definir a cor do texto.
setAlpha(float $alpha, string $blendMode = 'Normal'): static
Definir a transparência alfa (0.0 = totalmente transparente, 1.0 = totalmente opaco) e modo de mesclagem opcional.
setDrawColorObject(Color $color): static
Definir a cor de traço usando um value object Color (suporta RGB, CMYK, Gray, Spot).
setFillColorObject(Color $color): static
Definir a cor de preenchimento usando um value object Color.
setTextColorObject(Color $color): static
Definir a cor do texto usando um value object Color.
HasTextOutput
Métodos para renderizar conteúdo de texto na página.
cell(float $width, float $height = 0, string $text = '', string|int $border = 0, int $ln = 0, Alignment $align = Alignment::Left, bool $fill = false, string $link = ''): static
Imprimir uma célula de linha única. A célula pode ter borda, preenchimento de fundo e um hyperlink opcional.
multiCell(float $width, float $height, string $text, string|int $border = 0, Alignment $align = Alignment::Justified, bool $fill = false, int $maxLines = 0): static
Imprimir um bloco de texto multi-linha com quebra automática de linha.
text(float $x, float $y, string $text): static
Posicionar uma string de texto em coordenadas exatas. Sem quebra de linha ou limites de célula.
write(float $height, string $text, string $link = ''): static
Escrever texto fluido a partir da posição atual. Suporta hyperlinks inline.
writeHtml(string $html, bool $lineBreak = true, bool $fill = false, bool $resetStyles = false, string $align = ''): static
Renderizar uma string HTML com suporte CSS. Suporta tags HTML comuns, tabelas, listas e estilos inline.
writeHtmlCell(float $width, float $height, float $x, float $y, string $html, string|int $border = 0, int $ln = 0, bool $fill = false): static
Renderizar HTML dentro de uma célula posicionada.
ln(float $height = 0): static
Inserir uma quebra de linha. Se height for 0, usa a altura da última célula impressa.
HasDrawing
Métodos para desenhar linhas, formas e setas.
line(float $x1, float $y1, float $x2, float $y2): static
Desenhar uma linha reta entre dois pontos.
rect(float $x, float $y, float $w, float $h, string $style = ''): static
Desenhar um retângulo. Style: '' (traço), 'F' (preenchimento), 'DF' (traço + preenchimento).
roundedRect(float $x, float $y, float $w, float $h, float $r, string $roundCorner = '1111', string $style = ''): static
Desenhar um retângulo com cantos arredondados. A bitmask roundCorner controla quais cantos são arredondados.
circle(float $x, float $y, float $r, string $style = '', array $angles = [0, 360]): static
Desenhar um círculo (ou arco) com centro (x, y) e raio r.
ellipse(float $x, float $y, float $rx, float $ry, float $angle = 0, string $style = ''): static
Desenhar uma elipse com centro (x, y), raio horizontal rx e raio vertical ry.
polygon(array $points, string $style = ''): static
Desenhar um polígono a partir de um array de pares de coordenadas [x, y].
arrow(float $x1, float $y1, float $x2, float $y2, int $headStyle = 0, float $armSize = 5, int $armAngle = 15): static
Desenhar uma linha com ponta de seta.
curve(float $x0, float $y0, float $x1, float $y1, float $x2, float $y2, float $x3, float $y3, string $style = ''): static
Desenhar uma curva Bezier cúbica.
setLineWidth(float $width): static
Definir a largura da linha para operações de traço.
setLineCap(int $style): static
Definir o estilo de ponta de linha: 0 (butt), 1 (round), 2 (square).
setLineJoin(int $style): static
Definir o estilo de junção de linha: 0 (miter), 1 (round), 2 (bevel).
HasTransforms
Métodos para transformações do sistema de coordenadas (salvas como uma pilha).
startTransform(): static
Salvar o estado gráfico atual. Deve ser pareado com stopTransform().
stopTransform(): static
Restaurar o estado gráfico previamente salvo.
rotate(float $angle, float $x = null, float $y = null): static
Rotacionar operações de desenho subsequentes pelo ângulo fornecido (graus) ao redor do ponto (x, y).
scale(float $sx, float $sy, float $x = null, float $y = null): static
Escalar operações de desenho subsequentes. 100 = sem alteração, 200 = dobro do tamanho.
translate(float $tx, float $ty): static
Transladar (deslocar) operações de desenho subsequentes por (tx, ty) unidades do usuário.
skew(float $angleX, float $angleY, float $x = null, float $y = null): static
Inclinar operações de desenho subsequentes pelos ângulos fornecidos (graus).
mirror(string $axis, float $x = null, float $y = null): static
Espelhar operações de desenho subsequentes ao longo do eixo fornecido ('H' horizontal, 'V' vertical).
HasLayout
Métodos para cabeçalhos, rodapés, colunas e modo caderno.
setHeaderCallback(callable $callback): static
Registrar um callback invocado no topo de cada página. Recebe a instância do Document.
setFooterCallback(callable $callback): static
Registrar um callback invocado no rodapé de cada página. Recebe a instância do Document.
setColumnsArray(array $columns): static
Definir um layout multi-coluna. Cada entrada é um array associativo com chaves 'width' e opcionalmente 'margin'.
selectColumn(int $column = 0): static
Mover o cursor para a coluna especificada (baseado em 0).
setBooklet(bool $enable, float $innerMargin = -1, float $outerMargin = -1): static
Habilitar modo caderno (saddle-stitch) com margens internas e externas configuráveis.
setPrintHeader(bool $print): static
Habilitar ou desabilitar o cabeçalho nas páginas subsequentes.
setPrintFooter(bool $print): static
Habilitar ou desabilitar o rodapé nas páginas subsequentes.
HasNavigation
Métodos para marcadores, sumário, links, anotações e anexos de arquivo.
bookmark(string $title, int $level = 0, float $y = -1, int $page = 0, string $style = '', Color $color = null): static
Adicionar um marcador (entrada de contorno). Nível 0 é o nível superior; valores maiores criam filhos aninhados.
addTOC(int $page = 0, string $numberFormat = '', string $filler = '.'): static
Gerar um sumário a partir de todos os marcadores e inseri-lo na página fornecida.
addLink(): int
Criar um destino de link interno e retornar seu identificador.
setLink(int $linkId, float $y = 0, int $page = -1): static
Definir o destino para um link interno previamente criado.
annotation(float $x, float $y, float $w, float $h, string $text, array $options = []): static
Adicionar uma anotação de texto no retângulo fornecido.
addFileAttachment(string $filePath, string $description = '', string $name = ''): static
Anexar um arquivo ao documento. Suporta arquivos associados PDF/A-3.
HasInteractive
Métodos para campos de formulário AcroForm e JavaScript.
textField(string $name, float $x, float $y, float $w, float $h, array $options = []): static
Adicionar um campo de entrada de texto na posição fornecida.
checkboxField(string $name, float $x, float $y, float $size = 10, bool $checked = false): static
Adicionar um campo checkbox.
radioField(string $name, float $x, float $y, float $size = 10, array $options = []): static
Adicionar um campo de botão de rádio como parte de um grupo nomeado.
listboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static
Adicionar um campo de seleção listbox.
comboboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static
Adicionar um campo combobox dropdown.
buttonField(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static
Adicionar um campo de botão push com ação JavaScript opcional.
includeJS(string $script): static
Incorporar uma ação JavaScript em nível de documento. Executada quando o documento é aberto.
HasSecurity
Métodos para criptografia e assinaturas digitais.
setProtection(array $permissions = [], string $userPassword = '', string $ownerPassword = '', int $mode = 3): static
Criptografar o documento com AES-256 (mode 3). Permissões: 'print', 'copy', 'modify', 'annot-forms', etc.
setSignature(string $certFile, string $privateKeyFile, string $password = '', string $extracertsFile = '', int $certType = 2, array $info = []): static
Aplicar uma assinatura digital PAdES. Use certType 2 para arquivos PKCS#12 (.p12/.pfx).
HasOutput
Métodos para renderizar o PDF final.
save(string $path): bool
Gravar o PDF em um arquivo. Retorna true em caso de sucesso.
output(OutputDestination $destination = OutputDestination::String, string $filename = 'doc.pdf', string $path = ''): string|bool
Renderizar o PDF para o destino escolhido: String (retornar binário), File, Inline (navegador) ou Download.
toString(): string
Alias de conveniência para output(OutputDestination::String). Retorna o binário PDF bruto.
Veja Também
- Visão Geral da API -- Todos os pacotes em resumo
- Referência de Enums -- Orientation, Alignment, OutputDestination e mais
- Referência de Interfaces -- Contratos que a classe Document implementa
- API de Value Objects -- PageSize, Margin, Position, Dimension, Unit