PHPackages                             mohammed-abd-razaq/laravel-toxicity-filter - 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. mohammed-abd-razaq/laravel-toxicity-filter

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

mohammed-abd-razaq/laravel-toxicity-filter
==========================================

A lightweight Laravel library that wraps AI-based toxicity detection engines to evaluate and moderate user-generated content within your application.

1.1.1(10mo ago)02MITPHPPHP ^8.0

Since Aug 9Pushed 10mo agoCompare

[ Source](https://github.com/MOHAMMED-ABD-RAZAQ/laravel-toxicity-filter)[ Packagist](https://packagist.org/packages/mohammed-abd-razaq/laravel-toxicity-filter)[ RSS](/packages/mohammed-abd-razaq-laravel-toxicity-filter/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (7)Versions (4)Used By (0)

Laravel AI Toxicity Filter Package
==================================

[](#laravel-ai-toxicity-filter-package)

[![Latest Version](https://camo.githubusercontent.com/34e695c6016bc2a934a96bed696e29b2f2ab562a7134d65a55d00653cd506bea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e302d626c75652e737667)](https://github.com/mohammed-abd-razaq/laravel-toxicity-filter)[![PHP Version](https://camo.githubusercontent.com/d994d75c13a9cd84975ec22cd83d2a7eba90d1de6a997599a566b9be8354d28b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e302d627269676874677265656e2e737667)](https://php.net)[![Laravel Version](https://camo.githubusercontent.com/0a499ba4ed472c682d8fc5f7e6b7b1b57fca489f73da770891d4c55b2cf3a0d6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d253545392e3025374325354531302e3025374325354531312e3025374325354531322e302d7265642e737667)](https://laravel.com)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](https://opensource.org/licenses/MIT)

A professional Laravel library that integrates AI-based toxicity detection engines to automatically evaluate, moderate, and filter user-generated content such as comments, posts, messages, and reviews within your application.

Features
--------

[](#features)

- 🤖 **Multiple AI Providers**: Support for OpenAI Moderation API, Google Perspective API, and extensible for more
- ⚡ **Laravel Integration**: Seamless integration with Laravel facades, service providers, and middleware
- 🛡️ **Automatic Filtering**: Middleware for automatic content moderation on routes
- 🎛️ **Configurable Thresholds**: Customizable toxicity thresholds for blocking, flagging, and warning
- 📊 **Detailed Analytics**: Comprehensive logging and database storage of toxicity detection results
- 🚀 **Queue Support**: Async processing for bulk or large content moderation
- 💾 **Caching**: Redis/database caching to reduce API calls and improve performance
- 🔧 **Extensible**: Easy to add new AI providers through clean interfaces
- 🔒 **Privacy First**: Content hashing for privacy protection
- 📈 **Performance Optimized**: Built-in rate limiting and content optimization
- 🛠️ **Developer Friendly**: Rich testing utilities and comprehensive error handling
- 🌐 **Multi-language Support**: Native support for Arabic and English content with automatic language detection

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- Laravel 9.0, 10.0, 11.0, or 12.0
- OpenAI API key (for OpenAI provider)
- Google Perspective API key (for Perspective provider)

Installation
------------

[](#installation)

1. Install via Composer:

```
composer require mohammed-abd-razaq/laravel-toxicity-filter
```

Or if using the local package, update your root `composer.json`:

```
{
    "require": {
        "packages/toxicity-filter": "^1.0"
    }
}
```

2. Run composer update:

```
composer update
```

3. Publish the configuration file:

```
php artisan vendor:publish --tag=toxicity-filter-config
```

4. Publish and run migrations:

```
php artisan vendor:publish --tag=toxicity-filter-migrations
php artisan migrate
```

5. Clear configuration cache:

```
php artisan config:clear
```

Configuration
-------------

[](#configuration)

Set up your AI provider API keys in `.env`:

```
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODERATION_MODEL=text-moderation-latest

# Google Perspective API Configuration
PERSPECTIVE_API_KEY=your_perspective_api_key

# Toxicity Thresholds (0.0 - 1.0)
TOXICITY_BLOCK_THRESHOLD=0.8
TOXICITY_FLAG_THRESHOLD=0.6
TOXICITY_WARN_THRESHOLD=0.4

# Language-Specific Thresholds
TOXICITY_ARABIC_BLOCK_THRESHOLD=0.8
TOXICITY_ARABIC_FLAG_THRESHOLD=0.6
TOXICITY_ARABIC_WARN_THRESHOLD=0.4
TOXICITY_ENGLISH_BLOCK_THRESHOLD=0.8
TOXICITY_ENGLISH_FLAG_THRESHOLD=0.6
TOXICITY_ENGLISH_WARN_THRESHOLD=0.4

# Caching
TOXICITY_CACHE_ENABLED=true
TOXICITY_CACHE_TTL=3600

# Logging
TOXICITY_LOGGING_ENABLED=true
TOXICITY_STORE_CONTENT=false
```

Usage
-----

[](#usage)

### Basic Usage with Facade

[](#basic-usage-with-facade)

```
use Packages\ToxicityFilter\Facades\ToxicityFilter;

// Analyze English content
$result = ToxicityFilter::analyze("This is some content to check");

echo $result->getToxicityScore(); // 0.85
echo $result->getProvider(); // 'openai'
var_dump($result->getCategories()); // ['harassment', 'hate']

// Analyze Arabic content (automatic language detection)
$arabicResult = ToxicityFilter::analyze("مرحبا بالعالم");

// Analyze multilingual content
$multilingualResult = ToxicityFilter::analyze("Hello مرحبا world");

// Quick checks (uses language-specific thresholds)
if (ToxicityFilter::shouldBlock($content)) {
    // Block the content
}

if (ToxicityFilter::shouldFlag($content)) {
    // Flag for manual review
}

if (ToxicityFilter::shouldWarn($content)) {
    // Show warning to user
}
```

### Using Specific Providers

[](#using-specific-providers)

```
// Use OpenAI specifically
$result = ToxicityFilter::analyze($content, 'openai');

// Use Perspective API specifically
$result = ToxicityFilter::analyze($content, 'perspective');

// Get available providers
$providers = ToxicityFilter::getAvailableProviders();
```

### Optional Middleware Usage

[](#optional-middleware-usage)

The package includes optional middleware for automatic content filtering. To use it, you need to manually register it first.

#### Register the Middleware

[](#register-the-middleware)

Add to your `app/Http/Kernel.php`:

```
// In app/Http/Kernel.php

protected $routeMiddleware = [
    // ... other middleware
    'toxicity-filter' => \Packages\ToxicityFilter\Middleware\ToxicityFilterMiddleware::class,
];
```

#### Apply to Routes

[](#apply-to-routes)

```
// In your routes file
Route::post('/comments', [CommentController::class, 'store'])
    ->middleware('toxicity-filter');

// Or specify fields to check
Route::post('/posts', [PostController::class, 'store'])
    ->middleware('toxicity-filter:title,content,description');
```

The middleware will:

- Automatically block toxic content (returns 422 error)
- Flag moderately toxic content for review
- Add warnings to the request for mildly toxic content
- Log all detections to the database

### Advanced Usage

[](#advanced-usage)

```
use Packages\ToxicityFilter\Contracts\ToxicityFilterInterface;

class ContentModerationService
{
    public function __construct(
        private ToxicityFilterInterface $toxicityFilter
    ) {}

    public function moderateComment(string $content, User $user): array
    {
        $result = $this->toxicityFilter->analyze($content);

        $response = [
            'allowed' => true,
            'message' => null,
            'requires_review' => false,
        ];

        if ($result->shouldBlock(0.8)) {
            $response['allowed'] = false;
            $response['message'] = 'Content blocked due to inappropriate language';
        } elseif ($result->shouldFlag(0.6)) {
            $response['requires_review'] = true;
            $response['message'] = 'Content flagged for review';
        }

        return $response;
    }
}
```

### Arabic Language Support

[](#arabic-language-support)

The package includes native support for Arabic content with automatic language detection and text normalization:

#### Automatic Language Detection

[](#automatic-language-detection)

```
// Arabic content is automatically detected
$arabicContent = "مرحبا بالعالم";
$result = ToxicityFilter::analyze($arabicContent);
// Language is automatically detected as 'ar'

// Multilingual content is supported
$mixedContent = "Hello مرحبا world";
$result = ToxicityFilter::analyze($mixedContent);
// Primary language is determined based on character count
```

#### Arabic Text Normalization

[](#arabic-text-normalization)

The package automatically normalizes Arabic text for better analysis:

- **Character Normalization**: Converts different forms of Arabic characters (أ, إ, آ → ا)
- **Diacritics Removal**: Removes tashkeel (diacritics) for better matching
- **Hamza Handling**: Normalizes hamza variations

```
// Raw Arabic text with diacritics
$rawArabic = "مَرْحَباً بِالعَالَمِ";

// Package automatically normalizes for analysis
$result = ToxicityFilter::analyze($rawArabic);
```

#### Language-Specific Thresholds

[](#language-specific-thresholds)

Configure different toxicity thresholds for Arabic and English content:

```
// In config/toxicity-filter.php
'languages' => [
    'thresholds' => [
        'ar' => [
            'block' => 0.8,  // Arabic blocking threshold
            'flag' => 0.6,   // Arabic flagging threshold
            'warn' => 0.4,   // Arabic warning threshold
        ],
        'en' => [
            'block' => 0.8,  // English blocking threshold
            'flag' => 0.6,   // English flagging threshold
            'warn' => 0.4,   // English warning threshold
        ],
    ],
],
```

#### Manual Language Detection

[](#manual-language-detection)

You can also use the language detection service directly:

```
use Packages\ToxicityFilter\Services\LanguageDetectionService;

$detector = new LanguageDetectionService();

$language = $detector->detectLanguage("مرحبا بالعالم"); // 'ar'
$isArabic = $detector->isArabic("مرحبا"); // true
$isMultilingual = $detector->isMultilingual("Hello مرحبا"); // true
$normalized = $detector->normalizeArabicText("مَرْحَباً"); // "مرحبا"
```

### Queue Processing

[](#queue-processing)

For async processing, you can dispatch jobs:

```
use Packages\ToxicityFilter\Jobs\AnalyzeToxicityJob;

// Process large content asynchronously
AnalyzeToxicityJob::dispatch($content, $userId, $options);
```

Supported AI Providers
----------------------

[](#supported-ai-providers)

### OpenAI Moderation API

[](#openai-moderation-api)

- **Pros**: High accuracy, fast response, multiple toxicity categories
- **Cons**: Requires API key, has usage costs
- **Content Limit**: ~32,000 characters

### Google Perspective API

[](#google-perspective-api)

- **Pros**: Free tier available, detailed attribute scoring
- **Cons**: Limited free quota, requires Google Cloud setup
- **Content Limit**: 3,000 characters

Configuration Options
---------------------

[](#configuration-options)

The package offers extensive configuration options:

- **Providers**: Configure multiple AI providers with failover
- **Thresholds**: Set different toxicity thresholds for various actions
- **Caching**: Cache results to reduce API calls and costs
- **Logging**: Comprehensive logging with configurable storage
- **Queue**: Async processing for better performance
- **Bypass Rules**: Skip filtering for trusted users or content

Database Schema
---------------

[](#database-schema)

The package creates a `toxicity_detections` table to log all analysis results:

```
- id (primary key)
- provider (string, indexed)
- toxicity_score (decimal, indexed)
- categories (json)
- content_hash (text, indexed)
- content (text, optional)
- metadata (json)
- action_taken (string, indexed)
- user_id (bigint, nullable, indexed)
- ip_address, user_agent, request_path
- timestamps
```

Extending the Package
---------------------

[](#extending-the-package)

### Adding New AI Providers

[](#adding-new-ai-providers)

Implement the `ToxicityProviderInterface`:

```
use Packages\ToxicityFilter\Contracts\ToxicityProviderInterface;
use Packages\ToxicityFilter\ValueObjects\ToxicityResult;

class CustomProvider implements ToxicityProviderInterface
{
    public function analyze(string $content, array $options = []): ToxicityResult
    {
        // Implement your provider logic
    }

    public function getName(): string
    {
        return 'custom';
    }

    // ... implement other interface methods
}
```

Testing
-------

[](#testing)

```
# Run package tests
cd packages/toxicity-filter
composer test

# Run with coverage
composer test-coverage

# Run specific test file
vendor/bin/phpunit tests/Unit/ToxicityFilterServiceTest.php

# Run tests with debug output
vendor/bin/phpunit --debug
```

### Test Configuration

[](#test-configuration)

Create a `.env.testing` file for test environment:

```
TOXICITY_CACHE_ENABLED=false
TOXICITY_LOGGING_ENABLED=false
OPENAI_API_KEY=test_key
PERSPECTIVE_API_KEY=test_key
```

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues

[](#common-issues)

**1. Configuration not loaded**

```
php artisan config:clear
php artisan config:cache
```

**2. Provider API errors**

- Verify API keys are correctly set in `.env`
- Check API rate limits and quotas
- Ensure network connectivity to provider endpoints

**3. Migration issues**

```
php artisan migrate:rollback
php artisan vendor:publish --tag=toxicity-filter-migrations --force
php artisan migrate
```

**4. Cache issues**

```
php artisan cache:clear
php artisan config:clear
```

### Debug Mode

[](#debug-mode)

Enable debug logging in your configuration:

```
'debug' => env('TOXICITY_DEBUG', false),
'log_level' => env('TOXICITY_LOG_LEVEL', 'info'),
```

Performance Considerations
--------------------------

[](#performance-considerations)

- **Caching**: Enable caching to reduce API calls for duplicate content
- **Queue**: Use async processing for bulk content or non-blocking operations
- **Rate Limiting**: Configure rate limits to stay within API quotas
- **Content Optimization**: Pre-filter very short content or obvious spam

Security & Privacy
----------------------

[](#security--privacy)

- **Content Hashing**: Store MD5 hashes instead of actual content for privacy
- **API Key Management**: Store API keys securely in environment variables
- **User Bypass**: Allow trusted users to bypass filtering when appropriate
- **Audit Trail**: Comprehensive logging for compliance and debugging

Changelog
---------

[](#changelog)

### Version 1.1.0

[](#version-110)

**Arabic Language Support**

- ✅ Native Arabic language detection and support
- ✅ Automatic Arabic text normalization (character and diacritics)
- ✅ Language-specific toxicity thresholds
- ✅ Multilingual content support
- ✅ Arabic language detection service
- ✅ Enhanced provider support for Arabic content

### Version 1.0.0

[](#version-100)

**Initial Release**

- ✅ OpenAI Moderation API integration
- ✅ Google Perspective API integration
- ✅ Laravel facade and service provider
- ✅ Configurable toxicity thresholds
- ✅ Middleware for automatic filtering
- ✅ Database logging and analytics
- ✅ Caching support
- ✅ Queue processing
- ✅ Extensible provider system
- ✅ Comprehensive test suite

Contributing
------------

[](#contributing)

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

[](#development-setup)

1. Clone the repository
2. Install dependencies: `composer install`
3. Copy `.env.example` to `.env` and configure
4. Run tests: `composer test`

Support
-------

[](#support)

- 📧 **Email**:
- 🐛 **Issues**: [GitHub Issues](https://github.com/mohammed-abd-razaq/laravel-toxicity-filter/issues)
- 📖 **Documentation**: [GitHub Repository](https://github.com/mohammed-abd-razaq/laravel-toxicity-filter)

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT License](https://opensource.org/licenses/MIT).

Author
------

[](#author)

**Mohammed Abd Razaq**

- GitHub: [@mohammed-abd-razaq](https://github.com/mohammed-abd-razaq)
- Email:

---

⭐ If you find this package helpful, please consider giving it a star on GitHub!

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance53

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~1 days

Total

3

Last Release

328d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/29556066?v=4)[Mohammed Abd Alrazaq](/maintainers/MOHAMMED-ABD-RAZAQ)[@MOHAMMED-ABD-RAZAQ](https://github.com/MOHAMMED-ABD-RAZAQ)

---

Top Contributors

[![MOHAMMED-ABD-RAZAQ](https://avatars.githubusercontent.com/u/29556066?v=4)](https://github.com/MOHAMMED-ABD-RAZAQ "MOHAMMED-ABD-RAZAQ (7 commits)")

---

Tags

laravelaiopenaimachine learningmoderationsafetyperspective-apitoxicitycontent-filter

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mohammed-abd-razaq-laravel-toxicity-filter/health.svg)

```
[![Health](https://phpackages.com/badges/mohammed-abd-razaq-laravel-toxicity-filter/health.svg)](https://phpackages.com/packages/mohammed-abd-razaq-laravel-toxicity-filter)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[api-platform/laravel

API Platform support for Laravel

58171.6k14](/packages/api-platform-laravel)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.0k](/packages/simplestats-io-laravel-client)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.4k](/packages/tomshaw-electricgrid)

PHPackages © 2026

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