Document API

The Document class (TcpdfNext\Core\Document) is the primary entry point for creating PDF documents. It composes 12 traits, each contributing a group of related methods. All mutating methods return static for fluent chaining.

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

Methods for setting document-level metadata (Title, Author, Subject, Keywords, Creator).

setTitle(string $title): static

Set the document title (appears in PDF viewer title bar and XMP dc:title).

setAuthor(string $author): static

Set the document author (XMP dc:creator).

setSubject(string $subject): static

Set the document subject (XMP dc:description).

setKeywords(string|array $keywords): static

Set document keywords. Accepts a comma-separated string or an array of strings.

setCreator(string $creator): static

Set the creator application name (XMP xmp:CreatorTool). Defaults to 'TCPDF-Next'.

HasPages

Methods for adding, deleting, moving, and configuring pages.

addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static

Add a new page. Optionally override the default page size and orientation for this page only.

deletePage(int $pageNumber): static

Remove the page at the given 1-based index. Throws OutOfRangeException if the page does not exist.

movePage(int $from, int $to): static

Move a page from one position to another. Both indices are 1-based.

copyPage(int $pageNumber): static

Duplicate a page and append the copy after the last page.

setAutoPageBreak(bool $auto, float $margin = 0): static

Enable or disable automatic page breaks. When enabled, a new page is added when content reaches the bottom margin minus the given margin value.

setMargins(float $left, float $top, float $right = -1, float $bottom = -1): static

Set page margins in user units. If right is -1, it mirrors left. If bottom is -1, it mirrors top.

setLeftMargin(float $margin): static

Set the left margin only.

setTopMargin(float $margin): static

Set the top margin only.

setRightMargin(float $margin): static

Set the right margin only.

setCellPadding(float $padding): static

Set the default internal cell padding in user units.

setPageSize(PageSize $size): static

Set the default page size for new pages.

setOrientation(Orientation $orientation): static

Set the default page orientation for new pages.

pageCount(): int

Return the total number of pages in the document.

currentPage(): int

Return the current page number (1-based).

setPage(int $pageNumber): static

Move the cursor to an existing page.

HasTypography

Methods for font selection, sizing, spacing, and string measurement.

setFont(string $family, string $style = '', float $size = 0): static

Select a font by family name. Style can be '' (regular), 'B' (bold), 'I' (italic), or 'BI'. Size 0 keeps the current size.

setFontSize(float $size): static

Set the font size in points.

setFontSpacing(float $spacing): static

Set extra character spacing in user units.

setFontStretching(float $percent): static

Set horizontal font scaling as a percentage (100 = normal).

getStringWidth(string $text, string $family = '', string $style = '', float $size = 0): float

Calculate the width of a string in user units using the given (or current) font settings.

getCharWidth(string $char): float

Return the width of a single character in user units.

getNumberOfLines(string $text, float $width): int

Estimate how many lines the text will occupy at the given width.

HasColors

Methods for setting draw, fill, and text colors with optional alpha transparency.

setDrawColor(int $r, int $g = -1, int $b = -1): static

Set the stroke (draw) color. Pass a single value for grayscale or three values for RGB.

setFillColor(int $r, int $g = -1, int $b = -1): static

Set the fill color for shapes and cell backgrounds.

setTextColor(int $r, int $g = -1, int $b = -1): static

Set the text color.

setAlpha(float $alpha, string $blendMode = 'Normal'): static

Set the alpha transparency (0.0 = fully transparent, 1.0 = fully opaque) and optional blend mode.

setDrawColorObject(Color $color): static

Set the stroke color using a Color value object (supports RGB, CMYK, Gray, Spot).

setFillColorObject(Color $color): static

Set the fill color using a Color value object.

setTextColorObject(Color $color): static

Set the text color using a Color value object.

HasTextOutput

Methods for rendering text content onto the page.

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

Print a single-line cell. The cell can have a border, background fill, and an optional hyperlink.

multiCell(float $width, float $height, string $text, string|int $border = 0, Alignment $align = Alignment::Justified, bool $fill = false, int $maxLines = 0): static

Print a multi-line text block with automatic line wrapping.

text(float $x, float $y, string $text): static

Place a text string at exact coordinates. No line wrapping or cell boundaries.

write(float $height, string $text, string $link = ''): static

Write flowing text from the current position. Supports inline hyperlinks.

writeHtml(string $html, bool $lineBreak = true, bool $fill = false, bool $resetStyles = false, string $align = ''): static

Render an HTML string with CSS support. Supports common HTML tags, tables, lists, and inline styles.

writeHtmlCell(float $width, float $height, float $x, float $y, string $html, string|int $border = 0, int $ln = 0, bool $fill = false): static

Render HTML inside a positioned cell.

ln(float $height = 0): static

Insert a line break. If height is 0, uses the height of the last printed cell.

HasDrawing

Methods for drawing lines, shapes, and arrows.

line(float $x1, float $y1, float $x2, float $y2): static

Draw a straight line between two points.

rect(float $x, float $y, float $w, float $h, string $style = ''): static

Draw a rectangle. Style: '' (stroke), 'F' (fill), 'DF' (stroke + fill).

roundedRect(float $x, float $y, float $w, float $h, float $r, string $roundCorner = '1111', string $style = ''): static

Draw a rectangle with rounded corners. The roundCorner bitmask controls which corners are rounded.

circle(float $x, float $y, float $r, string $style = '', array $angles = [0, 360]): static

Draw a circle (or arc) with center (x, y) and radius r.

ellipse(float $x, float $y, float $rx, float $ry, float $angle = 0, string $style = ''): static

Draw an ellipse with center (x, y), horizontal radius rx, and vertical radius ry.

polygon(array $points, string $style = ''): static

Draw a polygon from an array of [x, y] coordinate pairs.

arrow(float $x1, float $y1, float $x2, float $y2, int $headStyle = 0, float $armSize = 5, int $armAngle = 15): static

Draw a line with an arrowhead.

curve(float $x0, float $y0, float $x1, float $y1, float $x2, float $y2, float $x3, float $y3, string $style = ''): static

Draw a cubic Bezier curve.

setLineWidth(float $width): static

Set the line width for stroke operations.

setLineCap(int $style): static

Set the line cap style: 0 (butt), 1 (round), 2 (square).

setLineJoin(int $style): static

Set the line join style: 0 (miter), 1 (round), 2 (bevel).

HasTransforms

Methods for coordinate system transformations (saved as a stack).

startTransform(): static

Save the current graphics state. Must be paired with stopTransform().

stopTransform(): static

Restore the previously saved graphics state.

rotate(float $angle, float $x = null, float $y = null): static

Rotate subsequent drawing operations by the given angle (degrees) around the point (x, y).

scale(float $sx, float $sy, float $x = null, float $y = null): static

Scale subsequent drawing operations. 100 = no change, 200 = double size.

translate(float $tx, float $ty): static

Translate (shift) subsequent drawing operations by (tx, ty) user units.

skew(float $angleX, float $angleY, float $x = null, float $y = null): static

Skew subsequent drawing operations by the given angles (degrees).

mirror(string $axis, float $x = null, float $y = null): static

Mirror subsequent drawing operations along the given axis ('H' horizontal, 'V' vertical).

HasLayout

Methods for headers, footers, columns, and booklet mode.

setHeaderCallback(callable $callback): static

setFooterCallback(callable $callback): static

setColumnsArray(array $columns): static

Define a multi-column layout. Each entry is an associative array with 'width' and optional 'margin' keys.

selectColumn(int $column = 0): static

Move the cursor to the specified column (0-based).

setBooklet(bool $enable, float $innerMargin = -1, float $outerMargin = -1): static

Enable booklet (saddle-stitch) mode with configurable inner and outer margins.

setPrintHeader(bool $print): static

Enable or disable the header on subsequent pages.

setPrintFooter(bool $print): static

Enable or disable the footer on subsequent pages.

HasNavigation

Methods for bookmarks, table of contents, links, annotations, and file attachments.

bookmark(string $title, int $level = 0, float $y = -1, int $page = 0, string $style = '', Color $color = null): static

Add a bookmark (outline entry). Level 0 is the top level; higher values create nested children.

addTOC(int $page = 0, string $numberFormat = '', string $filler = '.'): static

Generate a table of contents from all bookmarks and insert it at the given page.

addLink(): int

Create an internal link destination and return its identifier.

setLink(int $linkId, float $y = 0, int $page = -1): static

Set the destination for a previously created internal link.

annotation(float $x, float $y, float $w, float $h, string $text, array $options = []): static

Add a text annotation at the given rectangle.

addFileAttachment(string $filePath, string $description = '', string $name = ''): static

Attach a file to the document. Supports PDF/A-3 associated files.

HasInteractive

Methods for AcroForm form fields and JavaScript.

textField(string $name, float $x, float $y, float $w, float $h, array $options = []): static

Add a text input field at the given position.

checkboxField(string $name, float $x, float $y, float $size = 10, bool $checked = false): static

Add a checkbox field.

radioField(string $name, float $x, float $y, float $size = 10, array $options = []): static

Add a radio button field as part of a named group.

listboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static

Add a listbox selection field.

comboboxField(string $name, float $x, float $y, float $w, float $h, array $items, array $options = []): static

Add a dropdown combobox field.

buttonField(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static

Add a push button field with an optional JavaScript action.

includeJS(string $script): static

Embed a document-level JavaScript action. Executed when the document is opened.

HasSecurity

Methods for encryption and digital signatures.

setProtection(array $permissions = [], string $userPassword = '', string $ownerPassword = '', int $mode = 3): static

Encrypt the document with AES-256 (mode 3). Permissions: 'print', 'copy', 'modify', 'annot-forms', etc.

setSignature(string $certFile, string $privateKeyFile, string $password = '', string $extracertsFile = '', int $certType = 2, array $info = []): static

Apply a PAdES digital signature. Use certType 2 for PKCS#12 (.p12/.pfx) files.

HasOutput

Methods for rendering the final PDF.

save(string $path): bool

Write the PDF to a file. Returns true on success.

output(OutputDestination $destination = OutputDestination::String, string $filename = 'doc.pdf', string $path = ''): string|bool

Render the PDF to the chosen destination: String (return binary), File, Inline (browser), or Download.

toString(): string

Convenience alias for output(OutputDestination::String). Returns the raw PDF binary.

Document API ​

HasMetadata ​

HasPages ​

HasTypography ​

HasColors ​

HasTextOutput ​

HasDrawing ​

HasTransforms ​

HasLayout ​

HasNavigation ​

HasInteractive ​

HasSecurity ​

HasOutput ​

See Also ​