Text, Schriften und Seitengrundlagen

Im ersten Tutorial haben Sie eine Seite mit einer einzigen Textzeile gerendert. Diesmal übernehmen Sie die Kontrolle über die Seite selbst und über den Text darauf. Sie wählen eine Seitengröße, schreiben Überschriften und Absätze und formatieren sie mit den eingebauten Schriften der Engine.

Was Sie erstellen

Sie schreiben zwei kleine Skripte. Jedes davon erzeugt eine einseitige Datei im Portable Document Format (PDF):

• 01-text-basics.php rendert eine A4-Hochformatseite mit einer farbigen Überschrift, umbrochenen Absätzen und drei Ausrichtungsbeispielen.
• 02-fonts.php rendert eine Musterseite, die zwei eingebaute Schriftfamilien in mehreren Größen vergleicht.

Alles läuft allein mit dem Paket nextpdf/core. Sie benötigen keine Schriftdateien, keine zusätzlichen Erweiterungen und kein Netzwerk. Falls Sie noch kein Projekt eingerichtet haben, folgen Sie zuerst dem ersten Tutorial und kehren Sie dann zurück.

Schritt 1: Text auf einer A4-Seite formatieren

Jede Seite hat eine Größe und eine Ausrichtung. A4 ist das übliche internationale Papierformat, und Letter ist sein Gegenstück in den Vereinigten Staaten. Die Ausrichtung ist entweder Hochformat (aufrecht) oder Querformat (quer). Sie übergeben beide Entscheidungen an addPage(), wenn Sie eine Seite beginnen.

Drei Methoden übernehmen dann das Schreiben. setFont() wählt Schriftart und Größe für den folgenden Text. cell() schreibt eine Zeile innerhalb eines unsichtbaren Kastens. multiCell() bricht längeren Text in so viele Zeilen um, wie nötig sind. In beiden Methoden bedeutet eine Breite von 0 „alles bis zum rechten Rand nutzen”.

Zwei weitere Aufrufe bestimmen das Erscheinungsbild. setTextColor() nimmt Rot-, Grün- und Blauwerte von 0 bis 255 entgegen, und die Farbe gilt, bis Sie sie erneut ändern. Das Enum Alignment, eine feste Liste benannter Optionen, bietet Left, Center, Right und Justify.

Erstellen Sie 01-text-basics.php in Ihrem Projektordner:

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\Orientation;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Text basics');
$document->addPage(PageSize::A4(), Orientation::Portrait);

// A colored heading. The values are red, green, and blue, each 0 to 255.
$document->setFont('helvetica', 'B', 20);
$document->setTextColor(30, 64, 175);
$document->cell(0, 14, 'Project kickoff notes', newLine: true);
$document->ln(4);

// Back to black for the body text.
$document->setTextColor(0, 0, 0);
$document->setFont('helvetica', '', 11);
$document->multiCell(
    0,
    7,
    'Welcome to the second tutorial. This paragraph is written with '
        . 'multiCell(), so the engine wraps the words onto as many lines '
        . 'as the page width requires.',
);
$document->ln(4);

$document->multiCell(
    0,
    7,
    'Justified text stretches the spaces so both edges line up. It is a '
        . 'good fit for report bodies and other long passages.',
    align: Alignment::Justify,
);
$document->ln(6);

// One line each: left, centered, and right.
$document->setFont('helvetica', 'I', 11);
$document->cell(0, 8, 'Left-aligned line', newLine: true, align: Alignment::Left);
$document->cell(0, 8, 'Centered line', newLine: true, align: Alignment::Center);
$document->cell(0, 8, 'Right-aligned line', newLine: true, align: Alignment::Right);

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

echo "Wrote out/text-basics.pdf\n";

Führen Sie es mit php 01-text-basics.php aus. Das Skript gibt Wrote out/text-basics.pdf aus, und die Datei erscheint im neuen Ordner out/.

Was gerade passiert ist

addPage(PageSize::A4(), Orientation::Portrait) hat die Seite erstellt, bevor Text geschrieben wurde. Übergeben Sie stattdessen Orientation::Landscape, und dieselbe Seite dreht sich ins Querformat. Andere benannte Größen wie PageSize::A5() oder PageSize::Letter() funktionieren auf die gleiche Weise.

setFont('helvetica', 'B', 20) hat fettes Helvetica in 20 Punkt ausgewählt. Ein Punkt (pt) ist die traditionelle Druckeinheit; 72 Punkt entsprechen einem Zoll. Die Überschrift ist blau, weil setTextColor(30, 64, 175) aktiv war, als der Aufruf von cell() sie geschrieben hat. Der nächste setTextColor(0, 0, 0) hat für alles danach wieder auf Schwarz umgeschaltet.

Die beiden Aufrufe von multiCell() haben ihre Absätze automatisch umbrochen. Der Absatz im Blocksatz dehnt die Wortabstände, sodass beide Kanten bündig sind, mit Ausnahme der letzten Zeile des Absatzes. Zwischen den Blöcken hat ln() die Schreibposition nach unten verschoben, um für etwas Luft zu sorgen. Schließlich hat save() die Datei erstellt und in out/ geschrieben.

Alle Parameter, die diese Methoden akzeptieren, finden Sie unter Text mit Schriften und Ausrichtung zusammenstellen.

Schritt 2: Unter den eingebauten Schriften wählen

Die Engine bringt drei Textfamilien fest eingebaut mit: Helvetica, Times und Courier. Helvetica ist eine serifenlose Schrift, das heißt, ihre Buchstaben haben keine kleinen Endstriche (Serifen). Times ist eine Serifenschrift, die sich in langen, druckähnlichen Passagen gut liest. Courier hat eine feste Breite und eignet sich daher für Code-Listings und Belege. Da diese Familien eingebaut sind, benötigen Ihre Skripte überhaupt keine Schriftdateien.

Das Stilargument von setFont() kombiniert Ein-Buchstaben-Flags: 'B' für fett, 'I' für kursiv und 'U' für unterstrichen. Eine leere Zeichenkette bedeutet regulär, und die Flags lassen sich kombinieren, sodass 'BI' fett-kursiv ergibt.

Die eingebauten Familien decken lateinbasierten Text ab. Für andere Schriftsysteme oder Ihre eigene Markenschrift registrieren Sie eine Schriftdatei, wie das Rezept Schriften einbetten und als Teilmenge einbinden zeigt (das Bilden einer Teilmenge behält nur die tatsächlich verwendeten Zeichen, sodass die Dateien klein bleiben). Die Schriftunterstützungsmatrix listet jedes Schriftformat auf, das die Engine akzeptiert.

Erstellen Sie 02-fonts.php neben dem ersten Skript:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Font sampler');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 14, 'Built-in font sampler', newLine: true);
$document->ln(4);

// Helvetica: a sans-serif face, a solid default for labels and headings.
$document->setFont('helvetica', 'B', 14);
$document->cell(0, 10, 'Helvetica', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('helvetica', '', (float) $size);
    $document->cell(0, $size * 0.8, "Helvetica sample at {$size}pt.", newLine: true);
}
$document->setFont('helvetica', 'BI', 12);
$document->cell(0, 9, 'Helvetica bold italic for emphasis.', newLine: true);
$document->ln(6);

// Times: a serif face that suits long, print-like passages.
$document->setFont('times', 'B', 14);
$document->cell(0, 10, 'Times', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('times', '', (float) $size);
    $document->cell(0, $size * 0.8, "Times sample at {$size}pt.", newLine: true);
}
$document->setFont('times', 'I', 12);
$document->cell(0, 9, 'Times italic for quotations.', newLine: true);

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

echo "Wrote out/font-sampler.pdf\n";

Führen Sie es mit php 02-fonts.php aus und öffnen Sie out/font-sampler.pdf. Sie sehen, wie derselbe Beispielsatz zwischen den beiden Familien seinen Charakter wechselt und über drei Größen hinweg wächst.

Was gerade passiert ist

addPage() ohne Argumente hat die Standard-Seiteneinrichtung im Hochformat verwendet, sodass nicht jedes Skript die Größe ausschreiben muss. Jeder Aufruf von setFont() hat mitten auf der Seite die aktive Familie, den Stil oder die Größe gewechselt, und eine Schrift bleibt bis zum nächsten Aufruf von setFont() aktiv.

Die Schleifen wandeln die Größe mit (float) um, weil setFont() eine Dezimalzahl erwartet. Die Zeilenhöhen skalieren mit der Schriftgröße ($size * 0.8), sodass größerer Text höhere Zeilen erhält und nichts überlappt. Versuchen Sie, 'times' durch 'courier' zu ersetzen, und führen Sie das Skript erneut aus, um die dritte Familie zu sehen.

Falls etwas schiefgegangen ist

• Ein Fehler „class not found” oder ein Autoload-Fehler bedeutet in der Regel, dass das Skript vendor/autoload.php nicht gefunden hat. Führen Sie es innerhalb des Projektordners aus, der vendor/ enthält.
• Ein falsch geschriebener Familienname löst eine Ausnahme aus, die die nicht gefundene Schrift benennt. Überprüfen Sie die Schreibweise: helvetica, times, courier.
• Das Fehlerbehebungs-Hub sammelt gängige Lösungen, und Schriften und Tagging behandelt Schriftprobleme ausführlich.
• Jede Ausnahme der Engine ist in der Fehlerreferenz dokumentiert, mit dem Kontext, den sie mitführt, und der Wiederherstellungsmaßnahme.

Weiter

Sie können nun Seiten gestalten, Text formatieren und gezielt Schriften auswählen. Im nächsten Tutorial platzieren Sie Bilder auf der Seite und organisieren Inhalte mit Tabellen und Listen.