Sensitive Text Detect Bundle Laravel Package

Getting Started

Install via Composer:

composer require tourze/sensitive-text-detect-bundle

First place to look is the bundle's README.md and, if it's thin, the DependencyInjection/ directory — that's where the configuration tree and default service definitions live. The public service ID is usually a detector/sensitive-word service you can autowire by its interface.

Laravel caveat up front: this is a Symfony bundle, not a Laravel package. There is no extra.laravel service-provider auto-discovery. In a Laravel app you have two options:

1. Use the underlying library directly (tourze/sensitive-word or whatever the bundle wraps) and skip the bundle's DI glue, or
2. Register the bundle's services manually in a Laravel service provider and bind the detector interface in the container.

For a first use case, wire the detector into a form request or a middleware that scans incoming user-generated text (comments, nicknames, bios) before it's persisted:

$hits = $detector->detect($request->input('body')); // returns matched words / bool depending on API

Confirm the return shape from the service's method signatures before building validation around it — different Tourze wrappers return either a boolean, a list of matched words, or a result object.

Implementation Patterns

Service injection / container binding. Autowire the detector interface rather than the concrete class so you can swap implementations in tests. In Laravel, bind it in a provider:

$this->app->singleton(SensitiveWordDetectorInterface::class, fn ($app) =>
    $app->make(SensitiveWordDetector::class)
);

Validation rule. Wrap detection in a custom Laravel rule so it composes with the rest of your validation:

class NoSensitiveWords implements ValidationRule
{
    public function __construct(private Detector $detector) {}

    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if ($this->detector->detect($value)) {
            $fail('The :attribute contains prohibited language.');
        }
    }
}

Middleware for broad coverage. For apps with many write endpoints, a TerminateSensitiveContent middleware that only inspects POST/PUT/PATCH string fields avoids sprinkling rules everywhere. Keep an allowlist of routes (webhooks, admin) to skip.

Dictionary as configuration, not code. Load the word list from config/sensitive.php (or the bundle's YAML) pointing at a file path. Keep the list versioned separately from application code so moderators can update it without a deploy.

Precompile / warm the word tree. Most DFA-backed detectors build a trie from the dictionary on first use. Warm it in a cache-warmer or on container boot (or cache the built structure to Redis/file) so the first request after deploy isn't slow. This is the single biggest integration tip for day-to-day performance.

Masking/replacement. For display filtering (e.g. showing a redacted comment) use the replace/mask method if exposed; otherwise run detection and do the substitution yourself with the returned match offsets/words.

Gotchas and Tips

• Encoding. Sensitive-word tries are character-based. Ensure your strings are UTF-8 and, if you handle CJK text, that the library splits on multibyte characters. mb_* functions and a mb_internal_encoding('UTF-8') at bootstrap prevent corrupt matching.
• False positives. Short words inside longer words ("ass" in "class", "草" in "草莓") are the classic trap. If the library doesn't support word boundaries or whitelisting, add a pre-filter or a secondary allowlist check after a hit.
• Normalization. Attackers evade with full-width chars, spaces, homoglyphs, and zero-width joiners. Normalize (NFKC), strip zero-width characters, and lowercase before detection — do this in your adapter, not by mutating the library.
• Case and punctuation handling is often controlled by a config flag (ignoreCase, splitByPunctuation). Check the bundle's config tree; defaults vary.
• Bundle vs. framework coupling. If you go the Laravel route, the bundle's Symfony Configuration/Extension classes won't auto-run. Read the config defaults out of those classes and replicate them in your own config file rather than guessing.
• Caching invalidation. If you cache the compiled dictionary, key the cache on a hash of the source file contents, otherwise updated word lists silently won't take effect.
• Testing. Point the detector at a tiny fixture dictionary in tests (2–3 words) so assertions are deterministic and fast; don't rely on the shipped production list.
• Debugging misses. When a word isn't caught, first verify it survives your normalization step, then check the dictionary was actually loaded (log the word count at boot), then check the trie cache is fresh — roughly in that order.
• Extension point. If you need custom scoring (weights per word, severity levels) or external dictionary sync, decorate the detector interface rather than forking the bundle; that keeps the upgrade path to patch releases clean.
• Version pinning. The 1.1.0 changelog is only a compare link with no described changes. Pin to ^1.1 and read the git diff 1.0.1..1.1.0 yourself before upgrading in production — Tourze bundles occasionally rename service IDs or move classes between namespaces in minor bumps.