Signatur
Beschreibung
imagecreatefromgd2part liest eine GD2-Datei (oder eine über eine URL erreichbare GD2-Ressource) und extrahiert daraus einen rechteckigen Teilbereich, der durch Startkoordinaten sowie Breite und Höhe definiert wird. Das Ergebnis ist ein neues GdImage-Objekt, das nur den angegebenen Ausschnitt enthält.
Die Funktion ist besonders nützlich, wenn nur ein kleiner Bereich einer großen GD2-Datei benötigt wird, da nicht das gesamte Bild in den Speicher geladen werden muss. Typische Anwendungsfälle sind Sprite-Sheets, bei denen einzelne Sprites aus einem großen GD2-Archiv extrahiert werden.
GD2 ist ein proprietäres, unkomprimiertes Binärformat der GD-Bibliothek und eignet sich wegen der schnellen Lesbarkeit gut für serverseitige Zwischenspeicherung, jedoch nicht für die direkte Auslieferung an Webbrowser. Für die Ausgabe sollte das Bild anschließend in ein Webformat wie PNG oder JPEG konvertiert werden.
Ab PHP 8.0 gibt die Funktion bei Erfolg ein GdImage-Objekt zurück; in älteren PHP-Versionen wurde eine GD-Ressource zurückgegeben. Bei einem Fehler wird false zurückgegeben.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $filename Pflicht | string | Pfad zur GD2-Datei oder URL (sofern allow_url_fopen in der php.ini aktiviert ist). Der Pfad kann relativ oder absolut sein. |
|
| $srcX Pflicht | int | X-Koordinate (Pixel) der linken oberen Ecke des zu extrahierenden Ausschnitts innerhalb der Quelldatei. | |
| $srcY Pflicht | int | Y-Koordinate (Pixel) der linken oberen Ecke des zu extrahierenden Ausschnitts innerhalb der Quelldatei. | |
| $width Pflicht | int | Breite des Ausschnitts in Pixeln. | |
| $height Pflicht | int | Höhe des Ausschnitts in Pixeln. |
Rückgabewert
GdImage-Objekt zurück, das den angegebenen Bildausschnitt enthält. Bei einem Fehler (z. B. Datei nicht gefunden, ungültiges GD2-Format oder ungültige Koordinaten) wird false zurückgegeben.Beispiele
Sprite aus einem GD2-Sprite-Sheet extrahieren und als PNG ausgeben
<?php
// GD2-Sprite-Sheet liegt auf dem Server
$spriteSheet = '/var/cache/sprites/sheet.gd2';
// Sprite bei Position (64, 0), 32x32 Pixel
$sprite = imagecreatefromgd2part($spriteSheet, 64, 0, 32, 32);
if ($sprite === false) {
http_response_code(500);
die('Fehler beim Laden des Sprites.');
}
// Als PNG an den Browser senden
header('Content-Type: image/png');
imagepng($sprite);
imagedestroy($sprite);Ausschnitt laden, skalieren und als JPEG speichern
<?php
$source = '/var/cache/images/grosse_karte.gd2';
// Bereich (100, 200) mit 400x300 Pixeln extrahieren
$ausschnitt = imagecreatefromgd2part($source, 100, 200, 400, 300);
if ($ausschnitt === false) {
die('GD2-Datei konnte nicht gelesen werden.');
}
// Auf 200x150 Pixel skalieren
$ziel = imagecreatetruecolor(200, 150);
imagecopyresampled($ziel, $ausschnitt, 0, 0, 0, 0, 200, 150, 400, 300);
// Als JPEG speichern
imagejpeg($ziel, '/var/www/html/ausschnitt.jpg', 85);
imagedestroy($ausschnitt);
imagedestroy($ziel);
echo 'Ausschnitt gespeichert.';// Wichtig · Fallstricke
Sicherheitshinweis: Wird $filename aus Benutzereingaben übernommen, muss der Wert sorgfältig validiert und bereinigt werden, um Path-Traversal-Angriffe (../) sowie das Laden beliebiger Dateien vom Server oder aus dem Netz zu verhindern. Verwende Whitelists oder realpath() zur Prüfung.
URL-Unterstützung: Das Laden über URLs ist nur möglich, wenn allow_url_fopen = On in der php.ini gesetzt ist. In Produktivumgebungen ist diese Einstellung häufig aus Sicherheitsgründen deaktiviert.
GD2-Format: GD2-Dateien sind nicht für die direkte Browseranzeige geeignet. Das Format ist auf schnelle serverseitige Verarbeitung ausgelegt. Für die Auslieferung an Clients immer ein Webformat (PNG, JPEG, WebP) verwenden.
Koordinaten außerhalb des Bildes: Liegen die angegebenen Koordinaten oder Dimensionen außerhalb des tatsächlichen Bildbereichs, kann das Ergebnis leer oder fehlerhaft sein. Es empfiehlt sich, die Bildmaße vorab mit getimagesize() zu prüfen.