Download the PHP package yolorouter/llmasking-php without Composer

llmasking-php

🌐 English · 简体中文

A PHP library that masks sensitive data before it reaches an LLM, and restores it afterward — so the model, the network, and the vendor's logs never see the real values.

Phone numbers, national ID numbers/SSNs, bank cards, emails, cloud credentials, private keys, JWTs, and your own custom keywords are detected and replaced with placeholders ([PHONE_1]) before a request leaves your process. When the LLM's reply references that placeholder, llmasking swaps it back — including in streamed (SSE) responses, where a placeholder can be split across chunk boundaries.

Already using a PSR-18 HTTP client (Guzzle, Symfony, ...)? The MaskingClient decorator auto-detects the request format and anonymizes every supported free-text field — your SDK and framework code stay untouched:

Table of contents

• How it works
• Install
• Features
• Supported entity types
• Configuration
• Masking strategies
• Usage
  • Transport decorator
  • Reporting
  • One-shot masking
• Playground
• Error handling
• Limitations
• Quality
• Acknowledgements
• License

How it works

llmasking follows the same two-stage Analyzer/Anonymizer split as microsoft/presidio, compiled into a single PHP call:

1. Recognize — every active Recognizer scans the input and reports Findings: a text span, an entity name, and a confidence score. Recognizers are regex rules (checksum-validated where applicable — Luhn for bank cards, ISO 7064 for Chinese IDs) or an Aho-Corasick multi-pattern matcher for custom keywords.
2. Resolve conflicts — overlapping findings are reduced to a non-overlapping set. SECRET-family findings always win; otherwise the longest match wins, then the highest-scoring one.
3. Apply a strategy — each surviving finding is replaced according to its entity's Strategy: Placeholder by default, Redact for secrets, or whatever you configured.
4. Track, if reversible — a Placeholder replacement is recorded in the Session's mapping table; Redact/MaskMiddle/Hash never touch it. Secrets are therefore structurally unrestorable.

Restoring is the mirror image: Session::restore() scans for placeholder-shaped tokens and looks each up in the mapping table.

Install

PHP 8.1+. Dependencies: PSR-18 / PSR-17 / PSR-7 interfaces and wikimedia/aho-corasick (keyword matching).

Features

• PSR-18 transport decorator: MaskingClient wraps any PSR-18 client, anonymizes known free-text fields in outgoing JSON requests, and restores placeholders in responses — including SSE streams. Supports gzip decompression, integrity-header detection, and failed-body degradation.
• Two-layer detection: Aho-Corasick keyword matching plus region-tagged regex rules (Chinese ID checksum, bank card Luhn, US SSN filtering). WithRegions trims which geographic rule packs load.
• Secret detection: cloud access keys, PEM private keys, JWTs, git tokens, high-entropy passwords — all non-reversible (Redact) by default. Secrets win conflict resolution over any overlapping match.
• Session-scoped restoration: the same entity always maps to the same placeholder within a session; restoration tolerates minor LLM reformatting (missing brackets, zero-padded numbers, full-width brackets).
• Streaming-safe: StreamRestorer withholds just enough of a chunk's tail when a placeholder might be split across a boundary — including mid-byte inside a multi-byte UTF-8 character.
• Structured reporting: anonymize()/restore() return MaskEvent/RestoreEvent arrays; TransportOptions::withMaskReport()/withRestoreReport() deliver them per request/response.
• Fail-closed: any input or state the library can't safely handle throws an exception. Per-session limits guard against memory exhaustion.
• More than LLMs: Engine::mask() does one-shot, non-reversible masking for logs and data export — no Session, no mapping table.

Supported entity types

CLOUDKEY/PRIVATEKEY/JWT/GITTOKEN/SECRET form the SECRET family: they always win conflict resolution, and WithStrategy refuses to assign them a reversible strategy.

Configuration

Engine::new() takes zero or more EngineOptions; all validation happens at construction time.

Masking strategies

Implement the Strategy interface (apply(Finding $f, int $seq): string) for custom strategies — always non-reversible.

Usage

Basic round-trip

Transport decorator

The MaskingClient PSR-18 decorator wraps any HTTP client. It detects application/json POST requests, anonymizes all known free-text fields (messages content, tool descriptions, schema annotations), and restores placeholders in responses — including text/event-stream SSE.

Reporting what was masked and restored

One-shot masking (no restore)

For logs, data export, or anything write-only — no Session, no mapping, safe for concurrent use:

Playground

A local web UI for end-to-end testing against any LLM endpoint — see playground/README.md:

Open the URL in a browser, configure your LLM endpoint, send a message, and watch the anonymize → LLM → restore pipeline side-by-side — for both plain and streamed responses.

Error handling

All errors implement LlmaskingException (which extends \Throwable). Typed subclasses:

Limitations

• Session lives in process memory only — not persisted or shared across processes.
• Session::anonymize() is not safe for concurrent use on the same Session (mutates mapping table). Session::restore() is read-only.
• Transport redirect gap: each sendRequest() creates a fresh Session; a 307/308 redirect with a new Session can't restore placeholders from the first hop.
• Supported transport fields: OpenAI Chat Completions (messages content/refusal/tool arguments, tools/functions descriptions, JSON Schema annotations). SSE streaming (delta content/refusal/arguments). Unknown fields pass through unchanged.

Quality

• 475 tests / 4617 assertions
• PHPStan max level clean
• PSR-12 coding standard
• Multi-round adversarial code review (codex) approved

Acknowledgements

This project is a PHP port of llmasking-go, whose design and rule sets draw on:

• microsoft/presidio — Analyzer/Anonymizer pipeline architecture
• bytedance/godlp — China-region recognition patterns
• gitleaks/gitleaks — Secret detection patterns
• wikimedia/aho-corasick — Keyword matching engine

License

MIT, see LICENSE.