README

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

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'];

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.

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'];

Supported Models for Vision

Note: If you attempt to use an unsupported model for vision, an exception will be thrown.

Advanced Configuration

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'];

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

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

Response format

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);

Error Handling

This package includes built-in error handling with a dedicated exception class. Common errors and their messages:

Example of handling exceptions:

use GrokPHP\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.