Download the PHP package lucianotonet/groq-php without Composer

Groq PHP

High-performance PHP client for GroqCloud API

A comprehensive PHP SDK that simplifies interaction with the world's fastest LLM inference platform, allowing PHP developers to easily integrate high-performance models (DeepSeek r1, Llama 3.3, Mixtral, Gemma, and more) into any PHP application.

Using on Laravel? Check this out: GroqLaravel

Features

• [x] Chat Completions
• [x] Tool Calling
• [x] Audio Transcription and Translation
• [x] Text-to-Speech
• [x] Vision
• [x] Reasoning
• [x] Files and Batch Processing

Installation

Configuration

1. Get your API Key:

   • Go to GroqCloud Console
   • Create a new API key

2. Configure your API Key:

   • Using environment variables:

   • Or using a .env file:

Usage

1. Listing Models

List available models.

2. Chat (Completions)

Generate interactive chat responses.

Streaming:

JSON Mode:

Additional Parameters (Chat Completions):

• temperature: Controls randomness (0.0 - 2.0)
• max_completion_tokens: Maximum tokens in response
• top_p: Nucleus sampling
• frequency_penalty: Penalty for repeated tokens (-2.0 - 2.0)
• presence_penalty: Penalty for repeated topics (-2.0 - 2.0)
• stop: Stop sequences
• seed: For reproducibility

3. Tool Calling

Allows the model to call external functions/tools.

Advanced Tool Calling (with multiple tools and parallel calls):

See examples/tool-calling-advanced.php for a more complete example, including:

• Definition of multiple tools (e.g., getCurrentDateTimeTool, getCurrentWeatherTool)
• parallel_tool_calls: Controls whether tool calls can be made in parallel (currently must be forced false in code)

4. Audio (Transcription, Translation and Text-to-Speech)

Transcription and Translation

• Response formats: 'json', 'verbose_json', 'text'. The vtt and srt formats are not supported.
• language: ISO 639-1 code of the source language (optional but recommended for better accuracy). See examples/audio-transcriptions.php for a complete list of supported languages.
• temperature: Controls variability.

Text-to-Speech (TTS)

Convert text to speech using GroqCloud's Text-to-Speech API.

• Models: 'playai-tts' (English), 'playai-tts-arabic' (Arabic)
• Parameters:
  • model(): The TTS model to use
  • input(): Text to convert to speech
  • voice(): Voice identifier (e.g., "Bryan-PlayAI")
  • responseFormat(): Output format (default: "wav")
• Methods:
  • create(): Returns audio content as stream
  • save($filePath): Saves audio to a file and returns success boolean

5. Vision

Allows analyzing images (local upload or URL).

• analyze(): Takes the file path (local) or image URL, and a prompt.
• Size limits: 20MB for URLs, 4MB for local files (due to base64 encoding).
• Default model is llama-3.2-90b-vision-preview, but can be configured with setDefaultModel() or by passing the model parameter in analyze().
• Local image is base64 encoded within the library before sending.

6. Reasoning

Enables step-by-step reasoning tasks.

• analyze(): Takes the prompt (question/problem) and an options array.
• reasoning_format:
  • 'raw': Includes reasoning with <think> tags in content (default)
  • 'parsed': Returns reasoning in a separate reasoning field
  • 'hidden': Returns only the final answer
• system_prompt: Additional instructions for the model (optional). Added as a system message before the user message.
• Must use 'parsed' or 'hidden' format when using JSON mode
• Optional parameters: temperature, max_completion_tokens, top_p, frequency_penalty, etc.

Reasoning Formats

The reasoning feature supports three output formats:

1. Raw Format (Default)

   • Includes reasoning steps within <think> tags in the content
   • Best for debugging and understanding the model's thought process

2. Parsed Format

   • Separates reasoning into a dedicated field
   • Ideal for applications that need to process reasoning steps separately
3. Hidden Format
   • Returns only the final answer without showing reasoning steps
   • Best for production applications where only the result matters

7. Files and Batch Processing

Enables JSONL file upload for batch processing.

File Management:

• upload(): Uploads a valid JSONL file. Purpose must be 'batch'
• File validation:
  • Checks file existence
  • Checks if empty
  • Checks maximum size (100MB)
  • Checks MIME type (text/plain or application/json)
  • Validates each line as valid JSON
• list(): Lists files, optionally filtering by purpose with pagination options (limit, after, order)
• download(): Downloads file content
• delete(): Deletes a file

Batch Processing:

• batches()->create(): Creates batch for asynchronous processing
  • input_file_id: Uploaded JSONL file ID
  • endpoint: Currently only /v1/chat/completions supported
  • completion_window: Currently only '24h' supported
• batches()->list(), batches()->retrieve(), batches()->cancel(): Manage batches

8. Error Handling

The library throws GroqException for API errors. The exception contains:

• getMessage(): Descriptive error message
• getCode(): HTTP status code (or 0 for invalid API key)
• getType(): Error type (see GroqException::ERROR_TYPES for possible types)
• getHeaders(): HTTP response headers
• getResponseBody(): Response body (as object if JSON)
• getError(): Returns array with error details (message, type, code)
• getFailedGeneration(): If error type is failed_generation, returns the invalid JSON that caused the issue

The GroqException class provides static methods for creating specific exceptions like invalidRequest(), authenticationError(), etc., following a factory pattern.

Examples

The examples/ folder contains complete, working PHP scripts demonstrating each library feature. You can run them directly to see the library in action and interact with on your browser.

First, you need to copy your .env file from the root of the project to the examples folder.

Then, in the examples folder, you need to install the dependencies with:

Now, you can start the server with:

Finally, you can access the examples in your browser at http://127.0.0.1:8000.

Tests

The tests/ folder contains unit tests. Run them with composer test. Tests require the GROQ_API_KEY environment variable to be set.

Note: Tests make real API calls to Groq and consume API credits. For this reason, our CI pipeline runs tests only on PHP 8.2. If you need to test with different PHP versions, please do so locally and be mindful of API usage.

Requirements

• PHP >= 8.1
• fileinfo extension
• guzzlehttp/guzzle

Contributing

Contributions are welcome! If you find a bug, have a suggestion, or want to add functionality, please open an issue or submit a pull request.

Changelog

See CHANGELOG.md for the full changelog.

About Semantic Versioning

This package follows SemVer conventions. However, breaking changes may be released in minor versions in the following cases:

1. Changes that only affect static types and not runtime behavior.
2. Modifications to internal library components that are technically public but not intended for external use. (Please open a GitHub issue if you depend on these internals).
3. Changes that should not affect most users in practical scenarios.

License

MIT