🧠 Grok PHP Client

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.

---

📖 Table of Contents

• Features
• Installation
• Quick Start
  • Basic Usage
  • Vision Analysis
  • Advanced Configuration
• Available Grok AI Models
• Streaming Responses
• Response format
• Error Handling
• Testing
• Security
• Contributing
• License

---

Features

• 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.

---

Installation

Install via Composer:

composer require grok-php/client

Requirements:

• PHP 8.2+
• Composer 2.0+

---

Quick Start

Basic Usage

useGrokPHP\Client\Clients\GrokClient;
useGrokPHP\Client\Config\GrokConfig;
useGrokPHP\Client\Config\ChatOptions;
useGrokPHP\Client\Enums\Model;
// Initialize the client$config = newGrokConfig('your-api-key');
$client = newGrokClient($config);
// Define messages$messages = [
['role' => 'system', 'content' => 'You are an AI assistant.'],
['role' => 'user', 'content' => 'Tell me a joke!']
];
// Call API$options = newChatOptions(model: Model::GROK_2, temperature: 0.7, stream: false);
$response = $client->chat($messages, $options);
echo"AI Response: " . $response['choices'][0]['message']['content'];

Defaults Used:

• Model: grok-2
• Temperature: 0.7
• Streaming: false

---

Vision Analysis (Image Recognition)

The Vision API allows you to send images for analysis using Grok-2-Vision models.

useGrokPHP\Client\Clients\GrokClient;
useGrokPHP\Client\Config\GrokConfig;
// Initialize the client$config = newGrokConfig('your-api-key');
$client = newGrokClient($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'];

Supported Models for Vision

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.

---

Advanced Configuration

useGrokPHP\Client\Clients\GrokClient;
useGrokPHP\Client\Config\GrokConfig;
useGrokPHP\Client\Config\ChatOptions;
useGrokPHP\Client\Enums\Model;
// Load API key from environment$apiKey = getenv('GROK_API_KEY');
$config = newGrokConfig($apiKey);
$client = newGrokClient($config);
// Define messages$messages = [
['role' => 'system', 'content' => 'You are a helpful assistant.'],
['role' => 'user', 'content' => 'How do black holes form?']
];
// Custom API settings$options = newChatOptions(
model: Model::GROK_2_LATEST,
temperature: 1.2,
stream: false
);
$response = $client->chat($messages, $options);
echo"AI Says: " . $response['choices'][0]['message']['content'];

---

Available Grok AI Models

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

Default model used:Model::GROK_2

---

Streaming Responses

The Grok API supports streaming responses for real-time interaction. Enable it by setting stream: true:

$options = newChatOptions(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.

---

Response format

The Grok API supports setting a response format, also refered to structured outputs, for the grok-2-1212 model.

$options = newChatOptions(model: Model::GROK_2_1212, temperature: 0.7, stream: false, responseFormat: ['type' => 'json_object']);
$response = $client->chat($messages, $options);

---

Error Handling

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:

useGrokPHP\Client\Exceptions\GrokException;
try {
$response = $client->chat($messages, $options);
} catch (GrokException$e) {
echo"Error: " . $e->getMessage();
}

---

Testing

Run the tests with PHPUnit:

composer test

Or run PHPUnit manually:

vendor/bin/phpunit

---

Security

If you discover a security vulnerability, please report it via email: 📩 thefeqy@gmail.com

---

Contributing

Want to improve this package? Check out CONTRIBUTING.md for contribution guidelines.

---

License

This package is open-source software licensed under the MIT License.