SensitiveParameter — Klasse · PHP-Referenz

Signatur

#[SensitiveParameter]

Beschreibung

Das PHP-Attribut #[SensitiveParameter] wird auf Funktions- und Methoden-Parameter angewendet, um sicherzustellen, dass deren Werte in Ausnahme-Stack-Traces (Throwable::getTrace(), Throwable::getTraceAsString()) sowie in PHP-Fehlerausgaben nicht im Klartext erscheinen. Stattdessen wird der Wert durch ein SensitiveParameterValue-Objekt ersetzt, das die eigentlichen Daten verbirgt.

Das Attribut ist besonders wichtig für Parameter, die Passwörter, API-Schlüssel, Tokens, Kreditkartendaten oder andere vertrauliche Informationen enthalten. Ohne diese Markierung könnten sensible Daten versehentlich in Log-Dateien, Fehlerseiten oder Monitoring-Systemen landen – ein erhebliches Sicherheitsrisiko.

Es ist zu beachten, dass #[SensitiveParameter] ausschließlich die Sichtbarkeit in Stack-Traces beeinflusst. Die Funktion oder Methode selbst erhält den Parameterwert wie gewohnt und kann ihn uneingeschränkt verwenden. Das Attribut hat keinerlei Auswirkung auf die Laufzeit-Logik.

Das Attribut kann auf mehrere Parameter derselben Funktion angewendet werden und funktioniert sowohl bei normalen Funktionen, Methoden, Konstruktoren als auch bei Closures und Arrow-Functions.

Parameter

Name	Typ	Default	Beschreibung
$(keine Konstruktor-Parameter)			`#[SensitiveParameter]` besitzt keinen Konstruktor und nimmt keine Argumente entgegen. Es wird einfach vor dem betreffenden Parameter platziert.

Beispiele

Passwort in einer Authentifizierungsfunktion schützen

<?php
function authenticate(
    string $username,
    #[\SensitiveParameter] string $password
): bool {
    // Simulierter Fehlerfall, der einen Stack-Trace erzeugt
    throw new \RuntimeException('Datenbankverbindung fehlgeschlagen.');
}

try {
    authenticate('admin', 'geheim1234');
} catch (\RuntimeException $e) {
    // Stack-Trace: $password erscheint als SensitiveParameterValue-Objekt
    echo $e->getMessage() . PHP_EOL;

    // Trace-Array inspizieren
    $trace = $e->getTrace();
    var_dump($trace[0]['args'][1]);
}

Datenbankverbindung fehlgeschlagen. object(SensitiveParameterValue)#2 (0) { }

Mehrere sensible Parameter in einer Klasse

<?php
class ApiClient
{
    public function __construct(
        private string $baseUrl,
        #[\SensitiveParameter] private string $apiKey,
        #[\SensitiveParameter] private string $apiSecret
    ) {}

    public function request(string $endpoint): void
    {
        // Auslösen eines Fehlers, um den Stack-Trace zu demonstrieren
        throw new \LogicException('Endpunkt nicht erreichbar: ' . $endpoint);
    }
}

try {
    $client = new ApiClient(
        'https://api.example.com',
        'mein-geheimer-api-key',
        'mein-geheimer-api-secret'
    );
    $client->request('/users');
} catch (\LogicException $e) {
    echo $e->getMessage() . PHP_EOL;

    // $apiKey und $apiSecret sind im Trace verborgen
    $trace = $e->getTrace();
    foreach ($trace[0]['args'] as $index => $arg) {
        echo "Argument $index: ";
        echo ($arg instanceof \SensitiveParameterValue)
            ? '[VERBORGEN]'
            : var_export($arg, true);
        echo PHP_EOL;
    }
}

Endpunkt nicht erreichbar: /users Argument 0: 'https://api.example.com' Argument 1: [VERBORGEN] Argument 2: [VERBORGEN]

Verwendung mit einer Closure

<?php
$encrypt = function (
    string $plaintext,
    #[\SensitiveParameter] string $encryptionKey
): string {
    throw new \RuntimeException('Verschlüsselungsfehler aufgetreten.');
};

try {
    $encrypt('Hallo Welt', 's3cr3t-k3y');
} catch (\RuntimeException $e) {
    $trace = $e->getTrace();
    // $encryptionKey erscheint als SensitiveParameterValue
    var_dump($trace[0]['args'][1] instanceof \SensitiveParameterValue);
}

bool(true)

// Wichtig · Fallstricke

Sicherheitshinweis: #[SensitiveParameter] schützt ausschließlich vor der versehentlichen Ausgabe in Stack-Traces. Es verhindert nicht, dass die Werte im Speicher lesbar sind, in eigenen Log-Aufrufen ausgegeben werden oder durch var_dump() / print_r() sichtbar werden. Die eigentliche Datensicherheit (Verschlüsselung, sichere Übertragung) muss separat gewährleistet werden.

SensitiveParameterValue: Die Klasse \SensitiveParameterValue wurde ebenfalls in PHP 8.2 eingeführt und dient als Platzhalter-Objekt im Trace. Sie besitzt eine getValue()-Methode, über die der ursprüngliche Wert programmatisch abgerufen werden kann – was jedoch in der Regel vermieden werden sollte.

Kompatibilität: Das Attribut funktioniert ab PHP 8.2. In älteren PHP-Versionen wird das Attribut nicht erkannt; der Parameter verhält sich wie ein normaler Parameter ohne Verschleierung.

Siehe auch

SensitiveParameterValue Attribute Throwable::getTrace Throwable::getTraceAsString Exception