Blasp Laravel Package

Product Decisions This Supports

• Build vs. buy for content moderation. Profanity filtering is a solved-ish, low-differentiation problem. This package replaces a bespoke regex + wordlist implementation (typically 1–2 weeks of engineering plus ongoing dictionary upkeep) with a maintained, driver-based library. Buy — unless moderation is a core differentiator (e.g., a kids' social product where false negatives are a safety incident).
• Scope of the moderation feature. The package defines a natural "Tier 1" scope for a launch: catch obvious profanity, mask it in stored content, surface a score. It explicitly does not cover hate speech nuance, context, sarcasm, or image moderation — which sets the boundary for a roadmap that later layers in a hosted moderation API for Tier 2.
• Enforcement policy as configuration, not code. sanitize vs. reject at the middleware, model, and validation layers lets Product own the policy question ("do we block the comment or mask it?") without an engineering ticket. This is directly useful for A/B testing moderation strictness per surface: e.g., sanitize on public comments, reject on usernames.
• Severity tiering enables graduated UX. Severity::Mild/Moderate/High/Extreme plus a 0–100 score supports differentiated product responses: allow mild through, flag high for review, hard-block extreme. This is the difference between a blunt "we don't allow bad words" wall and a usable product.
• Roadmap prioritization signal via events. ProfanityDetected / ContentBlocked / ModelProfanityDetected give a cheap instrumentation path — measuring how often real users hit the filter tells you whether to invest in better moderation or relax the rules.
• Multi-language reach. English/Spanish/German/French support gates or de-risks expansion into those markets without a new vendor evaluation per locale.
• Use cases that fit cleanly: UGC comments and reviews, display names and handles, chat messages, support ticket bodies, marketplace listing titles/descriptions, and any admin-facing dashboard that needs to flag rather than block.

When to Consider This Package

Adopt when:

• You're on Laravel 8+ / PHP 8.2+ and want a first-party-feeling integration (middleware alias, validation rules, Eloquent trait, Blade directive, Str macros) rather than a standalone library you wire up yourself.
• Your moderation need is text hygiene — keeping public surfaces presentable — not safety-critical abuse detection.
• You want to avoid a network round-trip and per-call vendor cost. This runs in-process, which matters for high-volume, low-margin endpoints.
• You need obfuscation resistance (leet-speak, separators, doubled letters, phonetic sound-alikes). That's genuinely the hard part of the problem and is where the driver architecture earns its keep.
• You want masking (not just blocking) — clean(), grawlix, or a custom callback map directly to how content renders.
• You need a stopgap while a proper moderation vendor is procured.

Look elsewhere when:

• Safety-critical or regulated context. No ML, no contextual understanding, no hate-speech/self-harm/CSAM coverage. For minors' platforms, trust & safety obligations, or app-store compliance, you need a dedicated provider (Perspective API, OpenAI moderation, AWS Rekognition/Comprehend, Hive, etc.).
• Adoption risk tolerance is low. 356 stars with 0 dependents is a weak ecosystem signal. This is effectively a single-maintainer package; if it's abandoned, you own the fork. For a multi-year platform commitment, weigh that against a vendor with an SLA.
• Non-English-first products outside the four supported languages. The phonetic driver is English-only (metaphone()-based); the curated false-positive list is English-tuned. Other locales will need dictionary work you'd have to do yourself.
• You need a moderation operations console — queueing, reviewer workflows, appeals, audit trails. This package is a filter, not a system.
• Latency-critical hot paths at scale. The regex driver acknowledges separator complexity limits for PHP-FPM; results caching is available but adds a cache dependency and cache-invalidation surface.
• You already run a managed moderation pipeline and adding a second, inconsistent source of truth on profanity would create conflicting decisions.

Adoption caveats to validate before committing (a 1-day spike):

• False-positive rate against your actual corpus. Export 5–10k real user strings and run them through all drivers; measure false positives on legitimate words (place names, surnames, medical terms, other languages). The bundled false-positive list won't know your domain.
• False-negative rate on obfuscation. Have the team try to evade it for 30 minutes. Note the documented 3-separator cap (f--u--c--k works; longer separators won't).
• Performance under realistic load. Benchmark regex and pipeline against your p95 payload sizes.
• Maintenance signals. Review the changelog cadence and issue responsiveness honestly — the "last release" metadata looks anomalous, which is itself a reason to verify rather than assume.

How to Pitch It (Stakeholders)

For executives: We can ship baseline content moderation — masking or blocking profanity in comments, usernames, chat, and listings — in days instead of weeks, with no new vendor contract, no per-request cost, no user data leaving our infrastructure, and no new privacy/compliance review. It's MIT-licensed and integrates natively with our Laravel stack, so there's no architectural commitment. It covers English, Spanish, German, and French, and it's configurable enough that Product can tune strictness per surface without engineering work. The honest framing: this is tier-one hygiene, not a trust-and-safety solution — it keeps public surfaces clean and buys us time to evaluate a paid moderation provider for anything safety-critical.

For engineering: This is a well-factored package — driver architecture (regex/pattern/phonetic/pipeline), a fluent PendingCheck builder, a rich Result object, and proper Laravel integration points (middleware alias, validation rules, Blaspable trait, Blade directive, Str/Stringable macros, events, and Blasp::fake() for tests). It's extensible via DriverInterface if we need a domain-specific driver. Two engineering caveats to own: config is broad enough that it warrants a documented internal standard rather than per-team improvisation, and we should keep the boundary thin — wrap it behind our own ModerationService interface so swapping to a vendor later is a one-file change, not a refactor. Also budget a cache driver for results caching in production, and benchmark the regex driver on our largest payloads before rollout. Lowest-risk first landing zone: sanitize mode on a single non-critical surface (e.g., listing descriptions), instrumented with the ProfanityDetected event so we have real false-positive data before widening scope.