ps_add_pdflink — Funktion · PHP-Referenz

Signatur

ps_add_pdflink(resource $psdoc, float $llx, float $lly, float $urx, float $ury, string $filename, int $page, string $dest): bool

Beschreibung

ps_add_pdflink() gehört zur ps-Erweiterung (pslib) und ermöglicht es, innerhalb eines PostScript-Dokuments einen Hyperlink-Bereich zu definieren, der beim Konvertieren nach PDF auf eine bestimmte Seite eines anderen PDF-Dokuments verweist. Der Link wird durch ein rechteckiges Klickgebiet definiert, das durch die Koordinaten der linken unteren (lower left) und rechten oberen (upper right) Ecke angegeben wird.

Die Koordinaten beziehen sich auf das aktuelle PostScript-Koordinatensystem (Punkte, Ursprung unten links). Der Parameter filename gibt den Pfad zur Ziel-PDF-Datei an, page die Zielseitennummer und dest die Art der Darstellung der Zielseite (z. B. fitpage, fitwidth, fitheight, fitbbox).

Diese Funktion ist besonders nützlich, wenn mehrteilige Dokumentsammlungen erstellt werden, die miteinander verknüpft sein sollen, etwa Inhaltsverzeichnisse, die auf Kapitel in separaten PDF-Dateien verweisen.

Hinweis: Die ps-Erweiterung setzt eine installierte pslib-Bibliothek voraus und ist in modernen PHP-Umgebungen selten vorinstalliert.

Parameter

Name	Typ	Beschreibung
$psdoc Pflicht	resource	Eine gültige PostScript-Dokumentressource, die zuvor mit `ps_new()` erzeugt und mit `ps_open_file()` geöffnet wurde.
$llx Pflicht	float	Die x-Koordinate der linken unteren Ecke des Linkbereichs in Punkten.
$lly Pflicht	float	Die y-Koordinate der linken unteren Ecke des Linkbereichs in Punkten.
$urx Pflicht	float	Die x-Koordinate der rechten oberen Ecke des Linkbereichs in Punkten.
$ury Pflicht	float	Die y-Koordinate der rechten oberen Ecke des Linkbereichs in Punkten.
$filename Pflicht	string	Pfad zur Ziel-PDF-Datei, auf die der Link verweisen soll.
$page Pflicht	int	Die Seitennummer im Ziel-PDF-Dokument, zu der der Link führen soll (beginnend bei `1`).
$dest Pflicht	string	Die Darstellungsart der Zielseite. Mögliche Werte sind `fitpage`, `fitwidth`, `fitheight` oder `fitbbox`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Ressource oder fehlerhafte Parameter).

Beispiele

Einfacher PDF-Link auf Seite 3 eines externen Dokuments

<?php
$ps = ps_new();

if (!ps_open_file($ps, 'output.ps')) {
    die('Konnte PostScript-Datei nicht öffnen.');
}

ps_set_info($ps, 'Creator', 'Beispielskript');
ps_set_info($ps, 'Title', 'PDF-Link Beispiel');

ps_begin_page($ps, 596, 842); // DIN A4

// Link-Bereich definieren: Rectangle von (100,700) bis (300,730)
// Verweist auf Seite 3 der Datei 'kapitel2.pdf'
ps_add_pdflink($ps, 100.0, 700.0, 300.0, 730.0, 'kapitel2.pdf', 3, 'fitpage');

// Optionaler Linktext (visuell)
ps_set_font($ps, 'Helvetica', 1, 12);
ps_show_xy($ps, 'Zu Kapitel 2, Seite 3', 100, 705);

ps_end_page($ps);
ps_close($ps);
ps_delete($ps);

echo 'PostScript-Datei mit PDF-Link wurde erstellt.';
?>

PostScript-Datei mit PDF-Link wurde erstellt.

Mehrere PDF-Links auf einer Seite (Inhaltsverzeichnis)

<?php
$ps = ps_new();
ps_open_file($ps, 'inhaltsverzeichnis.ps');
ps_set_info($ps, 'Title', 'Inhaltsverzeichnis');

ps_begin_page($ps, 596, 842);

$links = [
    ['label' => 'Einleitung',   'file' => 'kapitel1.pdf', 'page' => 1, 'y' => 750],
    ['label' => 'Grundlagen',   'file' => 'kapitel2.pdf', 'page' => 1, 'y' => 720],
    ['label' => 'Fortgeschritten', 'file' => 'kapitel3.pdf', 'page' => 1, 'y' => 690],
];

ps_set_font($ps, 'Helvetica', 1, 12);

foreach ($links as $link) {
    // Rechteckiger Klickbereich für jeden Eintrag
    ps_add_pdflink($ps, 80.0, $link['y'] - 5, 400.0, $link['y'] + 15, $link['file'], $link['page'], 'fitwidth');
    ps_show_xy($ps, $link['label'], 80, $link['y']);
}

ps_end_page($ps);
ps_close($ps);
ps_delete($ps);

echo 'Inhaltsverzeichnis mit PDF-Links erstellt.';
?>

Inhaltsverzeichnis mit PDF-Links erstellt.

// Wichtig · Fallstricke

Verfügbarkeit: Die ps-Erweiterung ist nicht standardmäßig in PHP enthalten und muss separat kompiliert bzw. installiert werden. Sie setzt die externe Bibliothek pslib voraus. In modernen PHP-Versionen (ab PHP 8) ist die Unterstützung eingeschränkt und die Erweiterung gilt als selten gewartet.

Die Links werden erst beim Konvertieren des PostScript-Dokuments in PDF (z. B. mit ps2pdf oder Ghostscript) aktiv — ein reines PostScript-Dokument unterstützt keine interaktiven Hyperlinks.

Der Parameter dest muss exakt einem der erlaubten Werte entsprechen (fitpage, fitwidth, fitheight, fitbbox); ein ungültiger Wert kann zu fehlerhaftem Verhalten führen.

Siehe auch

ps_add_weblink ps_add_locallink ps_add_launchlink ps_begin_page ps_new