Download the PHP package freema/perspective-api-bundle without Composer

Perspective API Bundle for Symfony

[!WARNING] Archived, no longer maintained. Google Jigsaw shuts down the Perspective API on December 31, 2026 (perspectiveapi.com), and this bundle stops working with it. No new versions will be released. Plan a move to another moderation service before then.

A powerful Symfony bundle that integrates Google's Perspective API for content moderation and toxicity detection in your applications. Built with flexibility in mind, it supports multiple threshold management strategies, caching, and can be used as a standalone service or Symfony validator.

🎯 Key Features

• 🔧 Flexible Threshold Management - Static config, database-driven, or runtime dynamic thresholds
• 💾 Built-in Caching Support - Reduce API calls and improve performance
• 🎨 Multiple Usage Patterns - Use as a service, validator constraint, or command-line tool
• 🌍 Multi-language Support - Analyze content in multiple languages with automatic detection
• 📊 Rich Analysis Results - Detailed scoring across multiple toxicity dimensions
• ⚡ Production Ready - Battle-tested with proper error handling and logging
• 🔄 Easy Migration - Simple migration path from deprecated libraries like bredmor/comment-analyzer

🚀 Why This Bundle?

This bundle was created as a modern, maintained alternative to abandoned Perspective API wrappers. It provides a clean, Symfony-native integration that follows best practices and offers the flexibility needed for real-world applications.

Unlike simple API wrappers, this bundle understands that different parts of your application might need different moderation thresholds - a children's section needs stricter controls than a general discussion forum. It allows you to implement context-aware content moderation without sacrificing simplicity.

⚠️ Important Note About Google's Gemini LLM Integration

Google has integrated their Gemini LLM into the Perspective API, which represents a shift from traditional deterministic models to AI-powered analysis. While the API remains fully functional and is actively supported by Google, please be aware that:

• Consistency: The same text might receive slightly different scores when analyzed at different times
• Predictability: Results may be less deterministic compared to traditional machine learning models
• Recommendation: Consider implementing caching to ensure consistent moderation decisions for the same content

This change reflects Google's commitment to improving the API with cutting-edge AI technology, but it's important to understand these characteristics when implementing content moderation.

📋 Requirements

• PHP 8.1 or higher
• Symfony 5.4, 6.x, or 7.x
• Google Perspective API key (Get one here)

🔧 Advanced Configuration

HTTP Client Options

The bundle supports custom HTTP client configuration for environments that require proxy servers or specific timeouts:

This is particularly useful for:

• Corporate environments with proxy requirements
• Applications with specific network configurations
• Custom timeout requirements for slow networks
• Adding custom headers for monitoring or tracking

🛠️ Use Cases

This bundle is perfect for:

• Comment Systems - Automatically moderate user comments before publication
• Forums & Communities - Maintain healthy discussion environments
• Social Platforms - Filter toxic content in real-time
• Content Management - Review and flag potentially problematic content
• Customer Support - Filter inappropriate messages in support tickets
• Educational Platforms - Ensure safe learning environments

📦 Installation

Install the bundle using Composer:

⚙️ Configuration

Basic Configuration

Environment Variables

📖 Usage

Basic Service Usage

Using as a Validator

Using in Symfony Forms

The bundle provides a PerspectiveTextType for easy integration into Symfony forms:

Form Type Options

• perspective_validation (bool, default: true) - Enable/disable Perspective validation
• perspective_thresholds (array, default: []) - Custom thresholds for validation
• perspective_language (string|null, default: null) - Language for analysis
• perspective_message (string|null, default: null) - Custom validation error message

Custom Threshold Provider

Implement dynamic thresholds based on context:

Using Threshold Resolver

Batch Analysis

Analyzing with Specific Attributes

🧪 Development

For development setup, testing, and contribution guidelines, see:

• DEVELOP.md - Development environment setup and testing
• CONTRIBUTING.md - Contribution guidelines

🔄 Migration from bredmor/comment-analyzer

If you're migrating from the deprecated bredmor/comment-analyzer library:

📊 Available Attributes

• TOXICITY - A rude, disrespectful, or unreasonable comment
• SEVERE_TOXICITY - A very hateful, aggressive, disrespectful comment
• IDENTITY_ATTACK - Negative or hateful comments targeting identity
• INSULT - Insulting, inflammatory, or negative comment
• PROFANITY - Swear words, curse words, or profane language
• THREAT - Describes an intention to inflict pain or violence

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This bundle is released under the MIT License. See the bundled LICENSE file for details.

🙏 Credits

• Created and maintained by Freema
• Inspired by the need for a modern, maintained Perspective API integration
• Thanks to all contributors

📚 Resources

• Google Perspective API Documentation
• Symfony Documentation
• Bundle Issues & Support