A lightweight, framework-agnostic PHP client for interacting with Grok AI APIs. Supports PHP 8.2+, built with OOP best practices, and fully type-safe.
- Features
- Installation
- Quick Start
- Available Grok AI Models
- Streaming Responses
- Response format
- Error Handling
- Testing
- Security
- Contributing
- License
- Easy Integration – Seamlessly connects with Grok AI APIs.
- Modern PHP Features – Utilizes PHP 8.2+ features like enums and traits.
- Framework Agnostic – Works with any PHP project, CLI scripts, or web applications.
- Streaming Support – Built-in support for real-time responses.
- Lightweight & Efficient – Optimized with PSR-4 autoloading and minimal dependencies.
Install via Composer:
composer require grok-php/client- PHP 8.2+
- Composer 2.0+
use GrokPHP\Client\Clients\GrokClient; use GrokPHP\Client\Config\GrokConfig; use GrokPHP\Client\Config\ChatOptions; use GrokPHP\Client\Enums\Model; // Initialize the client $config = new GrokConfig('your-api-key'); $client = new GrokClient($config); // Define messages $messages = [ ['role' => 'system', 'content' => 'You are an AI assistant.'], ['role' => 'user', 'content' => 'Tell me a joke!'] ]; // Call API $options = new ChatOptions(model: Model::GROK_2, temperature: 0.7, stream: false); $response = $client->chat($messages, $options); echo "AI Response: " . $response['choices'][0]['message']['content'];- Model:
grok-2 - Temperature:
0.7 - Streaming:
false
The Vision API allows you to send images for analysis using Grok-2-Vision models.
use GrokPHP\Client\Clients\GrokClient; use GrokPHP\Client\Config\GrokConfig; // Initialize the client $config = new GrokConfig('your-api-key'); $client = new GrokClient($config); // Use the Vision API to analyze an image $response = $client->vision()->analyze('https://example.com/image.jpg', 'Describe this image.'); echo "Vision Response: " . $response['choices'][0]['message']['content'];| Model Enum | API Model Name | Description |
|---|---|---|
Model::GROK_2_VISION | grok-2-vision | Base Vision Model |
Model::GROK_2_VISION_LATEST | grok-2-vision-latest | Latest Vision Model |
Model::GROK_2_VISION_1212 | grok-2-vision-1212 | Default model for image analysis |
Note: If you attempt to use an unsupported model for vision, an exception will be thrown.
use GrokPHP\Client\Clients\GrokClient; use GrokPHP\Client\Config\GrokConfig; use GrokPHP\Client\Config\ChatOptions; use GrokPHP\Client\Enums\Model; // Load API key from environment $apiKey = getenv('GROK_API_KEY'); $config = new GrokConfig($apiKey); $client = new GrokClient($config); // Define messages $messages = [ ['role' => 'system', 'content' => 'You are a helpful assistant.'], ['role' => 'user', 'content' => 'How do black holes form?'] ]; // Custom API settings $options = new ChatOptions( model: Model::GROK_2_LATEST, temperature: 1.2, stream: false ); $response = $client->chat($messages, $options); echo "AI Says: " . $response['choices'][0]['message']['content'];Grok AI offers multiple models optimized for different use cases. These models are available in the Model enum inside our package: 📄 src/Enums/Model.php
| Model Enum | API Model Name | Description |
|---|---|---|
Model::GROK_VISION_BETA | grok-vision-beta | Experimental vision-enabled model |
Model::GROK_2_VISION | grok-2-vision | Advanced multi-modal vision model |
Model::GROK_2_VISION_LATEST | grok-2-vision-latest | Latest iteration of Grok vision models |
Model::GROK_2_VISION_1212 | grok-2-vision-1212 | Enhanced vision model with performance improvements |
Model::GROK_2_1212 | grok-2-1212 | Optimized chat model |
Model::GROK_2 | grok-2 | Default general-purpose Grok model |
Model::GROK_2_LATEST | grok-2-latest | Latest iteration of Grok-2 |
Model::GROK_BETA | grok-beta | Experimental beta model |
The Grok API supports streaming responses for real-time interaction. Enable it by setting stream: true:
$options = new ChatOptions(model: Model::GROK_2, temperature: 0.7, stream: true); $response = $client->chat($messages, $options);Streaming can be useful for chatbots, real-time applications, and CLI assistants.
The Grok API supports setting a response format, also refered to structured outputs, for the grok-2-1212 model.
$options = new ChatOptions(model: Model::GROK_2_1212, temperature: 0.7, stream: false, responseFormat: ['type' => 'json_object']); $response = $client->chat($messages, $options);This package includes built-in error handling with a dedicated exception class. Common errors and their messages:
| Error Type | HTTP Code | Message |
|---|---|---|
Invalid API Key | 400 | No API key provided. Specify your API key. |
Invalid Request | 400 | Client specified an invalid argument. |
Invalid Role | 422 | Unknown role variant provided in messages. |
Example of handling exceptions:
use GrokPHP\Client\Exceptions\GrokException; try { $response = $client->chat($messages, $options); } catch (GrokException $e) { echo "Error: " . $e->getMessage(); }Run the tests with PHPUnit:
composer testOr run PHPUnit manually:
vendor/bin/phpunitIf you discover a security vulnerability, please report it via email: 📩 thefeqy@gmail.com
Want to improve this package? Check out CONTRIBUTING.md for contribution guidelines.
This package is open-source software licensed under the MIT License.
