danek/clean-speak

PHP profanity filter with leet speak and diacritics detection, customizable dictionaries, and flexible word replacement.

v1.0.0 2025-07-19 22:30 UTC

Requires

• php: >=7.1
• ext-json: *
• ext-mbstring: *

Requires (Dev)

• phpunit/phpunit: ^9

MIT

• Jirka Daněk

• filter
• profanity
• censor
• bad words
• moderation
• diacritics
• leet speak

README

A PHP library for profanity filtering and text censoring with support for leet speak obfuscation and diacritics.

Contents

• Requirements
• Installation
• Usage
• Configuration
  • Word dictionary
  • Blocking Strategies
  • Detection Modes
  • Custom Leet Map
  • Diacritics Handling

Requirements

• PHP 7.1+

Installation

composer require danek/clean-speak

Usage

<?php

use CleanSpeak\CleanSpeak;

$filter = new CleanSpeak();
$filter->setWords(__DIR__ . '/my_dictionary.json'); // set dictionary from array or JSON
$filter->addWords(['badword', 'naughtyword']); // add words to dictionary
$filter->setText("Some b4dw0rd and n@ughtyω0rd text!"); // set text

echo $filter->filter(); // check
// Output: "Some ####### and ########### text!"

if (!$filter->isClean()) {
    echo "Found bad words: " . implode(', ', $filter->getBadWords());
    echo "Filtered: " . $filter->filter();
}

Configuration

Word dictionary

<?php

use CleanSpeak\CleanSpeak;

$filter = new CleanSpeak();

// set/replace dictionary from JSON file
$filter->setWords(__DIR__ . '/my_dictionary.json');

// or set/replace dictionary from PHP array
$filter->setWords(['word1', 'word2']);

// Add to existing dictionary
$filter->addWords(['word3', 'word4']);

Blocking Strategies

<?php

use CleanSpeak\CleanSpeak;

$filter = new CleanSpeak();
$filter->setBlocker('x');

// replacement with random characters
$filter->setBlocker(function ($context) {
    $length = $context['word_length'];
    $letters = 'abcdefghijklmnopqrstuvwxyz?#+-&!$@%*';
    $result = '';
    for ($i = 0; $i < $length; $i++) {
        $result .= $letters[random_int(0, strlen($letters) - 1)];
    }
    return $result;
});

Detection Modes

<?php

use CleanSpeak\CleanSpeak;

$filter = new CleanSpeak();
// Strict mode: Exact word matching only
$filter->setStrictMode(true);

// Non-strict: Detects leet speak obfuscation
$filter->setStrictMode(false);

// Strict replacement: Match original word length
$filter->setStrictClean(true);

Custom Leet Map

<?php

use CleanSpeak\CleanSpeak;

$filter = new CleanSpeak();
$filter->setLeetMap([
    'a' => '(a|4|@|\\*)',
    's' => '(s|5|\\$|\\*)',
    // ... more mappings
]);

// Or modify existing map
$filter->editLeetMap(function($map) {
    $map['e'] = '(e|3|€|\\*)';
    return $map;
});

Diacritics Handling

<?php

use CleanSpeak\CleanSpeak;

$filter = new CleanSpeak();
// Custom diacritics remover
$filter->setDiacriticsRemover(function($text) {
    // use 3rd party library
        return \Vendor\Slugify::content($text);
});