Pii Sanitizer Symfony Laravel Package

Getting Started

This package is a Symfony bundle (jackal/pii-sanitizer-symfony), not a native Laravel package. As a Laravel developer you will almost always consume the underlying sanitizer logic and wire it up yourself rather than relying on the bundle's autoconfiguration — but the bundle is still the source of truth for service definitions, config schema, and default rule sets, so read it first.

v0.2.0 is a breaking release: the namespace was renamed to Jackal\PiiSanitizer\Bundle. Every use statement, container alias, and string-referenced class name from v0.1.x must be updated. Treat this as a major bump despite the 0.x version.

Minimal steps:

1. composer require jackal/pii-sanitizer-symfony:^0.2
2. Open the bundle's DependencyInjection/ and Resources/config/ directories first — this is where the sanitizer service, its rule chain, and default config keys live. That is your integration contract.
3. In Laravel, register a thin service provider that binds the sanitizer to the container:

   // app/Providers/PiiSanitizerServiceProvider.php
   public function register(): void
   {
       $this->app->singleton(\Jackal\PiiSanitizer\Bundle\Sanitizer::class, function ($app) {
           return new \Jackal\PiiSanitizer\Bundle\Sanitizer(
               rules: config('pii.rules', [])
           );
       });
   }
   

4. First use case: sanitize outbound payloads before they are persisted or logged — request logs, failed-job payloads, audit trails, and webhook bodies.

Verify the rename took effect with composer dump-autoload -o followed by a class_exists smoke test; a stale classmap is the most common cause of "class not found" after this upgrade.

Implementation Patterns

Migration from v0.1.x (do this first). Sweep your codebase for the old root namespace and rewrite it:

grep -rn "Jackal\\\\PiiSanitizer\\\\" app/ config/ tests/ | grep -v "\\\\Bundle"

Then update composer.json to ^0.2 and regenerate the lock file. Any cached container/config (php artisan config:clear && php artisan cache:clear) must be flushed, since compiled Symfony-style container definitions embed FQCNs.

Facade wrapper. Laravel developers expect facades; wrap the sanitizer so call sites stay terse and the namespace change is contained to one file:

class Pii extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return Sanitizer::class;
    }
}

Pipeline / middleware usage. The highest-value pattern is a middleware that scrubs inbound request data before it hits validation or logging:

public function handle($request, Closure $next)
{
    $request->merge(Pii::sanitize($request->all()));
    return $next($request);
}

Be deliberate about ordering: sanitize after signature verification (you need the raw body to verify webhooks) but before anything writes to the database or a log channel.

Queue jobs. Sanitize in the job's __construct or use failed_jobs scrubbing — exception payloads are the single biggest PII leak vector in most Laravel apps. A JobProcessing/JobExceptionOccurred listener that runs the sanitizer over $event->job->payload() covers jobs you didn't write.

Config-driven rule sets. Keep the rule definitions in config/pii.php and map them onto whatever array/iterable the bundle's sanitizer expects. This decouples you from the bundle's config schema, which is unstable at 0.x.

Testing pattern. Bind a no-op or recording sanitizer in tests so assertions aren't fighting redaction, then have one dedicated test per rule asserting the exact redaction output. Namespace renames like v0.2.0 break test doubles silently — mock against interfaces, not the concrete Bundle\Sanitizer class, wherever the package exposes one.

Gotchas and Tips

• The v0.2.0 rename is not just a use statement change. Symfony bundle class names also appear in config/bundles.php-style registries, service resource globs, YAML/XML service definitions, and compiler passes. If you bridged the bundle via a custom container, re-check the alias strings — a stale alias fails at container compile time, not at runtime, so it can pass a casual php -r test and still break artisan.
• Pin the version. At 0.x, minor bumps carry breaking changes by design. "jackal/pii-sanitizer-symfony": "0.2.*" is safer than ^0.2 until you've reviewed a release's changelog.
• This is not a Laravel package. There is no auto-discovered service provider, no published config, no Blade/queue/HTTP integration. Anything you want in Laravel, you write. Budget for that — it's a wrapper project, not a composer require-and-go.
• Sanitize on write and on read. Existing rows written before you adopted the package are still full of PII. A one-off backfill command over logs/audit tables is usually required, and it needs the same rule set as the live path or you get inconsistent redaction.
• Redaction is lossy. Don't sanitize data you still need to operate on — hashing or tokenizing identifiers you must join on is a different (and harder) problem than masking. Decide per-field before turning the sanitizer loose on a whole payload.
• Debugging tip: when a field isn't being redacted, first check whether the sanitizer is receiving a nested array/object versus a flat string. Most "it doesn't work" reports are shape mismatches, not rule bugs. Dump the input after any json_decode/toArray conversion.
• Extension point: implement the package's rule/strategy interface (check Bundle\ for the contract) rather than monkey-patching the sanitizer. Custom rules survive namespace churn far better than subclasses of concrete classes.
• Log channel safety net: configure a Monolog processor that pipes every record through the sanitizer. It's a cheap belt-and-braces layer that catches PII added by third-party packages you don't control.