Set up NextPDF and render your first PDF

NextPDF is a PHP library that creates PDF (Portable Document Format) files. In this tutorial you install it into an empty folder and render your first one-page document. You need a terminal and about ten minutes.

What you will build

You will build a tiny project that contains one script, 01-hello.php. The script renders a single page with a bold title line and one paragraph. It saves the result as out/hello.pdf. Along the way you learn two commands that confirm your installation is healthy.

This page teaches one install path: an empty folder plus the engine package. Other paths exist, such as framework adapters, browser-based renderers, and the Python client. Those live in Installation and Choose your path. You do not need them today.

Step 1: Create a project and install NextPDF

Composer is the package manager for PHP. It downloads libraries into your project and generates an autoloader. An autoloader is a small PHP file that finds library classes for you, so you never write long lists of includes.

Open a terminal and run these three commands:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer prints progress while it resolves and downloads packages. The exact lines vary with your Composer version and your local cache. A successful install ends without error text and looks roughly like this:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

What just happened

Composer created three things in your folder. composer.json records that your project depends on the engine. composer.lock pins the exact version it installed, so a later install resolves the same code. The vendor/ folder holds the downloaded packages, including vendor/autoload.php. Your script loads that one file, and every engine class becomes available.

Composer also checked your PHP setup during the install. The engine declares the PHP extensions it needs. Extensions are optional modules built into PHP. If one is missing, Composer stops and names it instead of leaving you with a broken install.

Step 2: Render your first PDF

Create a file named 01-hello.php next to composer.json. Paste in this complete program:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

$document->save(__DIR__ . '/out/hello.pdf');

echo "Wrote out/hello.pdf\n";

Run it:

php 01-hello.php

You should see exactly one line:

Wrote out/hello.pdf

Open out/hello.pdf in any PDF viewer. You will see the bold title line with the paragraph under it, and most viewers show “Hello from NextPDF” in their window title.

What just happened

Walk through the script from top to bottom:

require loads the Composer autoloader, so the Document class resolves.
@mkdir creates the out/ folder. The leading @ keeps the script quiet when the folder already exists, so you can run it again.
Document::createStandalone() returns a fresh document. It is made for short command-line scripts exactly like this one.
setTitle() sets the document title, which viewers show in the window title.
addPage() adds one empty page and places the cursor at the top left.
setFont() picks a font family, a style, and a size in points. Points are the standard unit for font sizes in print. 'B' means bold, and '' means regular. The family named helvetica is built in, so you need no font files.
cell() writes one line of text at the cursor. A width of 0 means “stretch to the right margin”. newLine: true moves the cursor down afterwards, like pressing Enter.
save() builds the finished PDF and writes it to disk.

One document produces one file. When you need a second PDF, create a fresh document rather than reusing the old one.

Step 3: Verify your setup

Two quick checks confirm this installation will keep working beyond one script.

First, list the extensions your PHP carries:

php -m

Scan the list for curl, gd, intl, mbstring, openssl, and zlib. The engine relies on these six. Composer already checked them in Step 1, so they should all appear.

Second, run the engine’s own health check:

vendor/bin/nextpdf doctor

On Windows, call vendor\bin\nextpdf doctor instead. The command inspects your PHP version, extensions, temporary folder, and configuration. Each check prints [OK], [WARN], or [FAIL], followed by one overall verdict.

What just happened

Read the Extensions block first. Six [OK] lines named curl, gd, intl, mbstring, openssl, and zlib mean your install is ready for every tutorial that follows.

The report also lists engine capabilities. On the free Core install, the capabilities that belong to the commercial packages print [FAIL] with a message naming the package that provides them. That is expected here, and it can turn the overall verdict to UNHEALTHY even though your Core setup is fine. For these tutorials, the Extensions block is the signal that matters.

If something went wrong

Match your symptom against these common cases first:

composer: command not found means Composer is missing or not on your PATH. Install it from getcomposer.org, then repeat Step 1.
Failed opening required '.../vendor/autoload.php' means the script ran outside the project folder, or the install did not finish. Change into the folder from Step 1 and run composer install.
If Composer stops during Step 1 and names a missing PHP extension, enable that extension in your php.ini. Confirm it with php -m, then repeat the install.
A [FAIL] line in the doctor’s Extensions block names a missing PHP extension. Enable it in php.ini, confirm with php -m, and run the doctor again. Capability [FAIL] lines that name a commercial package are expected on the Core install and need no action here.

For anything else, start with the troubleshooting knowledge base. If a script raises an exception, look up its class in the error reference; most beginner errors appear under general errors.

You have a working install and your first rendered file. Continue with Text, fonts, and page basics to control page sizes, built-in fonts, colors, and alignment.