gacbaluyot/profanity-filter

A lightweight, multilingual profanity detection and censorship library written in native PHP

dev-main / 1.0.x-dev 2025-07-28 17:42 UTC

Requires

• php: >=8.0

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Gerard Angelo Baluyot

README

A lightweight, multilingual profanity detection and censorship library written in native PHP.

Supports dynamic language loading, custom word lists, and Unicode-safe pattern matching.

🚀 Features

• Detects profanity in text using prebuilt JSON wordlists
• Supports multiple languages:
  • English (en)
  • Russian (ru)
  • Italian (it)
  • Indonesian (id)
  • Chinese (zh)
  • Japanese (ja)
• Add or override custom bad words
• Merge multiple language filters or use all at once
• Extract, censor, or save profane words
• PHPUnit test suite included

📦 Installation

Clone the repo and include via Composer:

composer install

Make sure your autoloader can resolve ProfanityFilter\ProfanityFilter from /src.

📂 Usage

Basic Detection

use ProfanityFilter\ProfanityFilter;

$filter = new ProfanityFilter('en');

$text = "You idiot!";

if ($filter->containsProfanity($text)) {
    echo "Profanity detected!";
}

Censor Words

$censored = $filter->censor("You dumb bastard!");
echo $censored; // You **** *******!

Get Detected Words

$words = $filter->getProfaneWords("That was stupid and shitty.");
print_r($words); // ['stupid', 'shitty']

Use Multiple Languages

$filter->setLanguages(['en', 'ru']);

Use All Languages

$filter->useAllLanguages();

Add Custom Words

$filter->addCustomWords(['meanie', 'dummy']);

Save & Load Custom Word List

$filter->saveUpdatedWordList(__DIR__ . '/my-words.json');
$filter->setWordListFromFile(__DIR__ . '/my-words.json');

🧪 Running Tests

vendor/bin/phpunit tests/

Make sure you’ve run:

composer dump-autoload

to register autoload-dev.

📁 Language Wordlist Files

Each language is stored in a separate JSON file in src/data/, e.g.:

src/data/en.json
src/data/ru.json
src/data/zh.json

You can extend these manually or via the library methods.

📝 License

MIT Licensed. Use at your own discretion — offensive content warning applies.

🙌 Contributions Welcome!

Feel free to fork, submit PRs, or suggest new languages and improvements!