PHPackages                             diego-ninja/banthis - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. diego-ninja/banthis

ActiveLibrary[Utility & Helpers](/categories/utility)

diego-ninja/banthis
===================

A censor and word filtering library for PHP 8.2+

v1.1.1(1y ago)0212[1 PRs](https://github.com/diego-ninja/banthis/pulls)AGPL-3.0PHPPHP ^8.2CI passing

Since Oct 23Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/diego-ninja/banthis)[ Packagist](https://packagist.org/packages/diego-ninja/banthis)[ Docs](https://github.com/diego-ninja/banthis)[ Fund](https://paypal.me/diegorin)[ Fund](https://ko-fi.com/diegoninja)[ RSS](/packages/diego-ninja-banthis/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (5)Used By (0)

BanThis - A censor and word filtering library for PHP 8.2+
==========================================================

[](#banthis---a-censor-and-word-filtering-library-for-php-82)

[![Latest Version on Packagist](https://camo.githubusercontent.com/9636908913c18bf881f283e6cfff9e5428c90eca5bd67a420983e855fa1b1d11/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f646965676f2d6e696e6a612f62616e746869732e7376673f7374796c653d666c617426636f6c6f723d626c7565)](https://packagist.org/packages/diego-ninja/banthis)[![Total Downloads](https://camo.githubusercontent.com/2f6cf8ffadad795207b2afbf50a9e99d70011e597646500fd499165f094866de/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f646965676f2d6e696e6a612f62616e746869732e7376673f7374796c653d666c617426636f6c6f723d626c7565)](https://packagist.org/packages/diego-ninja/banthis)[![PHP Version](https://camo.githubusercontent.com/9db78987a7d05d3147802071748b905429ca68f2bc9f41f69da247b24c722d86/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f646965676f2d6e696e6a612f636f736d69632e7376673f7374796c653d666c617426636f6c6f723d626c7565)](https://camo.githubusercontent.com/9db78987a7d05d3147802071748b905429ca68f2bc9f41f69da247b24c722d86/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f646965676f2d6e696e6a612f636f736d69632e7376673f7374796c653d666c617426636f6c6f723d626c7565)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](https://opensource.org/licenses/MIT)[![GitHub last commit](https://camo.githubusercontent.com/7ba39fb5294e14518b9a0f593d9a9ae845e907ee0f27367b2bb249dd7d5674b4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f646965676f2d6e696e6a612f62616e746869733f636f6c6f723d626c7565)](https://camo.githubusercontent.com/7ba39fb5294e14518b9a0f593d9a9ae845e907ee0f27367b2bb249dd7d5674b4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f646965676f2d6e696e6a612f62616e746869733f636f6c6f723d626c7565)[![Hits-of-Code](https://camo.githubusercontent.com/0c379ba44cccdfe01a3fc28c3f70a46c0988a7e0a69ce4ea5393c8053db1bc07/68747470733a2f2f686974736f66636f64652e636f6d2f6769746875622f646965676f2d6e696e6a612f62616e746869733f6272616e63683d6d61696e266c6162656c3d686974732d6f662d636f6465)](https://hitsofcode.com/github/diego-ninja/banthis/view?branch=main&label=hits-of-code)[![wakatime](https://camo.githubusercontent.com/3d247b4bb312679aed74bcadf9f2b5010e1b1f07828485703111179b70c3bd88/68747470733a2f2f77616b6174696d652e636f6d2f62616467652f757365722f62643635663035352d633966332d346637332d393261612d3363393831306637306363332f70726f6a6563742f30326262626365622d343766392d343832642d626530622d6331653237373765623436332e737667)](https://wakatime.com/badge/user/bd65f055-c9f3-4f73-92aa-3c9810f70cc3/project/02bbbceb-47f9-482d-be0b-c1e2777eb463)

BanThis is a PHP package for profanity filtering. The PHP script uses regex to intelligently look for "leetspeak"-style numeric or symbol replacements.

This package is an evolution of [snipe/banbuilder](https://github.com/snipe/banbuilder) adapted and refactored to modern php versions.

📦 Installation
--------------

[](#-installation)

To install BanThis, simply include it in your projects's `composer.json`.

```
"diego-ninja/banthis": "^1",

```

There are no additional dependencies required for this package to work.

🚀 Usage
-------

[](#-usage)

```
use Ninja\BanThis\Censor;
use Ninja\BanThis\Dictionary;

$dictionary = Dictionary::withLanguage('en-us');

$censor = new Censor($dictionary);
$string = $censor->clean('A very offensive string with the bad word dick on it');
print_r($string)

Array
(
    [orig] => A very offensive string with the bad word dick on it
    [clean] => A very offensive string with the bad word **** on it
    [matched] => Array
        (
            [0] => dick
        )

)
```

### Setting the Dictionary

[](#setting-the-dictionary)

You can set or add dictionaries to the Censor instance.

```
// Set a new dictionary
$censor->setDictionary($dictionary);

// Add words from another dictionary
$additionalDictionary = Dictionary::withLanguage('fr');
$censor->addDictionary($additionalDictionary);
```

### Adding words from an array

[](#adding-words-from-an-array)

You can add words directly from an array.

```
$words = ['badword1', 'badword2'];
$censor->addWords($words);
```

### Managing the whitelist

[](#managing-the-whitelist)

You can add words to the whitelist to exclude them from being censored.

```
$whitelist = ['goodword1', 'goodword2'];
$censor->whitelist($whitelist);
```

### Setting the replacement character

[](#setting-the-replacement-character)

You can set the character or string that will replace the censored words.

```
$censor->setReplaceChar('*');
```

⚙️ How it works
---------------

[](#️-how-it-works)

In a nutshell, this code takes an array of bad words and compares it to an array of common filter-evasion tactics. It then does a string replacement to insert regex parameters into your badwords array, and then evaluates your input string to that expanded banned word list.

So in your bad words array, you might have:

```
 [0] => 'ass'

```

The `preg_replace` functions replace all of the possible shenanigan letters with regex patterns (in lieu of adding the variants onto the end of the array), so the 'ass' in your array gets turned into this, right before the `preg_replace` checks for matches:

```
 [0] => /(a|a\.|a\-|4|@|Á|á|À|Â|à|Â|â|Ä|ä|Ã|ã|Å|å|α)(s|s\.|s\-|5|\$|§)(s|s\.|s\-|5|\$|§)/i

```

This means that a word can have none, one or any variety of leet replacements and it will still trip the trigger. Part of the leet filter includes stripping out letter-dash and letter-dots.

This means that the following all evaluate to the "bitch":

- B1tch
- bi7tch
- b.i.t.c.h.
- b-i-t-c-h
- b.1.t.c.h.
- ßitch
- and so on....

🔬 Tests
-------

[](#-tests)

To run the unit tests on this package, run `vendor/bin/phpunit` from the package directory.

🙏 Credits
---------

[](#-credits)

This project is developed and maintained by 🥷 [Diego Rin](https://diego.ninja) in his free time.

Special thanks to:

- [snipe](https://github.com/snipe) for developing the [inital code](https://github.com/snipe/banbuilder) that serves BanThis as starting point.
- All the contributors and testers who have helped to improve this project through their contributions.

If you find this project useful, please consider giving it a ⭐ on GitHub!

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance67

Regular maintenance activity

Popularity11

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 60% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~40 days

Total

2

Last Release

532d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/dff5b0a76de3d555cb236c400384058ba23982bce2e859cc1b2f0c1f0161a3e6?d=identicon)[diego.ninja](/maintainers/diego.ninja)

---

Top Contributors

[![diego-ninja](https://avatars.githubusercontent.com/u/78662279?v=4)](https://github.com/diego-ninja "diego-ninja (9 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)")

---

Tags

languagestringsfilterprofanityswear

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/diego-ninja-banthis/health.svg)

```
[![Health](https://phpackages.com/badges/diego-ninja-banthis/health.svg)](https://phpackages.com/packages/diego-ninja-banthis)
```

###  Alternatives

[snipe/banbuilder

Library to easily handle profanity filtering in PHP projects.

3371.5M3](/packages/snipe-banbuilder)[doctrine/inflector

PHP Doctrine Inflector is a small library that can perform string manipulations with regard to upper/lowercase and singular/plural forms of words.

11.4k855.8M711](/packages/doctrine-inflector)[phpoption/phpoption

Option Type for PHP

2.7k541.2M159](/packages/phpoption-phpoption)[diego-ninja/sentinel

A content moderation and sentiment analysis library for Laravel 10+

384.3k](/packages/diego-ninja-sentinel)[patrickschur/language-detection

A language detection library for PHP. Detects the language from a given text string.

8513.2M18](/packages/patrickschur-language-detection)[landrok/language-detector

A fast and reliable PHP library for detecting languages

132647.0k3](/packages/landrok-language-detector)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)