README

solitus0/payload-path-sanitizer is a minimal PHP 8.1+ library for redacting or masking values deep inside associative payloads before they leave your system (logging, telemetry, queues, etc.). Define rules that pair a matcher (decides where) with a value sanitizer (decides how), then run the sanitizer to get a safe copy of the original payload.

Installation

composer require solitus0/payload-path-sanitizer

Core Concepts

Rule – pairs a Matcher and a ValueSanitizer.
SanitizerContext – convenient builder/iterator for rules (you can also pass any iterable<Rule>).
Sanitizer – walks the payload depth-first and replaces leaf values whenever a rule's matcher returns true.

Quick Start

use Solitus0\PayloadSanitizer\{Rule, SanitizerContext, Sanitizer};
use Solitus0\PayloadSanitizer\Matcher\KeyMatcher;
use Solitus0\PayloadSanitizer\ValueSanitizer\SimpleValueSanitizer;

$context = new SanitizerContext(
    new Rule(new KeyMatcher('password'), new SimpleValueSanitizer()),
);

$sanitized = (new Sanitizer())->sanitize($payload, $context);

SimpleValueSanitizer replaces the value with a SANITIZED (...) marker, but you will usually create your own value sanitizer (see below).

Custom Matchers

Implement Solitus0\PayloadSanitizer\Matcher\SanitizerMatcherInterface and inspect the current leaf:

final class EndsWithIdMatcher implements SanitizerMatcherInterface
{
    public function matches($key, array $path, $value = null): bool
    {
        return str_ends_with((string) $key, '_id');
    }
}

Available built-ins:

KeyMatcher – matches an exact key.
ParentKeyMatcher – matches by parent key (useful for targeting nested structures).
PathContainsMatcher – ensures the traversal path contains a set of keys (order agnostic).

Combine matchers by writing your own composite if needed.

Custom Value Sanitizers

Implement Solitus0\PayloadSanitizer\ValueSanitizer\ValueSanitizerInterface and transform the matched value into whatever should be persisted/logged. Typical strategies include fixed strings, hashes, or length-prefixed tokens.

final class FixedMaskSanitizer implements ValueSanitizerInterface
{
    public function sanitize($value): string
    {
        return '***';
    }
}

Advanced Usage

Dynamic rule sets – since Sanitizer::sanitize accepts any iterable<Rule>, you can yield rules lazily or build them per request.
Immutable pipelines – rules are evaluated in the order provided; the first matching rule wins for each payload leaf, ensuring deterministic behavior.
Binary-safe – matchers receive the raw value, so you can restrict sanitation to certain types before falling back to generic fallbacks.

Testing Tips

Assert on the sanitized payload rather than internal behavior.
Provide representative payload fixtures (arrays with strings, ints, and nested arrays) to ensure matchers behave as expected.

License

MIT

solitus0 / payload-path-sanitizer

Maintainers

Details