r94ever / phpai
A simple AI package for PHP
Requires
- laravel/framework: ^12.0
Requires (Dev)
- orchestra/testbench: ^10.0
- phpunit/phpunit: ^11.5.3
This package is auto-updated.
Last update: 2025-05-31 14:57:53 UTC
README
A simple and powerful AI integration package for PHP applications, providing seamless integration with various AI providers. Currently supports Google Gemini AI, with planned support for OpenAI and Anthropic Claude.
Features
- ๐ค Multiple AI Provider Support
- ๐ฌ Advanced Chat Capabilities
- ๐ Conversation History Management
- โ๏ธ Flexible Configuration System
- ๐ฏ Multiple Model Support
- ๐ Token Usage Tracking
- ๐ Detailed Response Analysis
- ๐ก๏ธ Exception Handling & Error Management
- ๐ Event Logging System
- ๐ Security First Approach
- ๐งช Comprehensive Testing Suite
Requirements
- PHP 8.2 or higher
- Laravel 12.x or higher
- Composer
- Google Cloud Platform account with Gemini API access (for Gemini provider)
Installation
You can install the package via composer:
composer require r94ever/phpai
Configuration
Laravel Integration
The package will automatically register itself if you're using Laravel. To publish the configuration file:
php artisan vendor:publish --provider="R94ever\PHPAI\AIServiceProvider"
This will create a phpai.php
configuration file in your config
directory:
return [ 'chatbot' => [ 'providers' => [ 'gemini' => [ 'handler' => \R94ever\PHPAI\Providers\Gemini\GeminiProvider::class, 'api_key' => env('CHATBOT_GEMINI_API_KEY', ''), ], // Add more providers here ], ] ];
Add the following environment variables to your .env
file:
CHATBOT_GEMINI_API_KEY=your-gemini-api-key
Architecture
The package follows a clean, modular architecture:
Core Components
- AI Service: Main entry point for interacting with AI capabilities
- Provider Manager: Manages and coordinates different AI providers
- Chatbot Service: Handles chat interactions with AI providers
Provider System
- Provider Interface: Standard interface for implementing AI providers
- Configuration System: Flexible provider-specific configurations
- Response Handling: Standardized response processing
Event System
- Message Sent Events
- Response Received Events
- Error Events
Basic Usage
use R94ever\PHPAI\Facades\AI; // Simple chat $response = AI::chatbot() ->chat('Hello, how are you?'); // Chat with specific configuration $response = AI::chatbot() ->withConfig(function ($config) { $config->setTemperature(0.7) ->setMaxOutputTokens(500); }) ->chat('Write a poem about AI'); // Chat with system instruction $response = AI::chatbot() ->withInstruction('You are a helpful SQL expert') ->chat('How to write a query to find duplicate records?'); // Chat with conversation history use R94ever\PHPAI\Objects\ChatHistory; use R94ever\PHPAI\Objects\ChatMessage; $history = new ChatHistory([ ChatMessage::user('What is your name?'), ChatMessage::assistant('My name is AI Assistant'), ]); $response = AI::chatbot() ->withHistory($history) ->chat('Nice to meet you!');
Advanced Usage
Custom Models
When using the Gemini provider, you can choose from several available models:
use R94ever\PHPAI\Providers\Gemini\ChatModel; $response = AI::chatbot() ->useModel(ChatModel::Gemini2_5Flash) ->chat('Hello!');
Available models:
New Generation Models
Gemini2_5FlashPreview05_20
: Latest preview model with best price-performance ratioGemini2_5ProPreview
: Advanced model for complex reasoning tasksGemini2_5Flash
: High-speed next-gen features
Standard Models
Gemini2_0FlashLite
: Cost-efficient with low latencyGemini1_5Flash
: Versatile multimodal modelGemini1_5Flash8b
: Compact model for simple tasksGemini1_5Pro
: Balanced model for reasoning tasksGemini2_0FlashLive
: Real-time interaction model
Response Handling
$response = AI::chatbot()->chat('Hello'); // Get message content $message = $response->getMessage(); // Success/Error checking if ($response->isSuccess()) { // Handle success case } else { $errorMessage = $response->getFailedMessage(); } // Token usage metrics $inputTokens = $response->getInputTokens(); $outputTokens = $response->getOutputTokens(); $totalTokens = $response->getTotalTokens(); // Additional metadata $statusCode = $response->getStatusCode(); $modelVersion = $response->getModelVersion(); $responseId = $response->getResponseId();
Event System
The package provides comprehensive event tracking:
use R94ever\PHPAI\Events\ChatMessageSent; use R94ever\PHPAI\Events\ChatResponseReceived; // Track sent messages Event::listen(function (ChatMessageSent $event) { Log::info('Message sent:', [ 'message' => $event->message, 'user' => $event->userId ]); }); // Track responses Event::listen(function (ChatResponseReceived $event) { Log::info('Response received:', [ 'original' => $event->message, 'response' => $event->response->getMessage(), 'metrics' => [ 'tokens' => $event->response->getTotalTokens(), 'model' => $event->response->getModelVersion() ] ]); });
Custom Providers
Implement your own AI providers:
use R94ever\PHPAI\Contracts\ChatbotProvider; use R94ever\PHPAI\Contracts\AIGenerationConfig; use R94ever\PHPAI\Contracts\AITextGeneratorResponse; class CustomProvider implements ChatbotProvider { private AIGenerationConfig $config; public function getConfiguration(): AIGenerationConfig { return $this->config; } public function chat(ChatMessage $chatMessage): AITextGeneratorResponse { // Custom implementation } }
Register your custom provider in your service provider's boot
method:
namespace App\Providers; use Illuminate\Support\ServiceProvider; use R94ever\PHPAI\Services\ChatbotProvidersManager; use Your\Custom\Provider\CustomProvider; class AIServiceProvider extends ServiceProvider { public function boot(): void { $this->app->make(ChatbotProvidersManager::class) ->register('custom', new CustomProvider()); // You can also set it as the default provider $this->app->make(ChatbotProvidersManager::class) ->setDefault('custom'); } } // Don't forget to register your service provider in config/app.php 'providers' => [ // ... App\Providers\AIServiceProvider::class, ],
Security
API Key Protection
Always store API keys securely:
// .env CHATBOT_GEMINI_API_KEY=your-api-key // config/phpai.php 'providers' => [ 'gemini' => [ 'api_key' => env('CHATBOT_GEMINI_API_KEY'), ], ]
Rate Limiting
Implement rate limiting to protect your API usage:
if (RateLimiter::tooManyAttempts('ai-chat:'.$userId, $perMinuteLimit)) { throw new ChatbotException('Rate limit exceeded'); } RateLimiter::hit('ai-chat:'.$userId);
Content Filtering
Add content filtering logic:
Event::listen(function (ChatMessageSent $event) { if (containsSensitiveContent($event->message)) { throw new ChatbotException('Inappropriate content'); } });
Testing
The package includes comprehensive tests:
composer test
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests
- Submit a pull request
Support
- Create issues on GitHub
- Email support: vandt147@gmail.com
License
This package is open-source software licensed under the MIT license.