README

PHP wrapper and CLI for the xAI Text-To-Speech (TTS) API, built on top of the adachsoft/text-to-audio-contract.

This package provides:

• An implementation of TextToSpeechInterface that talks to the official xAI TTS HTTP API.
• A small CLI tool (bin/text-to-audio-xai) that turns plain text or text files into audio files.
• A thin HTTP client based on PHP's cURL extension.

Important: this project is not an official xAI product. Use it at your own risk and make sure you comply with xAI's terms of service.

Requirements

• PHP 8.3 or higher
• ext-curl enabled
• Composer
• A valid xAI API key (XAI_KEY)

Installation

Install via Composer:

composer require adachsoft/text-to-audio-xai

The package depends on adachsoft/text-to-audio-contract, which will be installed automatically.

Configuration

The CLI and service expect the xAI API key to be provided via the XAI_KEY environment variable.

A typical project layout uses a .env file and vlucas/phpdotenv to load environment variables:

# .env
XAI_KEY=sk-...

The provided bin/bootstrap.php script loads vendor/autoload.php and then reads .env using Dotenv::createImmutable().

CLI usage

The main entrypoint is the bin/text-to-audio-xai script:

php bin/text-to-audio-xai [options]

Supported options:

• --text "Some text" – text to be synthesized.
• --file path.txt – path to a text file to be synthesized.
• --voice name – logical voice identifier (default: "default").
• --format mp3|wav|opus – output audio format (default: mp3).
• --output file – optional output file name.
• -h, --help – show help.

Exactly one of --text or --file must be provided.

Examples

Basic usage with inline text (default format mp3, default output directory var/data):

php bin/text-to-audio-xai --text "Hello from xAI TTS"

Specify voice and output file name:

php bin/text-to-audio-xai \
    --text "Cześć, tu Grok po polsku" \
    --voice leo \
    --output grok-pl.mp3

Use a text file as input and change format:

php bin/text-to-audio-xai \
    --file resources/text/introduction.txt \
    --format wav

By default, audio files are written into the var/data directory (created on demand). The file extension is derived from the requested audio format.

Library usage

You can also use the services directly from your PHP code, without the CLI.

use AdachSoft\TextToAudioContract\Dto\TextToSpeechRequestDto;
use AdachSoft\TextToAudioXai\CurlXaiTtsHttpClient;
use AdachSoft\TextToAudioXai\TextToSpeechService;

$xaiKey = getenv('XAI_KEY') ?: ($_ENV['XAI_KEY'] ?? '');

$client = new CurlXaiTtsHttpClient();
$textToSpeech = new TextToSpeechService($xaiKey, $client);

$request = new TextToSpeechRequestDto(
    text: 'Hello from PHP',
    voice: 'default',
    format: 'mp3',
);

$response = $textToSpeech->synthesize($request);

file_put_contents('hello.mp3', $response->audioContent);

The low-level HTTP interaction with xAI is encapsulated in CurlXaiTtsHttpClient and the service itself enforces simple validation rules (e.g. non-empty API key, non-empty text).

Testing

The project comes with a test suite based on PHPUnit:

• Unit tests for the core service (TextToSpeechService) and CLI helpers (e.g. Cli\AudioFileWriter).
• Functional tests for the CLI wrapper.
• A production test group (group=production) that uses the real xAI API via CurlXaiTtsHttpClient.

To run the default test suite (without production tests):

vendor/bin/phpunit

To run the production tests (will call the real xAI API and requires a valid XAI_KEY):

vendor/bin/phpunit --group production

Quality tools

The repository is configured to use the following tools:

• PHPStan – static analysis for src/ and tests/.
• Rector – automated refactorings and code quality improvements.
• PHP-CS-Fixer – coding style enforcement.
• PHPUnit – unit, functional and production tests.

You can run them with the usual vendor binaries, for example:

phpstan analyse src
phpstan analyse tests

vendor/bin/phpunit
vendor/bin/phpunit --group production

PHP_CS_FIXER_IGNORE_ENV=1 vendor/bin/php-cs-fixer fix src
PHP_CS_FIXER_IGNORE_ENV=1 vendor/bin/php-cs-fixer fix tests

Changelog and versioning

All notable changes are documented in CHANGELOG.md.

The first public version of this library is 0.1.0.