sapi_windows_cp_conv — Funktion · PHP-Referenz

Signatur

sapi_windows_cp_conv(int|string $in_codepage, int|string $out_codepage, string $subject): string|false

Beschreibung

sapi_windows_cp_conv() konvertiert einen String aus der angegebenen Quell-Codepage (in_codepage) in die angegebene Ziel-Codepage (out_codepage). Die Funktion ist ausschließlich unter Windows verfügbar und nutzt intern die Windows-API MultiByteToWideChar und WideCharToMultiByte.

Codepages können entweder als Ganzzahl (z. B. 1252 für Windows-1252, 65001 für UTF-8) oder als String-Alias angegeben werden (z. B. "UTF-8", "ACP" für die aktive ANSI-Codepage, "OCP" für die OEM-Codepage). Diese Funktion ist besonders nützlich, wenn Strings zwischen der Konsole (oft OEM-Codepage 850 oder 437) und der internen ANSI-Codepage konvertiert werden müssen.

Typische Einsatzgebiete sind das korrekte Einlesen von Dateinamen, Konsolenausgaben oder externen Prozessergebnissen auf Windows-Systemen, bei denen Sonderzeichen andernfalls korrumpiert würden. In Verbindung mit sapi_windows_cp_get() lässt sich die aktuelle Codepage ermitteln und als Ausgangsbasis verwenden.

Nur verfügbar unter Windows.
Unterstützt String-Aliase wie "ACP", "OEMCP", "UTF-8".
Bei ungültigen Codepages oder Konvertierungsfehlern wird false zurückgegeben.

Parameter

Name	Typ	Beschreibung
$in_codepage Pflicht	int\|string	Die Quell-Codepage des Eingabe-Strings. Kann als Ganzzahl (z. B. `850`, `1252`, `65001`) oder als String-Alias (z. B. `"ACP"`, `"OCP"`, `"UTF-8"`) angegeben werden.
$out_codepage Pflicht	int\|string	Die Ziel-Codepage, in die der String konvertiert werden soll. Gleiche Formatmöglichkeiten wie bei `in_codepage`.
$subject Pflicht	string	Der zu konvertierende Eingabe-String.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den konvertierten String zurück. Bei einem Fehler (z. B. ungültige Codepage oder nicht konvertierbarer Inhalt) wird false zurückgegeben.

Beispiele

Konsolenausgabe von OEM-Codepage nach UTF-8 konvertieren

<?php
// Typisch: Ausgabe eines externen Prozesses (cmd.exe) liegt in OEM-Codepage vor
$output = shell_exec('dir /b C:\\');

if ($output !== null) {
    // OEM-Codepage (z. B. 850 oder 437) nach UTF-8 konvertieren
    $utf8Output = sapi_windows_cp_conv('OCP', 'UTF-8', $output);

    if ($utf8Output !== false) {
        echo $utf8Output;
    } else {
        echo 'Konvertierung fehlgeschlagen.';
    }
}

String von Windows-1252 nach UTF-8 konvertieren

<?php
// Ein String, der in Windows-1252 kodiert vorliegt (z. B. aus einer alten Datei)
$win1252String = "\xDC\xE4\xF6\xFC"; // Ü ä ö ü in Windows-1252

$utf8String = sapi_windows_cp_conv(1252, 65001, $win1252String);

if ($utf8String !== false) {
    echo $utf8String; // Gibt Ü ä ö ü als UTF-8 aus
} else {
    echo 'Konvertierung fehlgeschlagen.';
}

Üäöü

Aktuelle ANSI-Codepage ermitteln und als Basis nutzen

<?php
// Aktuelle ANSI-Codepage ermitteln
$currentCp = sapi_windows_cp_get();
echo "Aktuelle Codepage: $currentCp\n";

// String von aktueller ANSI-Codepage nach UTF-8 konvertieren
$subject = "M\xFCller & S\xF6hne"; // Müller & Söhne in ACP
$utf8 = sapi_windows_cp_conv($currentCp, 65001, $subject);

if ($utf8 !== false) {
    echo $utf8;
}

Aktuelle Codepage: 1252 Müller & Söhne

// Wichtig · Fallstricke

Nur Windows: sapi_windows_cp_conv() ist ausschließlich unter Windows verfügbar. Auf anderen Betriebssystemen sollte mb_convert_encoding() oder iconv() verwendet werden.

Alias-Strings: Neben numerischen Codepage-IDs werden folgende Aliase akzeptiert: "ACP" (aktive ANSI-Codepage), "OEMCP" oder "OCP" (OEM-Codepage). UTF-8 entspricht der Codepage 65001.

Fehlerbehandlung: Wenn ein ungültiger Codepage-Bezeichner übergeben wird oder der String Zeichen enthält, die in der Ziel-Codepage nicht darstellbar sind, gibt die Funktion false zurück. Der Rückgabewert sollte daher stets mit === false geprüft werden.

Siehe auch

sapi_windows_cp_get sapi_windows_cp_set mb_convert_encoding iconv