Download the PHP package padosoft/laravel-pii-redactor without Composer

laravel-pii-redactor

EU-first PII redaction for Laravel — deterministic regex + checksum-validated detectors organised into opt-in country packs (Italy, Germany, Spain ship built-in; France / Netherlands / Portugal land in v1.2+), plus always-on multi-country detectors (email, IBAN mod-97 for every ISO 13616 country, credit card with Luhn) and a pluggable strategy layer (mask / hash / tokenise / drop) with persistent reverse-map storage (memory / database / cache), opt-in HuggingFace + spaCy NER drivers, and YAML custom-rule packs for tenant-specific identifiers. Zero external services in the default path, zero mandatory LLM cost, GDPR + EU AI Act ready.

laravel-pii-redactor is the seventh deliverable of the Padosoft v4.0 cycle (W7). It is a community Apache-2.0 package, standalone-agnostic (zero references to AskMyDocs / sister packages), and ships with the Padosoft AI vibe-coding pack so you can extend it with Claude Code or GitHub Copilot in minutes — not days.

Table of contents

• Why this package
• Design rationale
• Features at a glance
• 🇪🇺 EU country pack architecture
• Build your own country pack — 3-step recipe
• Comparison vs alternatives
• Installation
• Quick start
• Usage examples
• Laravel integration recipes
• Web Panel UI
• Admin panel readiness
• Configuration reference
• Architecture
• AI vibe-coding pack
• Testing — Default + Live
• Performance
• Roadmap
• Migration guide v0.x → v1.0
• Contributing
• Security
• License

Why this package

PII redaction is one of those domains where the existing options force a bad trade-off:

• Build it yourself with a few hand-crafted regexes — fast to write, but the moment a real Italian fiscal code shows up (16 alphanumeric characters with a checksum derived from a Decreto Ministeriale lookup table) your "good enough" regex starts emitting false positives that break audits.
• Reach for Microsoft Presidio / AWS Comprehend / Google DLP — robust, but they assume a US-centric set of identifiers. None of them validate the Italian codice fiscale checksum out of the box, and routing every chat-log line through a hosted PII service is operationally expensive and a GDPR amplifier.
• Bolt an LLM-based redactor onto the pipeline — works, but pays per-token to do something that is, fundamentally, a regular language problem.

laravel-pii-redactor covers the deterministic layer. v1.0 ships:

• 3 always-on multi-country detectors — email (RFC-5321 shape), iban (ISO 13616 country-length table + mod-97 for every registered country, ~75), credit_card (Luhn).
• 3 shipped country packs (v1.1):
  • ItalyPack — codice_fiscale (CIN checksum), partita_iva (Luhn-IT), phone_it, address_it.
  • GermanyPack (v1.1) — steuer_id (mod-11 ISO 7064 per §139b AO), ust_idnr (BMF Method 30 per §27a UStG), phone_de, address_de.
  • SpainPack (v1.1) — dni (23-letter checksum table per RD 1553/2005), nie (prefix-substituted DNI), cif (corporate ID), phone_es, address_es.
• PackContract interface + DetectorPackRegistry — opt-in jurisdiction bundles. Operate in Italy only? Keep ItalyPack. Operate across the EU? Add GermanyPack / SpainPack (shipped v1.1) or FrancePack (v1.2+ candidate). Operate outside Italy? Drop ItalyPack from the config.
• 4 pluggable replacement strategies — mask, hash, tokenise, drop.
• 3 token-store drivers — memory (default), database (Eloquent + shipped migration), cache (Redis / Memcached / DynamoDB / array).
• 2 production NER drivers (opt-in) — HuggingFaceNerDriver, SpaCyNerDriver. Network calls fail open.
• YAML custom-rule packs — register tenant-specific detectors from *.yaml files; SP auto-registers when pii-redactor.custom_rules.auto_register = true.
• Typed DetectionReport — audit every redaction without re-running the engine.
• Admin-ready headless APIs — safe status snapshots, strategy factory, masked report formatter, token resolution, and custom-rule diagnostics for a separate Laravel 13 React/Tailwind admin package. See Admin panel readiness.

It is deliberately small and deliberately offline by default. You can extend it with custom detectors via Pii::extend() or your own country pack. The deterministic engine fits in ~200 lines of PHP, the v1.0 surface is locked under semver, and 300+ unit tests + a robustness suite describe every transition.

Design rationale

Five non-negotiable choices that drove the API:

1. EU-first via opt-in country packs. World-second.

Every PII pipeline I have seen for Laravel either ignores European fiscal data or matches it with a bare regex that returns false positives on every retry CI run. National identifiers need real code: the Italian codice fiscale requires the official odd/even checksum table from the 1976 Decreto Ministeriale; the German Steuer-ID needs mod-11; the Spanish DNI needs a letter-checksum lookup; the French NIR needs mod-97. A regex alone won't do.

Hence country packs. v1.0 shipped ItalyPack as the reference implementation (4 Italian detectors with the full CIN checksum + Luhn-IT). v1.1 makes good on the promise with two more concrete bundles — GermanyPack (Steuer-ID mod-11 ISO 7064 per §139b AO + USt-IdNr BMF Method 30 per §27a UStG + German phone/address) and SpainPack (DNI 23-letter checksum table per RD 1553/2005 + NIE + CIF + Spanish phone/address). Both opt-in via a single FQCN in config('pii-redactor.packs'). The PackContract interface + DetectorPackRegistry make it equally trivial for the community to contribute FrancePack, NetherlandsPack, PortugalPack next — each as a self-contained bundle of detectors with checksum-source citations and 10/5 valid/invalid fixtures.

Multi-country detectors (email, iban with mod-97 for every ISO 13616 country, credit_card with Luhn) stay always-on regardless of which packs you load — they have no jurisdictional flavour.

2. Deterministic regex + checksum, no LLM in the hot path

Every first-party detector is a pure function of its input. No external HTTP call, no per-token cost, no rate limit. A 1 MB chat log redacts in ~280 ms and the output is identical on every machine. The optional NER layer (v0.3+) ships behind a config switch; the default path never touches a network.

3. Strategy is a runtime decision, not a compile-time one

The same detected match can be masked ([REDACTED] for human-facing logs), hashed ([hash:abc123ef01234567] for cross-record joins on pseudonymous data), tokenised ([tok:email:abc123ef01234567] with a reversible salt-derived map for forensic recovery), or dropped (empty string for forwarding to lossy systems). Switching strategy is a one-line override on Pii::redact($text, new HashStrategy(...)) — no detector code changes.

4. Detector overlap is resolved deterministically

When two detectors emit overlapping byte ranges (e.g. an email-shaped string that also matches a phone heuristic), the engine keeps the earlier match (lower offset) and drops the latecomer. The behaviour is documented, tested, and predictable — callers can audit it via Pii::scan().

5. Standalone-agnostic — zero AskMyDocs symbols

laravel-pii-redactor is a community package. It is not coupled to AskMyDocs, the sister patent-box tracker, the eval-harness, the Regolo driver, or any other Padosoft project. An architecture test (tests/Architecture/StandaloneAgnosticTest.php) walks src/ with RecursiveDirectoryIterator on every CI run and asserts the forbidden-substring list (KnowledgeDocument, KbSearchService, AskMyDocs, PatentBoxTracker, LaravelFlow, EvalHarness, Regolo, ...) never appears.

Features at a glance

• 🇪🇺 EU country pack architecture — PackContract interface + DetectorPackRegistry boots country packs from config('pii-redactor.packs'). Three packs ship in v1.1: ItalyPack (default), GermanyPack (opt-in), SpainPack (opt-in). FrancePack, NetherlandsPack, PortugalPack are community PRs welcome (see CONTRIBUTING-PACKS.md).
• 3 always-on multi-country detectors (no pack required):
  • email — pragmatic RFC-5321 shape match.
  • iban — ISO 13616 IBAN for every registered country (~75) + mod-97 verification.
  • credit_card — 13–19 digit PAN with Luhn validation.
• ItalyPack (default — 4 detectors):
  • codice_fiscale — 16-char Italian fiscal code with full CIN checksum (Decreto Ministeriale 23/12/1976).
  • p_iva — 11-digit Italian VAT with Luhn-style checksum + zero-payload sentinel rejection.
  • phone_it — Italian mobile + landline (with optional +39 / 0039 prefix).
  • address_it — Italian street address heuristic (Via / Viale / Piazza / Corso / Largo / Strada / Vicolo / Lungomare + compound forms Via dei, Via della, Via d'…); civic number + 5-digit CAP + city optional.
• 4 pluggable redaction strategies: MaskStrategy, HashStrategy (deterministic, salt-derived, namespaced per detector), TokeniseStrategy (reversible pseudonymisation with detokenise() + dumpMap() / loadMap() for cross-process recovery), DropStrategy.
• Persistent reverse-map storage (v0.2) — TokenStore interface + InMemoryTokenStore (default, process-local) + DatabaseTokenStore (Eloquent-backed, shipped migration pii_token_maps). The same [tok:...] token detokenises across deploys / queue workers when the database driver is wired. Switch via PII_REDACTOR_TOKEN_STORE=database and run php artisan vendor:publish --tag=pii-redactor-migrations && php artisan migrate.
• Audit-trail event (v0.2) — opt-in PiiRedactionPerformed Laravel event fired after a redact() call that produced at least one detection, when PII_REDACTOR_AUDIT_TRAIL=true (or the structured audit_trail.enabled key is set). No-op redactions (engine disabled, empty input, zero detections) skip the dispatch — the event signals "redaction occurred", not "request processed". Event carries counts only (detector → match count, total, strategy name) — NEVER raw PII or redacted output. GDPR-friendly by construction.
• NER drivers (v0.2 scaffold + v0.3 production) — NerDriver interface + StubNerDriver (no-op default), HuggingFaceNerDriver (HuggingFace Inference API via Http::, opt-in via PII_REDACTOR_HUGGINGFACE_API_KEY), SpaCyNerDriver (generic spaCy HTTP server protocol returning Doc.to_json() shape, opt-in via PII_REDACTOR_SPACY_SERVER_URL). Both real drivers fail open on HTTP errors so a NER outage cannot block deterministic redaction. Driver detections merge into the same overlap-resolution pipeline as first-party detectors.
• Cache-backed TokenStore (v0.3) — third driver alongside InMemoryTokenStore and DatabaseTokenStore. Uses Laravel's Illuminate\Contracts\Cache\Repository so deployments swap between Redis / Memcached / DynamoDB / array (test) without touching package code. Maintains an explicit index entry so dump() / clear() work without scanning the backend keyspace. Optional TTL via PII_REDACTOR_TOKEN_STORE_CACHE_TTL. Switch with PII_REDACTOR_TOKEN_STORE=cache.

• Custom-rule YAML packs (v0.3 + v1.0 auto-register) — register tenant-specific detectors from *.yaml files. v1.0 adds an SP-level auto-register loop driven by config('pii-redactor.custom_rules.packs') so you can drop YAML packs into a config array and the SP wires them at boot. The host-controlled API still works for tenant-specific bootstrap logic:

  Each rule has a name + PCRE pattern + optional flags (default u). Invalid PCRE is rejected at first-match time with a clear CustomRuleException. Useful for Italian professional registry IDs (ISCR-..., Tess-XX-...), tenant-specific account codes, project tracker identifiers, etc.

• Live test suite (v0.3) — tests/Live/ houses opt-in tests against real APIs (HuggingFace, spaCy server). Each test self-skips unless PII_REDACTOR_LIVE=1 AND its driver-specific credentials are set. CI runs Unit + Architecture only — Live tests are operator-driven. See tests/Live/README.md for the convention.
• Typed DetectionReport — total(), countsByDetector(), samplesByDetector(cap), toArray(). Stable JSON shape for downstream auditors.
• Admin-ready headless APIs — RedactorAdminInspector exposes a secret-free runtime snapshot; RedactionStrategyFactory builds mask / hash / tokenise / drop strategies for admin previews; DetectionReportFormatter masks samples by default; TokenResolutionService detokenises through the configured TokenStore even when the current strategy is not tokenise; CustomRulePackInspector reports YAML pack health without registering detectors. Full implementation plan for the separate Laravel 13 + Vite + React + Tailwind UI package lives in docs/admin-panel-architecture-plan.md.
• Pii::extend() registry for custom detectors (custom_codice_iscrizione_albo, project-specific account ids, etc.).
• Artisan command — php artisan pii:scan path/to/file.txt --pretty or cat data | php artisan pii:scan --from=stdin (samples masked by default; pass --show-samples for raw values during interactive forensics).
• Standalone-agnostic — zero coupling to AskMyDocs / sister packages, enforced by an architecture test.
• PHP 8.3 / 8.4 / 8.5 × Laravel 12 / 13 matrix. Pint + PHPStan level 6 + 400+ PHPUnit tests on every push.
• Padosoft AI vibe-coding pack (.claude/) — Claude Code skills (R36 review loop, R10–R37 rules) + agents (review pre-push) + commands (/create-job, /domain-scaffold).

🇪🇺 EU country pack architecture

Why country packs exist. Italian fiscal codes need PHP code with checksum logic. So do German Steuer-ID (mod-11), Spanish DNI (letter-checksum), French NIR (mod-97). Pure regex isn't enough. Each country needs its own bundle of detectors — but the package shouldn't ship all of EU's IDs by default if you only operate in Italy. Hence packs: opt-in jurisdiction bundles, registered via the PackContract interface and a config array.

Enable / disable example:

To disable Italy on an English-only deployment:

The multi-country detectors (Email, IBAN, CreditCard) keep working regardless — they are never part of a country pack because they have no jurisdictional flavour.

Build your own country pack — 3-step recipe

The recipe below uses Iceland (small, real European country, no community pack ships yet) as a "blank slate" example. The real kennitala checksum is mod-11 over the first 9 digits.

Step 1 — Create the detector(s)

Step 2 — Wrap them in a pack

Step 3 — Register it

That's it. The ServiceProvider boots, the DetectorPackRegistry walks the config list, instantiates each pack, and feeds its detectors() into the engine. Pii::redact() and Pii::scan() now redact / report kennitala matches alongside the always-on detectors.

🚀 Contribute your country pack

Built a GermanyPack / SpainPack / FrancePack / etc. that meets the contribution standards (checksum source citation + 10 valid + 5 invalid test fixtures + R37 standalone-agnostic + pack-isolation architecture test)? Open a PR — see CONTRIBUTING-PACKS.md for the workflow. Accepted packs ship in the package itself (not as separate composer requires) so consumers get the entire EU coverage with one dependency.

Comparison vs alternatives

✅ = supported out of the box · 🟡 = partial / requires custom code or paid tier · ❌ = not supported

Platform & deployment

EU country detector coverage (deterministic, checksum-validated)

Replacement strategies (mask / hash / tokenise / drop)

Persistence & infrastructure

Extensibility & community

Quality gates & guarantees

laravel-pii-redactor is not a Presidio replacement for fuzzy named-entity recognition — Presidio's transformer-backed NER layer (PERSON, ORG, LOC) is genuinely more capable as a free-form classifier, and you can plug it (or any HuggingFace / spaCy model) into this package via the NerDriver interface (v0.3+). The deterministic regex + checksum + per-country pack core stays the strongest layer where the existing EU-aware options are weakest, and the persistent reverse-map storage + community-contributable pack architecture are unique to this package across the comparison set.

Installation

Laravel auto-discovery wires the PiiRedactorServiceProvider and the Pii facade alias. Publish the config to override defaults:

Set the salt for the hash / tokenise strategies in your .env:

Quick start

Usage examples

Reversible pseudonymisation for forensic exports

Custom detector via Pii::extend()

CLI — scan a file in CI

Default (masked-samples) output:

With --show-samples (raw values restored):

Laravel integration recipes

The package is transport-agnostic — Pii::redact() and RedactorEngine::redact() accept a string and return a redacted string, so they slot into HTTP, queue, CLI, and event paths identically.

Side-effects to expect. redact() is not strictly pure: when the active strategy is tokenise it persists (token, original) rows to the configured TokenStore (see pii-redactor.token_store), and when audit-trail is enabled it dispatches a PiiRedactionPerformed event after every call. Both behaviours are documented in the RedactorEngine source. Keep this in mind if you wrap the call in a transaction or invoke it from a hot loop.

This section documents the two production-tested integration shapes plus the strategy decision tree.

Real-world reference: AskMyDocs (the v4.1+ enterprise RAG / chat platform) wires this package at four observable touch-points using the patterns below. Source available under app/Http/Middleware/RedactChatPii.php, app/Services/Kb/EmbeddingCacheService.php, app/Services/Admin/AiInsightsService.php, and app/Http/Controllers/Api/Admin/LogViewerController.php of lopadova/AskMyDocs — feel free to copy.

A note on config namespaces — package vs host

This package's own runtime knobs (master switch, default strategy, salt, mask token, NER driver, …) live under pii-redactor.* (file: config/pii-redactor.php) and are driven by the documented PII_REDACTOR_* env vars. Do not invent a parallel app.pii_redactor tree — turning the package on via PII_REDACTOR_ENABLED=true will not flip a guard that reads config('app.pii_redactor.enabled').

What you DO need is your own per-touch-point integration knobs (e.g. "the chat middleware is active", "the embedding pre-redact is active"). Pick a host-app config namespace and document the env-var names alongside the package's own. The recipes below use a placeholder namespace myapp.pii.* — substitute your project's real config key (AskMyDocs uses kb.pii_redactor.*, for example).

Integration shape A — HTTP middleware (best practice for chat / API write paths)

This is the recommended pattern when redaction must happen before the controller persists the request to a database, dispatches a queue job, or calls an external LLM. The middleware mutates a specific request field (typically content / message / body) so every downstream consumer (controller, model creating event, queue job, log driver) sees the redacted form automatically.

1. Create the middleware:

2. Register the alias in bootstrap/app.php (Laravel 11+):

3. Bind it ONLY to the routes that handle user-supplied free-form content. Do NOT slap it on a global middleware group — that would also redact admin forms, configuration values, and curator-supplied content like markdown ingest payloads. The whole point is narrow scope:

4. Pin the binding scope with an architecture test so a future refactor cannot accidentally extend the binding to admin / curator / ingest routes. Use a substring match (not a prefix match) so bare URIs like admin and api/admin are caught alongside admin/... and api/admin/...:

Integration shape B — service-layer call (for non-HTTP write paths)

Use this when the data enters your system from somewhere other than an HTTP request — queue jobs, scheduled imports, CLI commands, or service-to-service callers. Inject RedactorEngine directly and call redact() at the boundary where the untrusted text first lands in your domain.

Forcing a strategy override. When you want a specific strategy for a service path (regardless of the package's default), pass an override to redact() rather than autowiring a fresh strategy instance — that way you respect the host's configured mask_token, salt, hex length, etc. The cleanest way is to construct the strategy explicitly from the package's config so the host's overrides flow through:

Example — queue job that consumes a webhook payload before persisting. Note the explicit string guard — webhook payloads can arrive as arrays / objects / nulls, and redact() is typed string-in / string-out:

Strategy decision tree — which one for which surface

The four ship-with-the-box strategies (MaskStrategy, HashStrategy, TokeniseStrategy, DropStrategy) are NOT interchangeable. Pick the one whose properties match the surface you're protecting.

Best-practice checklist for a production deploy

• [ ] Default-off integration knobs: every host integration knob (your myapp.pii.middleware_active, myapp.pii.redact_before_embeddings, etc.) defaults false. Hosts opt in by flipping an env var. The package's own pii-redactor.enabled defaults true (the package is harmless when no integration calls it).
• [ ] Narrow scope: middleware is bound only to routes that handle user-supplied free-form content. Curator / admin / configuration routes are NEVER bound (would silently corrupt KB pipelines, mangle role names, etc.).
• [ ] Architecture test pin with a substring match (not a prefix match) so bare admin / api/admin URIs are caught.
• [ ] Tenant-scoped reads: when reading from tables that store redacted records (e.g. chat_logs), scope the query to the active tenant if your app is multi-tenant. The package itself is tenant-agnostic; your reads must NOT be.
• [ ] Detokenise gate: if you expose an operator-driven detokenise endpoint, gate it with a dedicated permission AND audit every call (200 + 403). Single-use confirm tokens with lockForUpdate() held inside the same transaction as the update('used_at') write are the canonical anti-replay shape.
• [ ] Strategy preflight: when the row's text contains no [tok: literals, surface a 422 (not 200 with empty body) — that's the clean signal that there's nothing to detokenise. Pretending success on a one-way deploy is a worse UX than the explicit "this row has no tokenised content" message.
• [ ] Audit-trail visibility: every detokenise / unmask call writes a row to your audit table tagged with the actor, the target row id, the timestamp, the IP, and the user-agent. The host is responsible for choosing where (e.g. admin_command_audit table in AskMyDocs).
• [ ] Salt is APP_KEY-class: rotating PII_REDACTOR_SALT after the fact is rare. Existing tokenise rows in pii_token_maps are detokenised by direct token-literal lookup, so a salt change does NOT invalidate stored mappings — only NEW tokens emit hex digests derived from the new salt. For HashStrategy, by contrast, salt rotation does break cross-system joins (because every old hash becomes unrecoverable). Plan accordingly.
• [ ] NER off in the hot path (default): the regex / checksum detectors are deterministic and microsecond-fast. Turn the optional NER drivers ON only on offline / batch surfaces or with an explicit per-request opt-in.

Web Panel UI

This package now has a companion web panel with a polished Laravel admin dashboard: padosoft/laravel-pii-redactor-admin.

The UI gives operators a safe overview of the redaction engine, detector hits, token-map activity, audit events, custom-rule health, and strategy configuration. It is built on top of the secret-free inspector APIs exposed by this package, so the panel can surface runtime state without returning salts, API keys, raw PII, or token originals.

Admin panel readiness

The core package is intentionally headless: it does not ship controllers, routes, React components, or admin UI assets. The admin dashboard lives in the separate padosoft/laravel-pii-redactor-admin package, while this package exposes the safe backend primitives needed by that UI.

• RedactorAdminInspector::snapshot() returns a secret-free runtime snapshot: enabled state, default strategy, audit flag, token-store driver/class, NER status, detectors, packs, and custom-rule count. It does not expose salts, API keys, raw PII, token originals, or redacted output.
• RedactionStrategyFactory::names() and make() provide the public strategy construction surface for admin preview APIs, so hosts do not duplicate private service-provider logic.
• DetectionReportFormatter::safeArray() converts DetectionReport to an API-ready payload and masks samples by default as [email], [iban], etc.
• TokenResolutionService::detokeniseString() resolves only [tok:<detector>:<hex>] values referenced in the input through the configured TokenStore; it never loads the whole reverse map.
• CustomRulePackInspector::configuredPacks() reports configured YAML pack health without mutating the engine or registering detectors.

The companion UI is the Laravel 13.x package padosoft/laravel-pii-redactor-admin, built with Vite, React, TypeScript, and Tailwind CSS and connected to these APIs. The implementation contract, endpoint plan, audit schema, PHPUnit gates, and frontend gates are documented in docs/admin-panel-architecture-plan.md.

Configuration reference

Every key in config/pii-redactor.php is documented inline. Highlights:

• enabled — master switch. When false, Pii::redact() returns input unchanged. Wired all the way down to the RedactorEngine constructor so PII_REDACTOR_ENABLED=false in .env short-circuits redaction without code changes.
• strategy — mask | hash | tokenise | drop. Default mask token is [REDACTED].
• salt — required for hash and tokenise. Treat like APP_KEY.
• mask_token — override the default mask string.
• hash_hex_length — between 4 and 64; default 16 (= 64-bit namespace, well above the birthday bound for any realistic corpus). Drop to 8 only if you accept that downstream joins on [hash:...] may collapse unrelated records once the dataset crosses ~30k uniques.
• token_hex_length — between 8 and 64; default 16 for the [tok:<detector>:<id>] id portion. Same collision argument as hash_hex_length.
• detectors — whitelist of multi-country detector classes the ServiceProvider auto-registers (EmailDetector, IbanDetector, CreditCardDetector by default). Removing an entry disables the detector. Country-specific detectors are loaded via the packs array, not here. Custom detectors registered via Pii::extend() bypass this list. Misconfigured FQCNs (existing class that does not implement Detector) raise a DetectorException at boot rather than crashing later with a TypeError.
• packs — array of PackContract FQCNs the ServiceProvider boots into the DetectorPackRegistry. Default ships [ItalyPack::class]. Add GermanyPack::class (German Steuer-ID + USt-IdNr + phone/address) or SpainPack::class (DNI + NIE + CIF + phone/address) for additional EU coverage. Custom packs welcome — see CONTRIBUTING-PACKS.md. Misconfigured FQCNs are caught at boot.
• custom_rules.auto_register — when true (v1.0+), the SP walks custom_rules.packs and auto-registers each YAML pack at boot. Defaults to false for v0.x parity.
• custom_rules.packs — array of ['name' => ..., 'path' => ...] entries. The name becomes the Pii::extend() alias AND the CustomRuleDetector::name(). Example: ['name' => 'custom_it_albo', 'path' => storage_path('app/pii-rules/it-albo.yaml')]. Validation errors throw CustomRuleException at boot.
• audit_trail_enabled (v0.1 BC) and audit_trail.enabled (v0.2 structured) — when true, the engine fires PiiRedactionPerformed after every redact() call. Payload carries counts only (no raw PII or redacted output). The structured key is preferred; the flat key remains as a fallback so v0.1 hosts upgrade transparently.
• ner.enabled / ner.driver / ner.drivers — opt-in NER. Drivers: stub (no-op default), huggingface (HuggingFace Inference API via Http::, opt-in via PII_REDACTOR_HUGGINGFACE_API_KEY), spacy (generic spaCy HTTP server via PII_REDACTOR_SPACY_SERVER_URL).
• token_store.driver — memory (default) | database | cache. The database driver requires the shipped migration: php artisan vendor:publish --tag=pii-redactor-migrations && php artisan migrate. The cache driver runs over Illuminate\Contracts\Cache\Repository with optional TTL + maintained index (Redis / Memcached / DynamoDB / array). Switch with PII_REDACTOR_TOKEN_STORE=database or =cache.
• token_store.database.connection / token_store.database.table — isolate the pii_token_maps table on a dedicated DB connection (recommended for hosts that already partition PII from operational data).
• token_store.cache.store / token_store.cache.prefix / token_store.cache.ttl — pin the cache backend (redis, memcached, array, etc.), key prefix, and optional TTL for the CacheTokenStore driver.

Architecture

The engine itself is stateless with respect to the input. Calls to redact() / scan() are pure functions of (text, registered detectors). Overlap resolution is left-to-right, longer-match-wins on tie — see RedactorEngineTest::test_overlapping_detections_are_resolved_left_to_right.

AI vibe-coding pack

This repository ships with a .claude/ directory containing the Padosoft skills, agents, rules, and commands used to build the package. Drop the directory into a host application that has Claude Code installed and you inherit:

• R36 — Copilot PR review loop + R37 — branching strategy as project rules.
• Pre-push review agent (pre-push-self-review) that anticipates Copilot findings.
• Slash commands (/create-job, /domain-scaffold, /domain-service) tuned for the Padosoft Laravel pattern.
• Skills covering testid conventions, PHPUnit / Vitest / Playwright authoring, CI failure investigation.

Open the repo in Claude Code and /help lists everything.

Testing — Default + Live

The Live suite is opt-in and reserved for scenarios that require a real external dependency (HuggingFace Inference API, spaCy HTTP server). Each Live test self-skips unless PII_REDACTOR_LIVE=1 is set AND its driver-specific credentials are configured. CI runs Unit + Architecture only — Live is operator-driven and perf is excluded by default in shared-runner CI.

Performance

Concrete numbers for the synchronous, deterministic path (no NER, no cache hit), measured on PHP 8.4 / Laravel 13 / standard CI hardware:

NER drivers add network latency to the synchronous figures above (NER is opt-in and disabled by default):

• HuggingFace Inference API — cold start 10–30 s (model warm-up); warm requests ~150 ms RTT.
• spaCy local HTTP server — ~30–80 ms RTT.

Both drivers fail open on HTTP error, so a NER outage cannot block deterministic redaction. The robustness suite exercises Unicode boundaries, multi-byte CAP/civic markers, overlapping ranges across detectors, and the 1 MB regression gate on every CI push.

Roadmap

• v0.1.0 (W7, shipped 2026-04-30) — 6 deterministic detectors (codice_fiscale, p_iva, iban, email, phone_it, credit_card), 4 strategies, Pii::extend(), pii:scan command (masked samples by default), 80+ PHPUnit tests, standalone-agnostic invariant.
• v0.2.0 (W4.1, shipped 2026-05-03) — address_it Italian street-address heuristic detector (7th first-party detector). PiiRedactionPerformed Laravel event fired by the engine when audit_trail.enabled = true; carries counts only (no raw PII). Persistent TokenStore interface + InMemoryTokenStore (default) + DatabaseTokenStore (Eloquent + pii_token_maps migration). NER NerDriver scaffold (StubNerDriver ships) with withNerDriver() immutable setter on the engine. 158 PHPUnit tests on the v0.2 surface.
• v0.3.0 (W4.1, shipped 2026-05-03) — production NER drivers (HuggingFaceNerDriver + SpaCyNerDriver via Http::), Italian custom-rule YAML loader (CustomRule + CustomRuleSet + YamlCustomRuleLoader + CustomRuleDetector + CustomRuleException), cache-backed TokenStore driver (CacheTokenStore over Illuminate\Contracts\Cache\Repository with TTL + index), Live test harness. 320 PHPUnit tests / 658 assertions.
• v1.0.0 (W4.1, this PR) — EU country pack architecture. PackContract interface + ItalyPack reference implementation. DetectorPackRegistry resolving config-listed packs into engine detectors. SP auto-register loop for custom_rules YAML packs (closes v0.3 deferred TODO). Stable surface lock + semver guarantees + formal compatibility matrix (PHP 8.3/8.4/8.5 × Laravel 12/13). Migration guide v0.x → v1.0 (no breaking changes). SECURITY.md. 400+ PHPUnit tests on the v1.0 surface.
• v1.1.0 (W4.1, this PR) — first community-style packs land alongside ItalyPack:
  • GermanyPack — steuer_id (mod-11 ISO 7064 per §139b AO), ust_idnr (BMF Method 30 per §27a UStG), phone_de, address_de. 10 valid + 5 invalid + 5 wrong-format checksum fixtures per detector.
  • SpainPack — dni (23-letter table per RD 1553/2005), nie, cif, phone_es, address_es. Same fixture standards.
• v1.2+ candidates — FrancePack (NIR mod-97 + TVA), NetherlandsPack (BSN), PortugalPack (NIF). Community PRs welcome — see CONTRIBUTING-PACKS.md.

Migration guide v0.x → v1.0

No breaking changes. v1.0 is a drop-in upgrade from v0.3 / v0.2 / v0.1. Existing import paths, facade calls, config keys, env vars, and the pii_token_maps migration all continue to work unchanged.

What you gain by upgrading:

• The four Italian detectors continue to be registered automatically (now via ItalyPack instead of the flat pii-redactor.detectors list, but the observable behaviour is identical — same detector names, same DetectionReport shape, same overlap-resolution order).
• Hosts can now opt-in to additional country packs (v1.1+) by adding their FQCN to config('pii-redactor.packs').
• YAML custom-rule packs auto-register at boot when pii-redactor.custom_rules.auto_register = true — no more manual Pii::extend() bootstrap code.

What you should consider doing:

• Move tenant-specific Pii::extend() calls out of bootstrap into the YAML pack format (one yaml file per detector pack); set auto_register = true.
• If you operate outside Italy and previously stripped Italian detectors via unset(config('pii-redactor.detectors')[...]), switch to the cleaner 'packs' => [] pattern.
• If you ship custom country detectors, consider proposing them upstream as a community pack — see CONTRIBUTING-PACKS.md.

Contributing

PRs welcome. Please read:

• CONTRIBUTING.md — general PR workflow.
• CONTRIBUTING-PACKS.md — how to contribute a country pack (GermanyPack, SpainPack, etc.): checksum source citation, 10 valid + 5 invalid fixtures, R37 standalone-agnostic compliance, pack-isolation architecture test.

Every PR follows the R36 Copilot review + CI green loop before merge. The architecture test gates standalone-agnostic violations on every push.

Security

Found a vulnerability? Email [email protected] — please do not open a public issue. See SECURITY.md for the full disclosure policy.

License

Apache-2.0 — see LICENSE.