Download the PHP package rumenx/php-chatbot without Composer

php-chatbot

📖 Documentation: Funding

php-chatbot is a modern, framework-agnostic PHP package for integrating an AI-powered chat popup into any web application. It features out-of-the-box support for Laravel and Symfony, a flexible model abstraction for using OpenAI, Anthropic, xAI, Google Gemini, Meta, and more, and is designed for easy customization and extension. Build your own UI or use the provided minimal frontend as a starting point. High test coverage, static analysis, and coding standards are included.

Features

• Plug-and-play chat popup UI (minimal frontend dependencies)
• Laravel & Symfony support via adapters/service providers
• AI model abstraction via contracts (swap models easily)
• Customizable prompts, tone, language, and scope
• Emoji and multi-script support (Cyrillic, Greek, Armenian, Asian, etc.)
• Security safeguards against abuse
• High test coverage (Pest)
• Static analysis (phpstan) & coding standards (phpcs, Symfony style)

📚 Documentation & Wiki

Comprehensive documentation and guides are available in our GitHub Wiki:

🚀 Getting Started

• Installation Guide - Step-by-step installation for all environments
• Quick Start Guide - Get up and running in minutes
• Configuration - Complete configuration reference

🔧 Implementation Guides

• Framework Integration - Laravel, Symfony, and plain PHP setup
• Frontend Integration - React, Vue, Angular components and examples
• AI Models - Provider comparison and configuration

📖 Examples & Best Practices

• Examples - Real-world implementations and use cases
• Best Practices - Production deployment and security guidelines
• Security & Filtering - Content filtering and abuse prevention

🛠️ Development & Support

• API Reference - Complete API documentation
• Troubleshooting - Common issues and solutions
• Contributing - How to contribute to the project
• FAQ - Frequently asked questions

💡 Tip: The wiki contains production-ready examples, troubleshooting guides, and comprehensive API documentation that goes beyond this README.

Supported AI Providers & Models

Installation

Laravel

• Package auto-discovers the service provider.
• Publish config: php artisan vendor:publish --provider="Rumenx\\PhpChatbot\\Adapters\\Laravel\\PhpChatbotServiceProvider"

Symfony

• Register the bundle in your bundles.php.
• Publish config: php bin/console chatbot:publish-config

Usage

1. Add the chat popup to your layout (see /resources/views for examples).
2. Configure your preferred AI model and prompts in the config file (src/Config/phpchatbot.php).
3. Optionally, customize the frontend (CSS/JS) in /resources.

API Keys & Credentials

Never hardcode API keys or secrets in your codebase.

• Use environment variables (e.g. .env file) or your infrastructure's secret management.
• The config file will check for environment variables (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) first.
• See .env.example for reference.

Quick Start

Example .env

API Endpoint Contract

• Endpoint: /php-chatbot/message

• Request:

• Response:

Symfony Backend Example

Testing

Running Tests with Coverage

Static Analysis

Coding Standards

Security

• Input validation and abuse prevention built-in.
• Rate limiting and content filtering available via config.

Rate Limiting & Abuse Prevention

You can implement rate limiting and abuse prevention in your backend. For Laravel, use built-in middleware:

For plain PHP, you can use a simple session or IP-based limiter, or integrate a package like malkusch/lock or Redis.

JavaScript Framework Components

You can use the provided chat popup as a plain HTML/JS snippet, or integrate a modern component for Vue, React, or Angular:

• Vue: resources/js/components/PhpChatbotVue.vue
• React: resources/js/components/PhpChatbotReact.jsx
• Angular: resources/js/components/PhpChatbotAngular.html (with TypeScript logic)

JS Component Usage

1. Copy the component into your app's source tree.
2. Import and register it in your app (see your framework's docs).
3. Customize the backend endpoint (/php-chatbot/message) as needed.
4. Build your assets (e.g. with Vite, Webpack, or your framework's CLI).

Example (Vue)

Example (React)

Example (Angular)

• Copy the HTML, TypeScript, and CSS into your Angular component files.
• Register and use <php-chatbot-angular></php-chatbot-angular> in your template.

JS Component Customization

• You can style or extend the components as needed.
• You may add your own framework component in a similar way.
• The backend endpoint is framework-agnostic; you can point it to any PHP route/controller.

TypeScript Example (React)

A modern TypeScript React chatbot component is provided as an example in resources/js/components/PhpChatbotTs.tsx.

How to use:

1. Copy PhpChatbotTs.tsx into your React app's components folder.

2. Import and use it in your app:

3. Make sure your backend endpoint /php-chatbot/message is set up as described above.
4. Style as needed (the component uses inline styles for demo purposes, but you can use your own CSS/SCSS).

This component is a minimal, framework-agnostic starting point. You are encouraged to extend or restyle it to fit your app.

Backend Integration Example

To handle chat requests, add a route/controller in your backend (Laravel, Symfony, or plain PHP) that receives POST requests at /php-chatbot/message and returns a JSON response. Example for Laravel:

For plain PHP, use:

Frontend Styles (SCSS)

The chat popup styles are written in modern SCSS for maintainability. You can find the source in resources/css/chatbot.scss.

To compile SCSS to CSS:

1. Install Sass (if you haven't already):

2. Add this script to your package.json:

3. Compile SCSS:

Or use the Sass CLI directly:

To watch for changes automatically:

Only commit the compiled chatbot.css for production/deployment. For more options, see Sass documentation.

Customizing Frontend Styles & Views (Best Practice)

The provided CSS/SCSS and view files (resources/css/, resources/views/) are optional and basic. They are meant as a starting point for your own implementation. You are encouraged to build your own UI and styles on top of or instead of these defaults.

Do not edit files directly in the vendor/ folder or inside the package source.

How to Safely Override Views and Styles

• Copy the provided view files (e.g. resources/views/popup.blade.php or popup.php) into your own application's views directory. Update your app to use your custom view.
• Copy and modify the SCSS/CSS (resources/css/chatbot.scss or chatbot.css) into your own asset pipeline. Import, extend, or replace as needed.

• For Laravel/Symfony:

  • Publish the package views/config (see the Installation section above) and edit the published files in your app, not in vendor/.

  • Example (Laravel):

  • Example (Symfony):
• For plain PHP: Copy the view and style files to your public or template directory and reference them in your HTML.

Important: If you edit files directly in vendor/rumenx/php-chatbot/, your changes will be lost on the next composer update. Always override or extend in your own app.

Principle

• Treat the package's frontend as a reference implementation.
• Override or extend in your own codebase for all customizations.
• Never edit vendor files directly.

Configuration Best Practices

Never edit files in the vendor/ directory.

• For Laravel: Publish the config file to your app's config/ directory using:

  Then edit config/phpchatbot.php in your app. This file will not be overwritten by package updates.

• For Symfony: Use the provided command to publish config to your app's config directory, then edit as needed.

• For plain PHP or other frameworks: Use an environment variable to point to your own config file.

  1. Copy src/Config/phpchatbot.php to a safe location in your project (e.g., config/phpchatbot.php).

  2. Set the environment variable in your .env or server config:

  3. In your bootstrap or controller, load config like this:
• Always use environment variables for secrets and API keys.
• Never edit or commit changes to files in vendor/.
• Document your custom config location for your team.

Example usage in a plain PHP project:

This approach ensures your configuration is safe from being overwritten during package updates and is easy to manage in any deployment environment.

Best Practices

• Never edit files in vendor/
• Always copy views/styles to your own app before customizing
• Use environment variables for secrets
• Use the provided JS/TS components as a starting point, not as production code
• Keep your customizations outside the package directory for upgrade safety

What's Included

Chat Message Filtering Middleware

The package includes a configurable chat message filtering middleware to help ensure safe, appropriate, and guideline-aligned AI responses. This middleware:

• Filters and optionally rephrases user-submitted messages before they reach the AI model.
• Appends hidden system instructions (not visible in chat history) to the AI context, enforcing safety and communication guidelines.
• All filtering rules (profanities, aggression patterns, link regex) and system instructions are fully configurable in src/Config/phpchatbot.php.

Example configuration:

Example usage in your controller or chat service:

Purpose:

• Promotes safe, respectful, and effective communication.
• Prevents misuse, abuse, and unsafe outputs.
• All rules are transparent and configurable—no hidden censorship or manipulation.

Questions & Support

For questions, issues, or feature requests, please use the GitHub Issues page.

For security vulnerabilities, please see our Security Policy.

Contributing

See CONTRIBUTING.md for guidelines on how to contribute.

Code of Conduct

This project adheres to a Code of Conduct to ensure a welcoming and inclusive environment for all contributors. See CODE_OF_CONDUCT.md for details.

Support the Project

If you find this project helpful, consider supporting its development. See FUNDING.md for ways to contribute.

Changelog

See CHANGELOG.md for a detailed history of changes and releases.

License

MIT. See LICENSE.md.