imagechar — Funktion · PHP-Referenz

Signatur

imagechar(GdImage $image, GdFont|int $font, int $x, int $y, string $char, int $color): bool

Beschreibung

imagechar() rendert das erste Zeichen des übergebenen Strings $char an der Position ($x, $y) in das Bild $image. Das Zeichen wird horizontal gezeichnet, also von links nach rechts.

Für den Parameter $font können die integrierten Bitmap-Fonts 1–5 verwendet werden (je größer die Zahl, desto größer die Schrift), oder eine mit imageloadfont() geladene benutzerdefinierte Schriftart. Ab PHP 8.1 wird der Rückgabewert von imageloadfont() als GdFont-Objekt übergeben.

Die Funktion ist besonders nützlich, wenn man schnell einzelne Zeichen oder einfache Text-Labels ohne externe TrueType-Schriften in ein Bild einzeichnen möchte. Für ganze Zeichenketten steht imagestring() zur Verfügung; für TTF-Schriften empfiehlt sich imagettftext().

Die Koordinaten ($x, $y) geben die linke obere Ecke des zu zeichnenden Zeichens an und sind in Pixeln angegeben.

Parameter

Name	Typ	Beschreibung
$image Pflicht	GdImage	Ein GD-Bild-Objekt, das zuvor mit Funktionen wie `imagecreatetruecolor()` oder `imagecreatefromjpeg()` erzeugt wurde.
$font Pflicht	GdFont\|int	Eingebauter Font als Ganzzahl von 1 (kleinste) bis 5 (größte Bitmap-Schrift), oder ein `GdFont`-Objekt, das von `imageloadfont()` zurückgegeben wurde.
$x Pflicht	int	Die horizontale Position (in Pixeln) der linken oberen Ecke des Zeichens.
$y Pflicht	int	Die vertikale Position (in Pixeln) der linken oberen Ecke des Zeichens.
$char Pflicht	string	Das zu zeichnende Zeichen. Nur das erste Zeichen des Strings wird gezeichnet.
$color Pflicht	int	Die Farbe des Zeichens als Farbindex, der mit `imagecolorallocate()` oder `imagecolorallocatealpha()` erzeugt wurde.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler.

Beispiele

Einzelnes Zeichen mit eingebautem Font zeichnen

<?php
// Bild erstellen
$image = imagecreatetruecolor(100, 50);

// Farben definieren
$hintergrund = imagecolorallocate($image, 255, 255, 255);
$schriftfarbe = imagecolorallocate($image, 0, 0, 0);

// Hintergrund füllen
imagefill($image, 0, 0, $hintergrund);

// Zeichen 'A' mit Font 5 an Position (10, 10) zeichnen
imagechar($image, 5, 10, 10, 'A', $schriftfarbe);

// PNG ausgeben
header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);

Mehrere Zeichen manuell als einfache Textzeile platzieren

<?php
// Bild erstellen
$image = imagecreatetruecolor(200, 40);

$hintergrund = imagecolorallocate($image, 240, 240, 240);
$rot         = imagecolorallocate($image, 200, 0, 0);
$blau        = imagecolorallocate($image, 0, 0, 200);

imagefill($image, 0, 0, $hintergrund);

$text = 'PHP';
$zeichenBreite = imagefontwidth(4); // Breite pro Zeichen

foreach (str_split($text) as $i => $zeichen) {
    // Abwechselnd rot und blau
    $farbe = ($i % 2 === 0) ? $rot : $blau;
    imagechar($image, 4, 10 + $i * $zeichenBreite, 10, $zeichen, $farbe);
}

header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);

// Wichtig · Fallstricke

Nur das erste Zeichen: Wenn $char mehr als ein Zeichen enthält, werden alle weiteren ignoriert. Für ganze Zeichenketten sollte stattdessen imagestring() verwendet werden.

Zeichensatz-Einschränkung: Die eingebauten Fonts unterstützen nur den Latin-1-Zeichensatz (ISO-8859-1). Für Unicode- oder UTF-8-Text ist imagettftext() mit einer passenden TrueType-Schriftart die richtige Wahl.

Ab PHP 8.0: Der Parameter $image erwartet ein GdImage-Objekt statt einer Ressource. Älterer Code, der resource-Werte verwendet, muss entsprechend angepasst werden.

Siehe auch

imagecharup imagestring imagestringup imagettftext imageloadfont imagefontwidth imagecolorallocate