SensitiveParameterValue — Klasse · PHP-Referenz

Signatur

final class SensitiveParameterValue

Beschreibung

SensitiveParameterValue ist eine eingebaute PHP-Klasse, die zusammen mit dem Attribut #[\SensitiveParameter] verwendet wird. Wenn ein Funktions- oder Methodenparameter mit #[\SensitiveParameter] markiert ist, ersetzt PHP den übergebenen Wert bei der Erstellung von Stack-Traces automatisch durch eine Instanz von SensitiveParameterValue. Dadurch werden Passwörter, API-Schlüssel, Tokens und andere vertrauliche Daten nicht in Fehlerprotokollen oder Exception-Stack-Traces sichtbar.

Die Klasse besitzt einen einzigen Konstruktor-Parameter und eine Methode getValue(), mit der der ursprüngliche, unverschleierte Wert bei Bedarf programmatisch abgerufen werden kann. Direkt instanziiert werden kann sie ebenfalls, was nützlich ist, um eigene Logging- oder Fehlerbehandlungsschichten zu bauen, die sensible Werte kapseln sollen.

Typische Einsatzgebiete sind Authentifizierungsfunktionen (Passwörter, Tokens), Kryptografie-Funktionen (Schlüssel, IVs) sowie jede API, die Credentials entgegennimmt. Da PHP den Wert im Fehlerfall automatisch schützt, entfällt aufwändiges manuelles Maskieren in set_exception_handler()- oder error_handler()-Callbacks.

Wichtig: SensitiveParameterValue ist als final deklariert und kann nicht erweitert werden. Die Klasse implementiert keine Interfaces und hat keine öffentlichen Eigenschaften.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	mixed		Der zu kapselnde sensible Wert beliebigen Typs (z. B. ein Passwort-String, ein Array mit Credentials oder ein Objekt). Der Wert wird intern gespeichert und kann über `getValue()` wieder abgerufen werden.

Rückgabewert

Typ

Beispiele

Automatischer Schutz durch #[SensitiveParameter]

<?php

function login(string $user, #[\SensitiveParameter] string $password): void
{
    // Simuliere einen Fehler innerhalb der Funktion
    throw new \RuntimeException('Login fehlgeschlagen');
}

try {
    login('alice', 'geheimesPasswort123');
} catch (\RuntimeException $e) {
    // Stack-Trace ausgeben — das Passwort erscheint NICHT im Klartext
    echo $e->getMessage() . PHP_EOL;

    // Detaillierte Trace-Informationen
    $trace = $e->getTrace();
    $arg = $trace[0]['args'][1]; // zweites Argument von login()

    var_dump($arg); // Gibt object(SensitiveParameterValue) aus, nicht den Klartext
}

Login fehlgeschlagen object(SensitiveParameterValue)#1 (0) { }

Manuelles Instanziieren und getValue()

<?php

// Sensiblen Wert manuell kapseln
$apiKey = 'sk-prod-abc123XYZ';
$safe   = new \SensitiveParameterValue($apiKey);

// Im Log nur das Objekt ausgeben (kein Klartext)
error_log('API-Anfrage gestartet, Key: ' . get_class($safe));

// Wenn der Wert tatsächlich benötigt wird:
$originalKey = $safe->getValue();
echo 'Länge des Keys: ' . strlen($originalKey) . PHP_EOL;

// Sicherheitsprüfung: var_dump zeigt keinen Wert
var_dump($safe);

Länge des Keys: 18 object(SensitiveParameterValue)#1 (0) { }

Schutz eines komplexen Wertes (Array mit Credentials)

<?php

function connectToDatabase(
    string $host,
    string $dbname,
    #[\SensitiveParameter] array $credentials
): void {
    // Verbindungsversuch schlägt fehl
    throw new \PDOException('Verbindung verweigert: ' . $host);
}

try {
    connectToDatabase('db.example.com', 'shop', [
        'user'     => 'dbuser',
        'password' => 'superGeheim!',
    ]);
} catch (\PDOException $e) {
    $trace = $e->getTrace();
    // $credentials-Argument ist als SensitiveParameterValue gekapselt
    $arg   = $trace[0]['args'][2];
    echo get_class($arg) . PHP_EOL; // SensitiveParameterValue

    // Originalwert ist bei Bedarf abrufbar
    $creds = $arg->getValue();
    echo $creds['user'] . PHP_EOL; // dbuser
}

SensitiveParameterValue dbuser

// Wichtig · Fallstricke

Sicherheitshinweis: SensitiveParameterValue schützt Werte ausschließlich in automatisch erzeugten PHP-Stack-Traces (z. B. in Exception::getTrace() und Exception::getTraceAsString()). Wenn sensible Daten manuell geloggt oder in eigenen Fehlermeldungen ausgegeben werden, muss der Entwickler selbst für deren Schutz sorgen.

Kein vollständiger Schutz: getValue() gibt den Originalwert zurück. Wer Zugriff auf die SensitiveParameterValue-Instanz hat, kann den Wert auslesen. Die Klasse schützt primär vor unbeabsichtigter Offenlegung, nicht vor gezieltem Zugriff.

Kompatibilität: Das Attribut #[\SensitiveParameter] und die Klasse SensitiveParameterValue sind seit PHP 8.2.0 verfügbar. In älteren PHP-Versionen wird das Attribut ignoriert, was jedoch bedeutet, dass der Wert im Stack-Trace im Klartext erscheint — achte daher auf die Mindest-PHP-Version in deinem Projekt.

Siehe auch

#[SensitiveParameter] Exception::getTrace Exception::getTraceAsString set_exception_handler