Download the PHP package lychee-org/phpstan-sensitive-parameter-values without Composer

PHPStan SensitiveParameter Detector

A PHPStan extension that detects parameters that might contain sensitive information and should be marked with the #[\SensitiveParameter] attribute (added in PHP 8.2+).

About SensitiveParameter

The #[\SensitiveParameter] attribute was introduced in PHP 8.2 to mark sensitive data that should be hidden from stack traces and debugging output. This extension helps you identify parameters that should use this attribute for better security.

Learn more: PHP RFC: Redact parameters in back traces

Requirements

• PHP 8.2 or higher
• PHPStan 2.1.3 or higher (SensitiveParameterPropagationRule relies on getAttributes() reflection support added in 2.1.3)

Installation

Usage

The extension will be automatically registered if you use PHPStan's extension installer.

Alternatively, include the extension in your PHPStan configuration:

Typed SensitiveParameterValue

PHP's built-in \SensitiveParameterValue::getValue() is natively typed as mixed, so calling it normally loses type information. This extension ships a PHPStan stub that declares SensitiveParameterValue as generic over the type of the value passed to its constructor, so PHPStan can narrow the return type of getValue() accordingly:

This is most useful when inspecting exception traces, where PHP replaces sensitive arguments with SensitiveParameterValue instances:

Propagating sensitivity through the call graph

Marking a parameter #[\SensitiveParameter] only protects that one call frame. If the value is then forwarded unchanged into a callee whose corresponding parameter is not marked sensitive, protection stops there: an exception thrown from inside the callee will still expose the value in plaintext.

SensitiveParameterPropagationRule flags login()'s $password in this example, with:

This is detected across method calls, static calls, constructors, and plain function calls. Only simple, unmodified pass-through arguments (a bare $variable matching a sensitive parameter of the enclosing function/method) are tracked — values that are transformed, wrapped, or reassigned before being passed on are not.

Cryptographic callees are never flagged

Passing a sensitive value directly into a hashing or encryption function is the intended usage — there is nothing to propagate. The rule ships with a built-in allowlist of well-known cryptographic functions and methods that will never trigger a propagation warning:

The built-in allowlist covers:

• PHP core — password_hash, password_verify, hash, hash_hmac, hash_pbkdf2, hash_equals, crypt, md5, sha1
• OpenSSL — openssl_encrypt, openssl_decrypt, openssl_digest, openssl_sign, openssl_verify
• Sodium — sodium_crypto_pwhash, sodium_crypto_pwhash_str, sodium_crypto_pwhash_str_verify, sodium_crypto_secretbox, sodium_crypto_secretbox_open, sodium_crypto_auth, sodium_crypto_auth_verify, sodium_crypto_box, sodium_crypto_box_open, sodium_crypto_sign, and others
• Laravel — Illuminate\Support\Facades\Hash::make/check/needsRehash and the concrete BcryptHasher, ArgonHasher, Argon2IdHasher variants
• LdapRecord — LdapRecord\Auth\Guard::attempt

See Configuring the cryptographic callee allowlist for how to add your own entries.

Storing sensitive values safely

Marking a parameter sensitive prevents it from leaking through stack traces, but that protection is undone if the raw value is then saved into a property — anything that inspects, dumps, or serializes the object exposes it again. SensitiveParameterStorageRule requires sensitive values to be wrapped in \SensitiveParameterValue before being stored:

Constructor property promotion is also checked, since promotion assigns the raw value directly with no place to wrap it:

A value that's already wrapped is also checked: unwrapping it via ->getValue() right before storing defeats the point of wrapping it in the first place, so it's flagged too:

Only direct, unmodified assignments of a bare $variable (or a bare ->getValue() call on one) into a property are detected; values transformed before being stored are not tracked.

What it detects

The rule detects parameters with names containing common sensitive keywords:

• Authentication: password, secret, token, credential, auth, bearer
• API Security: apikey (matches apisecret, clientsecret via secret)
• Financial: credit, card, ccv, cvv, ssn, pin
• Security: private, signature, hash, salt, nonce, otp, passcode, csrf

Note: Due to substring matching, secret catches apisecret/clientsecret and token catches refreshtoken/accesstoken.

It works with:

• Regular functions
• Class methods (public, private, protected, static)
• Constructors
• Case-insensitive matching (Password, SECRET, etc.)
• Partial matches (userPassword, secretKey, etc.)

Examples

❌ Will trigger warnings:

✅ Properly protected:

Advanced Configuration

Configuring sensitive keywords

To use custom sensitive keywords instead of the defaults, set sensitiveParameter.keywords in your phpstan.neon:

Providing a non-empty list completely replaces the default keyword list.

Configuring the cryptographic callee allowlist

If your project uses a custom hashing or encryption wrapper that should not trigger a propagation warning, add it to sensitiveParameter.cryptoCallees:

Entries are matched as:

• Plain function name for global PHP functions (e.g. my_hash_fn)
• FullyQualifiedClass::method for static calls and instance method calls (e.g. Illuminate\Support\Facades\Hash::make)

Providing a non-empty list completely replaces the built-in allowlist, so include any built-in entries you still want to keep:

Suppressing Warnings

You can suppress warnings using PHPStan's ignore comments:

Constructor Parameters

Due to a PHPStan limitation, ignore comments for constructor parameters must be placed before the constructor:

Note: This ignores ALL parameter warnings for that constructor. For functions with multiple parameters where only some are false positives, consider renaming the problematic parameter to avoid the sensitive keyword match.

Common Issues

False Positives

The rule uses substring matching, which can occasionally trigger false positives:

• $appInstall triggers due to "install" containing "pin"
• $passwordService triggers due to containing "password"
• $signatureMethod triggers due to containing "signature"

For these cases, use ignore comments as shown above or consider renaming parameters to be more specific (e.g., $applicationToInstall, $authService, $verificationMethod).

Reporting Issues

Found a bug or have a feature request? Please report it on GitHub.

When reporting issues, please include:

• PHP version
• PHPStan version
• Code sample that demonstrates the issue
• Expected vs actual behavior

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development setup:

Running tests:

License

MIT License - see LICENSE for details.