Zuletzt aktualisiert: 11. September

Rotierte Bild-Uploads in PHP mit Jpegtran korrigieren

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Mobilgeräte betten häufig Orientierungsdaten in Fotos ein, wodurch Bilder beim Upload in Webanwendungen rotiert erscheinen. Dieses verbreitete Problem kann Nutzer und Entwickler gleichermaßen frustrieren. Zum Glück kann jpegtran – ein winziges Kommandozeilenprogramm, das libjpeg mitliefert – JPEGs ohne erneutes Encoding rotieren, sodass Sie die Ausrichtung korrigieren, während jedes Pixel unverändert bleibt.

EXIF-Orientierungsdaten verstehen

Fotos, die mit modernen Smartphones aufgenommen werden, enthalten EXIF-Metadaten, die unter vielem anderen festhalten, wie die Kamera gehalten wurde. Betrachtungsprogramme, die dieses Feld berücksichtigen, stellen das Bild aufrecht dar, während Software, die es ignoriert, die rohen Pixel zeigt – weshalb frisch hochgeladene Bilder manchmal seitlich oder auf dem Kopf stehend aussehen.

Das Orientierungs-Tag kann diese relevanten Werte annehmen:

1 – Normal
3 – Drehung um 180 Grad
6 – Drehung um 90 Grad im Uhrzeigersinn
8 – Drehung um 90 Grad gegen den Uhrzeigersinn

Bilder in PHP mit GD oder ImageMagick rotieren

Der klassische PHP-Ansatz besteht darin, das JPEG in GD oder ImageMagick zu laden, es zu rotieren und wieder zu speichern:

<?php
$image   = imagecreatefromjpeg('photo.jpg');
$rotated = imagerotate($image, 90, 0);
imagejpeg($rotated, 'photo-fixed.jpg');

Das funktioniert, doch die Datei wird dekomprimiert und neu komprimiert, was feine Details verwaschen lässt und auf ausgelasteten Servern CPU-Zyklen verbraucht.

jpegtran für verlustfreie Rotation verwenden

jpegtran transformiert quantisierte DCT-Koeffizienten ohne einen weiteren verlustbehafteten Kompressionsdurchgang. Perfekte Rotationen und Spiegelungen hängen von den MCU-Grenzen (Minimum Coded Unit) des Bildes ab. Das Flag -copy all kopiert die Metadaten, die anschließend an das transformierte Bild angepasst werden müssen.

jpegtran in Ihrer PHP-Umgebung installieren

# Debian/Ubuntu
sudo apt-get install libjpeg-progs libimage-exiftool-perl

# RHEL/CentOS (ExifTool may require an additional distribution repository)
sudo yum install libjpeg-turbo-utils perl-Image-ExifTool

# macOS (homebrew)
brew install jpeg exiftool

Prüfen Sie, ob die Binärdatei verfügbar ist:

jpegtran -version
exiftool -ver

Systemvoraussetzungen prüfen

Bevor Sie loslegen, prüfen Sie die EXIF-Erweiterung, jpegtran und ExifTool. ExifTool setzt die Orientierungs-Metadaten zurück, nachdem die Pixel transformiert wurden, und verhindert so eine zweite Drehung in Betrachtungsprogrammen.

<?php
function checkRequirements(): void
{
    if (!extension_loaded('exif')) {
        throw new RuntimeException('The EXIF extension is not enabled.');
    }

    foreach (['jpegtran', 'exiftool'] as $binary) {
        $output = [];
        exec('command -v ' . escapeshellarg($binary), $output, $status);
        if ($status !== 0 || empty($output)) {
            throw new RuntimeException($binary . ' is not installed or not in PATH.');
        }
    }
}

EXIF-Daten mit PHP auslesen

<?php
function getOrientation(string $file): int
{
    if (!is_readable($file)) {
        throw new RuntimeException("File {$file} is not readable.");
    }
    $exif = @exif_read_data($file);
    if ($exif === false) {
        // No EXIF block or unreadable — assume upright
        // You might want to log a warning here if EXIF data was expected
        return 1;
    }

    return (int) ($exif['Orientation'] ?? 1);
}

jpegtran sicher aus PHP aufrufen

<?php
function rotateJpeg(string $src, ?string $dst = null): string
{
    if (!is_readable($src)) {
        throw new RuntimeException("Source file {$src} is not readable.");
    }

    $dst ??= 'rotated_' . basename($src);
    if (file_exists($dst)) {
        throw new RuntimeException('Choose a new destination; existing files are not overwritten.');
    }
    $src = realpath($src);

    $orientation = getOrientation($src);

    // Map EXIF orientation to jpegtran switch
    $map = [
        2 => '-flip horizontal', 3 => '-rotate 180', 4 => '-flip vertical',
        5 => '-transpose', 6 => '-rotate 90', 7 => '-transverse', 8 => '-rotate 270',
    ];
    if (!isset($map[$orientation])) {
        // If orientation is 1 (normal) or any other unhandled value,
        // copy the file as is.
        if (!copy($src, $dst)) {
            throw new RuntimeException("Failed to copy {$src} to {$dst}.");
        }
        return $dst;
    }

    $cmd = sprintf(
        'jpegtran -perfect %s -copy all -outfile %s %s',
        $map[$orientation],
        escapeshellarg($dst),
        escapeshellarg($src)
    );

    exec($cmd, $output, $status);
    clearstatcache(true, $dst);

    if ($status !== 0 || !is_file($dst) || filesize($dst) === 0) {
        if (is_file($dst)) unlink($dst);
        throw new RuntimeException('jpegtran could not perform a perfect lossless transform.');
    }

    // Remove the stale thumbnail and mark the transformed pixels as upright.
    exec('exiftool -overwrite_original -Orientation=1 -n -ThumbnailImage= ' .
        escapeshellarg(realpath($dst)), $metadataOutput, $metadataStatus);
    if ($metadataStatus !== 0) {
        unlink($dst);
        throw new RuntimeException('Could not reset image orientation metadata.');
    }

    return $dst;
}

Mehrere Bilder im Batch verarbeiten

-perfect verweigert Transformationen, die nicht alle Randpixel an den JPEG-Blockgrenzen erhalten können. Behandeln Sie diese Fehlschläge bewusst mit einem separaten Workflow zum erneuten Encoding. Arbeiten Sie in einem privaten Ausgabeverzeichnis und geben Sie niemals die Quelldatei als Ziel an.

Wenn Sie mehrere Bilder verarbeiten möchten, können Sie diese in einer Schleife durchlaufen und die Rotationslogik anwenden. Hier ein einfaches Beispiel:

<?php
function batchRotateImages(array $sourceFiles, string $destinationDir): array
{
    if (!is_dir($destinationDir) || !is_writable($destinationDir)) {
        throw new RuntimeException("Destination directory {$destinationDir} is not writable or does not exist.");
    }

    $processedFiles = [];
    foreach ($sourceFiles as $srcFile) {
        try {
            $baseName = basename($srcFile);
            $dstFile = $destinationDir . DIRECTORY_SEPARATOR . 'rotated_' . $baseName;
            $processedFiles[$srcFile] = rotateJpeg($srcFile, $dstFile);
        } catch (RuntimeException $e) {
            // Log error for this specific file and continue with others
            error_log("Failed to process {$srcFile}: " . $e->getMessage());
            $processedFiles[$srcFile] = false; // Indicate failure
        }
    }
    return $processedFiles;
}

// Example usage:
// $filesToProcess = ['image1.jpg', 'path/to/image2.jpg'];
// $outputDirectory = 'processed_images';
// if (!is_dir($outputDirectory)) {
//     mkdir($outputDirectory, 0755, true);
// }
// $results = batchRotateImages($filesToProcess, $outputDirectory);
// print_r($results);

Stellen Sie sicher, dass das Zielverzeichnis existiert und für Ihr PHP-Skript beschreibbar ist.

Vollständiges funktionierendes Beispiel mit Fehlerbehandlung

<?php

// Ensure these functions are defined or included from where they are declared above.
// function checkRequirements(): void { ... }
// function getOrientation(string $file): int { ... }
// function rotateJpeg(string $src, string $dst = null): string { ... }
// function batchRotateImages(array $sourceFiles, string $destinationDir): array { ... }

try {
    checkRequirements(); // Checks for EXIF extension and jpegtran

    $sourceFile = 'photo.jpg'; // Ensure this file exists for testing
    if (!file_exists($sourceFile)) {
         // Create a dummy file for testing if it doesn't exist
         // In a real scenario, ensure photo.jpg is a valid JPEG with EXIF data.
         if (!touch($sourceFile)) {
            error_log("Warning: Could not create dummy file {$sourceFile}. Ensure the directory is writable.");
         } else {
            error_log("Warning: {$sourceFile} does not exist. A dummy file was touched for the example to run. Rotation may not occur as expected without valid EXIF data.");
         }
    }

    $fixed = rotateJpeg($sourceFile, 'rotated_photo.jpg');
    echo "Saved correctly oriented file to $fixed\n";

    // Example for batch processing (optional, uncomment to test)
    /*
    $filesToProcess = [$sourceFile]; // Add more files as needed
    $outputDirectory = 'processed_batch';
    if (!is_dir($outputDirectory)) {
        if (!mkdir($outputDirectory, 0755, true)) {
            throw new RuntimeException("Could not create directory: {$outputDirectory}");
        }
    }
    echo "\nStarting batch processing...\n";
    $results = batchRotateImages($filesToProcess, $outputDirectory);
    print_r($results);
    echo "Batch processing finished. Check the '{$outputDirectory}' directory.\n";
    */

} catch (Throwable $e) {
    error_log("Error: " . $e->getMessage());
    // It's generally better to let PHP handle the response code
    // or set it based on the context (e.g., web request vs. CLI script)
    // http_response_code(500);
    echo "An error occurred. Check the error log for details.\n";
}

Die drei Funktionen (checkRequirements, getOrientation und rotateJpeg) decken Abhängigkeitsprüfungen, das Parsen der EXIF-Daten, die Befehlsausführung, Metadaten-Aktualisierungen und die Validierung der Ausgabe ab.

Sicherheitsaspekte bei exec

Escapen Sie jedes Argument mit escapeshellarg() – verketten Sie niemals rohe Benutzereingaben. Das ist entscheidend, um Command-Injection-Schwachstellen zu verhindern.
Validieren Sie Abhängigkeiten (command -v jpegtran), bevor Sie sie aufrufen. Stellen Sie sicher, dass jpegtran installiert und im PATH des Systems erreichbar ist.
Prüfen Sie den Erfolg des Befehls über das Exit-Status-Argument, das an exec() übergeben wird, und stellen Sie anschließend sicher, dass die resultierende Datei existiert und eine Größe ungleich null hat.
Beschränken Sie Schreiborte nach Möglichkeit auf Verzeichnisse außerhalb des öffentlichen Web-Roots und sorgen Sie für korrekte Dateiberechtigungen für Lese- und Schreibvorgänge.
Bereinigen Sie Dateipfade: Stellen Sie sicher, dass Eingabepfade und Ausgabeziele validiert und bereinigt werden, um Directory-Traversal-Angriffe oder das Schreiben an unbeabsichtigte Orte zu verhindern.

Grenzfälle und Fehlerszenarien behandeln

Fehlende EXIF-Daten – Die Funktion getOrientation verwendet standardmäßig die Orientierung 1 (normal); in solchen Fällen kopiert rotateJpeg die Datei unverändert.
Nicht lesbare Quelldatei – Die Funktionen getOrientation und rotateJpeg enthalten jetzt Prüfungen mithilfe von is_readable() und werfen Ausnahmen, wenn eine Datei nicht gelesen werden kann.
Fehlschlag des Befehls jpegtran: rotateJpeg prüft den Exit-Status und die Ausgabedatei, entfernt fehlgeschlagene Ausgaben und wirft eine Ausnahme.
Progressive JPEGs: jpegtran akzeptiert progressive Eingaben. Die Einschränkungen für perfekte Transformationen gelten weiterhin, und für eine progressive Ausgabe ist die Option -progressive erforderlich.
Große Bilder: Koeffizientenpuffer verbrauchen weiterhin Arbeitsspeicher. Setzen Sie Ressourcenlimits und halten Sie ausreichend Speicherplatz für die Ausgabe bereit, besonders bei der Verarbeitung gleichzeitiger Aufträge.
Nicht unterstützte Orientierungswerte – Der aktuelle Code kopiert das Bild unverändert, wenn der EXIF-Orientierungswert 1 oder unbekannt ist. Sie können ihn so anpassen, dass er bei nicht unterstützten Werten eine Ausnahme wirft, falls eine strikte Behandlung erforderlich ist.
Berechtigungsfehler – Stellen Sie sicher, dass das PHP-Skript Leserechte für die Quelldateien und Schreibrechte für das Zielverzeichnis hat. Die Prüfungen mit is_readable() helfen dabei, und Fehler bei Dateioperationen (etwa bei copy() oder der Ausgabeumleitung von jpegtran) führen in der Regel zu Ausnahmen oder fehlgeschlagenen Ausgabeprüfungen.
Aufräumen von Dateien: Wenn temporäre Dateien erstellt werden oder Originaldateien nach erfolgreicher Verarbeitung entfernt werden müssen, implementieren Sie einen Aufräummechanismus. Die aktuellen Beispiele erzeugen neue Dateien (z. B. rotated_photo.jpg), sodass je nach Workflow ein explizites Aufräumen der Originale nötig sein kann.

Warum jpegtran sich für die JPEG-Rotation auszeichnet

Verlustfrei: Es transformiert quantisierte Koeffizienten ohne einen weiteren verlustbehafteten Encoding-Durchgang.
Metadatenfreundlich – -copy all bewahrt EXIF-, XMP- und ICC-Profile.
Oft schneller: Es vermeidet ein vollständiges Decodieren und erneutes Encoding im Pixelbereich, doch vergleichen Sie zur Sicherheit Ihre eigene Arbeitslast im Benchmark.
Stabil – Seit Jahrzehnten Teil von libjpeg und auf praktisch jeder Serverplattform verfügbar.

Fazit

Mit einer Handvoll Zeilen lesen Sie die EXIF-Orientierung aus, rufen jpegtran auf und liefern Ihren Nutzern ein aufrechtes Foto – ohne ein einziges Bit an Qualität zu verlieren. Fügen Sie die obigen Funktionen in Ihren Upload-Handler oder Queue-Worker ein, und seitlich liegende Selfies gehören der Vergangenheit an.

Bei Transloadit setzen wir fortschrittliche Techniken zur Bildoptimierung in unserem Robot 🤖 /image/optimize ein, der die Formate JPEG, PNG, GIF, WebP und SVG mit konfigurierbaren Optimierungsprioritäten unterstützt.