API de Document
La clase Document (TcpdfNext\Core\Document) es el punto de entrada principal para crear documentos PDF. Compone 12 traits, cada uno contribuyendo un grupo de métodos relacionados. Todos los métodos mutantes retornan static para encadenamiento fluent.
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 establecer metadatos a nivel de documento (Title, Author, Subject, Keywords, Creator).
setTitle(string $title): static
Establecer el título del documento (aparece en la barra de título del visor PDF y en XMP dc:title).
setAuthor(string $author): static
Establecer el autor del documento (XMP dc:creator).
setSubject(string $subject): static
Establecer el asunto del documento (XMP dc:description).
setKeywords(string|array $keywords): static
Establecer las palabras clave del documento. Acepta una cadena separada por comas o un array de cadenas.
setCreator(string $creator): static
Establecer el nombre de la aplicación creadora (XMP xmp:CreatorTool). Por defecto es 'TCPDF-Next'.
HasPages
Métodos para agregar, eliminar, mover y configurar páginas.
addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static
Agregar una nueva página. Opcionalmente sobrescribe el tamaño y orientación de página predeterminados solo para esta página.
deletePage(int $pageNumber): static
Eliminar la página en el índice dado (basado en 1). Lanza OutOfRangeException si la página no existe.
movePage(int $from, int $to): static
Mover una página de una posición a otra. Ambos índices son basados en 1.
copyPage(int $pageNumber): static
Duplicar una página y agregar la copia después de la última página.
setAutoPageBreak(bool $auto, float $margin = 0): static
Habilitar o deshabilitar saltos de página automáticos. Cuando está habilitado, se agrega una nueva página cuando el contenido alcanza el margen inferior menos el valor de margen dado.
setMargins(float $left, float $top, float $right = -1, float $bottom = -1): static
Establecer márgenes de página en unidades de usuario. Si right es -1, refleja left. Si bottom es -1, refleja top.
setLeftMargin(float $margin): static
Establecer solo el margen izquierdo.
setTopMargin(float $margin): static
Establecer solo el margen superior.
setRightMargin(float $margin): static
Establecer solo el margen derecho.
setCellPadding(float $padding): static
Establecer el padding interno predeterminado de celda en unidades de usuario.
setPageSize(PageSize $size): static
Establecer el tamaño de página predeterminado para nuevas páginas.
setOrientation(Orientation $orientation): static
Establecer la orientación de página predeterminada para nuevas páginas.
pageCount(): int
Retornar el número total de páginas en el documento.
currentPage(): int
Retornar el número de página actual (basado en 1).
setPage(int $pageNumber): static
Mover el cursor a una página existente.
HasTypography
Métodos para selección de fuente, tamaño, espaciado y medición de cadenas.
setFont(string $family, string $style = '', float $size = 0): static
Seleccionar una fuente por nombre de familia. El estilo puede ser '' (regular), 'B' (bold), 'I' (italic) o 'BI'. Tamaño 0 mantiene el tamaño actual.
setFontSize(float $size): static
Establecer el tamaño de fuente en puntos.
setFontSpacing(float $spacing): static
Establecer espaciado extra entre caracteres en unidades de usuario.
setFontStretching(float $percent): static
Establecer la escala horizontal de fuente como porcentaje (100 = normal).
getStringWidth(string $text, string $family = '', string $style = '', float $size = 0): float
Calcular el ancho de una cadena en unidades de usuario usando la configuración de fuente dada (o actual).
getCharWidth(string $char): float
Retornar el ancho de un solo carácter en unidades de usuario.
getNumberOfLines(string $text, float $width): int
Estimar cuántas líneas ocupará el texto en el ancho dado.
HasColors
Métodos para establecer colores de trazo, relleno y texto con transparencia alpha opcional.
setDrawColor(int $r, int $g = -1, int $b = -1): static
Establecer el color de trazo (draw). Pasa un solo valor para escala de grises o tres valores para RGB.
setFillColor(int $r, int $g = -1, int $b = -1): static
Establecer el color de relleno para formas y fondos de celda.
setTextColor(int $r, int $g = -1, int $b = -1): static
Establecer el color del texto.
setAlpha(float $alpha, string $blendMode = 'Normal'): static
Establecer la transparencia alpha (0.0 = totalmente transparente, 1.0 = totalmente opaco) y modo de mezcla opcional.
setDrawColorObject(Color $color): static
Establecer el color de trazo usando un value object Color (soporta RGB, CMYK, Gray, Spot).
setFillColorObject(Color $color): static
Establecer el color de relleno usando un value object Color.
setTextColorObject(Color $color): static
Establecer el color de texto usando un value object Color.
HasTextOutput
Métodos para renderizar contenido de texto en la 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 una celda de línea única. La celda puede tener borde, relleno de fondo y un hipervínculo opcional.
multiCell(float $width, float $height, string $text, string|int $border = 0, Alignment $align = Alignment::Justified, bool $fill = false, int $maxLines = 0): static
Imprimir un bloque de texto multilínea con ajuste de línea automático.
text(float $x, float $y, string $text): static
Colocar una cadena de texto en coordenadas exactas. Sin ajuste de línea ni límites de celda.
write(float $height, string $text, string $link = ''): static
Escribir texto fluido desde la posición actual. Soporta hipervínculos en línea.
writeHtml(string $html, bool $lineBreak = true, bool $fill = false, bool $resetStyles = false, string $align = ''): static
Renderizar una cadena HTML con soporte CSS. Soporta etiquetas HTML comunes, tablas, listas y estilos en línea.
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 una celda posicionada.
ln(float $height = 0): static
Insertar un salto de línea. Si la altura es 0, usa la altura de la última celda impresa.
HasDrawing
Métodos para dibujar líneas, formas y flechas.
line(float $x1, float $y1, float $x2, float $y2): static
Dibujar una línea recta entre dos puntos.
rect(float $x, float $y, float $w, float $h, string $style = ''): static
Dibujar un rectángulo. Estilo: '' (trazo), 'F' (relleno), 'DF' (trazo + relleno).
roundedRect(float $x, float $y, float $w, float $h, float $r, string $roundCorner = '1111', string $style = ''): static
Dibujar un rectángulo con esquinas redondeadas. La máscara de bits roundCorner controla qué esquinas se redondean.
circle(float $x, float $y, float $r, string $style = '', array $angles = [0, 360]): static
Dibujar un círculo (o arco) con centro (x, y) y radio r.
ellipse(float $x, float $y, float $rx, float $ry, float $angle = 0, string $style = ''): static
Dibujar una elipse con centro (x, y), radio horizontal rx y radio vertical ry.
polygon(array $points, string $style = ''): static
Dibujar un polígono desde un 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
Dibujar una línea con punta de flecha.
curve(float $x0, float $y0, float $x1, float $y1, float $x2, float $y2, float $x3, float $y3, string $style = ''): static
Dibujar una curva Bezier cúbica.
setLineWidth(float $width): static
Establecer el ancho de línea para operaciones de trazo.
setLineCap(int $style): static
Establecer el estilo de terminación de línea: 0 (butt), 1 (round), 2 (square).
setLineJoin(int $style): static
Establecer el estilo de unión de línea: 0 (miter), 1 (round), 2 (bevel).
HasTransforms
Métodos para transformaciones del sistema de coordenadas (guardadas como pila).
startTransform(): static
Guardar el estado gráfico actual. Debe emparejarse con stopTransform().
stopTransform(): static
Restaurar el estado gráfico guardado previamente.
rotate(float $angle, float $x = null, float $y = null): static
Rotar las operaciones de dibujo subsiguientes por el ángulo dado (grados) alrededor del punto (x, y).
scale(float $sx, float $sy, float $x = null, float $y = null): static
Escalar las operaciones de dibujo subsiguientes. 100 = sin cambio, 200 = doble tamaño.
translate(float $tx, float $ty): static
Trasladar (desplazar) las operaciones de dibujo subsiguientes por (tx, ty) unidades de usuario.
skew(float $angleX, float $angleY, float $x = null, float $y = null): static
Sesgar las operaciones de dibujo subsiguientes por los ángulos dados (grados).
mirror(string $axis, float $x = null, float $y = null): static
Reflejar las operaciones de dibujo subsiguientes a lo largo del eje dado ('H' horizontal, 'V' vertical).
HasLayout
Métodos para encabezados, pies de página, columnas y modo folleto.
setHeaderCallback(callable $callback): static
Registrar un callback invocado en la parte superior de cada página. Recibe la instancia de Document.
setFooterCallback(callable $callback): static
Registrar un callback invocado en la parte inferior de cada página. Recibe la instancia de Document.
setColumnsArray(array $columns): static
Definir un diseño multi-columna. Cada entrada es un array asociativo con claves 'width' y opcionalmente 'margin'.
selectColumn(int $column = 0): static
Mover el cursor a la columna especificada (basada en 0).
setBooklet(bool $enable, float $innerMargin = -1, float $outerMargin = -1): static
Habilitar el modo folleto (cosido de caballete) con márgenes internos y externos configurables.
setPrintHeader(bool $print): static
Habilitar o deshabilitar el encabezado en páginas subsiguientes.
setPrintFooter(bool $print): static
Habilitar o deshabilitar el pie de página en páginas subsiguientes.
HasNavigation
Métodos para marcadores, tabla de contenidos, enlaces, anotaciones y archivos adjuntos.
bookmark(string $title, int $level = 0, float $y = -1, int $page = 0, string $style = '', Color $color = null): static
Agregar un marcador (entrada de esquema). El nivel 0 es el nivel superior; valores mayores crean hijos anidados.
addTOC(int $page = 0, string $numberFormat = '', string $filler = '.'): static
Generar una tabla de contenidos desde todos los marcadores e insertarla en la página dada.
addLink(): int
Crear un destino de enlace interno y retornar su identificador.
setLink(int $linkId, float $y = 0, int $page = -1): static
Establecer el destino para un enlace interno previamente creado.
annotation(float $x, float $y, float $w, float $h, string $text, array $options = []): static
Agregar una anotación de texto en el rectángulo dado.
addFileAttachment(string $filePath, string $description = '', string $name = ''): static
Adjuntar un archivo al documento. Soporta archivos asociados PDF/A-3.
HasInteractive
Métodos para campos de formulario AcroForm y JavaScript.
textField(string $name, float $x, float $y, float $w, float $h, array $options = []): static
Agregar un campo de entrada de texto en la posición dada.
checkboxField(string $name, float $x, float $y, float $size = 10, bool $checked = false): static
Agregar un campo checkbox.
radioField(string $name, float $x, float $y, float $size = 10, array $options = []): static
Agregar un campo de botón radio como parte de un grupo nombrado.
listboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static
Agregar un campo de selección listbox.
comboboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static
Agregar un campo combobox desplegable.
buttonField(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static
Agregar un campo de botón con una acción JavaScript opcional.
includeJS(string $script): static
Incrustar una acción JavaScript a nivel de documento. Se ejecuta cuando se abre el documento.
HasSecurity
Métodos para cifrado y firmas digitales.
setProtection(array $permissions = [], string $userPassword = '', string $ownerPassword = '', int $mode = 3): static
Cifrar el documento con AES-256 (mode 3). Permisos: 'print', 'copy', 'modify', 'annot-forms', etc.
setSignature(string $certFile, string $privateKeyFile, string $password = '', string $extracertsFile = '', int $certType = 2, array $info = []): static
Aplicar una firma digital PAdES. Usa certType 2 para archivos PKCS#12 (.p12/.pfx).
HasOutput
Métodos para renderizar el PDF final.
save(string $path): bool
Escribir el PDF a un archivo. Retorna true en caso de éxito.
output(OutputDestination $destination = OutputDestination::String, string $filename = 'doc.pdf', string $path = ''): string|bool
Renderizar el PDF al destino elegido: String (retornar binario), File, Inline (navegador) o Download.
toString(): string
Alias de conveniencia para output(OutputDestination::String). Retorna el binario PDF sin procesar.
Ver también
- Resumen API -- Todos los paquetes de un vistazo
- Referencia de Enums -- Orientation, Alignment, OutputDestination y más
- Referencia de Interfaces -- Contratos que implementa la clase Document
- API de Value Objects -- PageSize, Margin, Position, Dimension, Unit