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)0228[1 PRs](https://github.com/diego-ninja/banthis/pulls)AGPL-3.0PHPPHP ^8.2CI passing

Since Oct 23Pushed 2mo 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 today

READMEChangelog (2)Dependencies (4)Versions (6)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 83% of packages

Maintenance64

Regular maintenance activity

Popularity13

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity56

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

578d 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.

3291.6M3](/packages/snipe-banbuilder)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k38](/packages/neuron-core-neuron-ai)[diego-ninja/sentinel

A content moderation and sentiment analysis library for Laravel 10+

394.8k](/packages/diego-ninja-sentinel)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)

PHPackages © 2026

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