imagefilter — Funktion · PHP-Referenz

Signatur

imagefilter(GdImage $image, int $filter, int|float $arg1 = 0, int $arg2 = 0, int $arg3 = 0, int $arg4 = 0): bool

Beschreibung

imagefilter() ermöglicht es, verschiedene visuelle Effekte direkt auf ein GD-Bild anzuwenden, ohne externe Bibliotheken zu benötigen. Die Funktion gehört zur GD-Erweiterung und unterstützt Filter wie Graustufen (IMG_FILTER_GRAYSCALE), Helligkeit (IMG_FILTER_BRIGHTNESS), Kontrast (IMG_FILTER_CONTRAST), Kantenerkennung (IMG_FILTER_EDGEDETECT), Prägung (IMG_FILTER_EMBOSS), Gaußscher Weichzeichner (IMG_FILTER_GAUSSIAN_BLUR), selektive Färbung (IMG_FILTER_COLORIZE) und mehr.

Je nach gewähltem Filter werden zusätzliche Argumente benötigt: IMG_FILTER_BRIGHTNESS und IMG_FILTER_CONTRAST erwarten einen Ganzzahl-Wert als erstes Argument, IMG_FILTER_COLORIZE benötigt vier Argumente (Rot, Grün, Blau, Alpha), und IMG_FILTER_PIXELATE erwartet Blockgröße und einen booleschen Modus-Parameter.

Typische Einsatzgebiete sind die dynamische Bildbearbeitung auf dem Server, etwa das automatische Erzeugen von Graustufen-Thumbnails, das Weichzeichnen von Vorschaubildern oder das Hervorheben von Kanten für grafische Effekte. Die Funktion verändert das Bild direkt (in-place).

IMG_FILTER_NEGATE – Farben invertieren (keine weiteren Argumente)
IMG_FILTER_GRAYSCALE – Graustufen (keine weiteren Argumente)
IMG_FILTER_BRIGHTNESS – Helligkeit (-255 bis 255)
IMG_FILTER_CONTRAST – Kontrast (-100 bis 100)
IMG_FILTER_COLORIZE – Einfärbung (R, G, B, Alpha 0–127)
IMG_FILTER_EDGEDETECT – Kantenerkennung
IMG_FILTER_EMBOSS – Prägungseffekt
IMG_FILTER_GAUSSIAN_BLUR – Gaußscher Weichzeichner
IMG_FILTER_SELECTIVE_BLUR – Selektiver Weichzeichner
IMG_FILTER_MEAN_REMOVAL – Skeletteffekt (Mean Removal)
IMG_FILTER_SMOOTH – Glätten (Stärke als float)
IMG_FILTER_PIXELATE – Verpixelung (Blockgröße, Modus)
IMG_FILTER_SCATTER – Streueffekt (ab PHP 7.4)

Parameter

Name	Typ	Default	Beschreibung
$image Pflicht	GdImage		Ein GD-Bildobjekt, wie es von Funktionen wie `imagecreatefromjpeg()`, `imagecreatefrompng()` oder `imagecreatetruecolor()` zurückgegeben wird.
$filter Pflicht	int		Eine der vordefinierten `IMG_FILTER_*`-Konstanten, die den anzuwendenden Filter bestimmt (z. B. `IMG_FILTER_GRAYSCALE`, `IMG_FILTER_BRIGHTNESS`).
$arg1	int\|float	0	Erstes optionales Argument für Filter, die einen Parameter benötigen. Bei `IMG_FILTER_BRIGHTNESS`: Helligkeitswert von -255 bis 255. Bei `IMG_FILTER_CONTRAST`: Kontrastwert von -100 bis 100. Bei `IMG_FILTER_COLORIZE`: Rotanteil (0–255). Bei `IMG_FILTER_SMOOTH`: Glättungsstärke (float). Bei `IMG_FILTER_PIXELATE`: Blockgröße in Pixeln.
$arg2	int	0	Zweites optionales Argument. Bei `IMG_FILTER_COLORIZE`: Grünanteil (0–255). Bei `IMG_FILTER_PIXELATE`: Modus (0 = einfach, 1 = fortgeschritten).
$arg3	int	0	Drittes optionales Argument. Bei `IMG_FILTER_COLORIZE`: Blauanteil (0–255).
$arg4	int	0	Viertes optionales Argument. Bei `IMG_FILTER_COLORIZE`: Alpha-Wert von 0 (vollständig opak) bis 127 (vollständig transparent).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Filterkonstante oder ungültiges Bildobjekt).

Beispiele

Bild in Graustufen umwandeln und als PNG ausgeben

<?php
// Originalbild laden
$image = imagecreatefromjpeg('foto.jpg');

if ($image === false) {
    die('Bild konnte nicht geladen werden.');
}

// Graustufen-Filter anwenden
if (imagefilter($image, IMG_FILTER_GRAYSCALE)) {
    // Als PNG an den Browser senden
    header('Content-Type: image/png');
    imagepng($image);
} else {
    echo 'Filter konnte nicht angewendet werden.';
}

imagedestroy($image);

(PNG-Bild in Graustufen wird ausgegeben)

Helligkeit erhöhen und Bild blau einfärben

<?php
$image = imagecreatefrompng('bild.png');

if ($image === false) {
    die('Bild konnte nicht geladen werden.');
}

// Helligkeit um 50 erhöhen
imagefilter($image, IMG_FILTER_BRIGHTNESS, 50);

// Blauen Farbton hinzufügen (R=0, G=0, B=80, Alpha=0)
imagefilter($image, IMG_FILTER_COLORIZE, 0, 0, 80, 0);

// Gaußschen Weichzeichner einmal anwenden
imagefilter($image, IMG_FILTER_GAUSSIAN_BLUR);

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

(Aufgehelltes, bläulich eingefärbtes und leicht unscharf gerendertes PNG-Bild)

Bild verpixeln (Datenschutz-Effekt)

<?php
$image = imagecreatefromjpeg('gesicht.jpg');

if ($image === false) {
    die('Bild konnte nicht geladen werden.');
}

// Blockgröße 15 Pixel, fortgeschrittener Modus
imagefilter($image, IMG_FILTER_PIXELATE, 15, IMG_FILTER_PIXELATE);

header('Content-Type: image/jpeg');
imagejpeg($image, null, 90);
imagedestroy($image);

(Verpixeltes JPEG-Bild zur Anonymisierung)

// Wichtig · Fallstricke

GD-Erweiterung erforderlich: imagefilter() setzt die PHP-GD-Erweiterung voraus. Prüfen Sie deren Verfügbarkeit mit extension_loaded('gd') oder phpinfo().

Mehrfache Anwendung: Filter können mehrfach hintereinander auf dasselbe Bild angewendet werden. Beispielsweise können Sie IMG_FILTER_GAUSSIAN_BLUR mehrmals aufrufen, um einen stärkeren Weichzeichner-Effekt zu erzielen.

Truecolor vs. Palette: Einige Filter (insbesondere IMG_FILTER_COLORIZE) funktionieren ausschließlich mit Truecolor-Bildern. Palette-basierte Bilder sollten vorab mit imagepalettetotruecolor() konvertiert werden.

Performance: Bei großen Bildern oder häufig aufgerufenen Skripten kann die wiederholte Anwendung rechenintensiver Filter (z. B. IMG_FILTER_GAUSSIAN_BLUR) zu hoher CPU-Auslastung führen. Ergebnisse sollten gecacht werden.

Siehe auch

imagecreatetruecolor imagecreatefromjpeg imagecreatefrompng imagepalettetotruecolor imageconvolution imagecopyresampled