v1.2.3 - Maintenance Release

Maintenance release: dependency bump and CI tooling-drift fixes. No SDK behavior changes — safe to upgrade from v1.2.x.

Changed

• Bumped codecov/codecov-action from v5 to v6 in the Tests workflow.

Fixed

• Forced php-cs-fixer into sequential mode in .php-cs-fixer.php. The 3.95.x parallel runner crashes with is_file(false) when it cannot auto-detect the PHP binary, which surfaced under setup-php-installed toolchains in CI.
• Resolved two PHPStan 2.1 bleeding-edge findings exposed once the toolchain was unblocked:
  • ChatResponse::getContent() no longer relies on ?? against a non-nullable property; it now guards on an empty choices array.
  • StreamIterator::$generator now declares its Generator<int, array<string, mixed>> generic types.
• Cleaned up an empty closure body in tests/Unit/Tools/ToolTest.php flagged by the upgraded fixer.

Docs

• Backfilled CHANGELOG entries for v1.2.1 and v1.2.2 that were tagged without notes.

Full Changelog: v1.2.2...v1.2.3

v1.2.2 - Example Test Runner and Bug Fixes

New Features

• Example Test Runner - Added tests/run-examples.php to validate all SDK examples against the live xAI API
• Composer Script - Added composer test:examples for easy local testing

Bug Fixes

• ApiException - Fixed error code type casting (API returns int, class expected string)
• ChatResource - Now accepts ServerSideTool in the tools array
• Tool::toArray() - Fixed to return parameters as array instead of JSON string
• image_generation.php - Corrected model name to grok-2-image-1212
• search.php - Updated to use grok-4 model for server-side tools

Improvements

• Added --test mode to interactive examples for CI/automation compatibility
• Documented unavailable APIs with expected failure handling:
  • Embeddings API (#10)
  • Collections API (#11)
  • Server-side Tools requiring grok-4 (#12)

Test Results

Passed:            7
Failed:            0
Skipped:           1
Expected Failures: 4

Full Changelog: v1.2.1...v1.2.2

v1.2.1 - Code Quality & Documentation Fixes

This patch release resolves code quality issues and adds documentation for embeddings API availability.

Bug Fixes

• 422 Error Classification: 422 (Unprocessable Entity) errors now correctly throw BadRequestException instead of being misclassified (fixes #8)

Code Quality

• Fixed code style issues across 8 files (php-cs-fixer)
• Resolved PHPStan level 8 errors in RequestResult.php and RetryMiddleware.php
• Regenerated PHPStan baseline for test-related type annotations

Documentation

• Embeddings API: Marked as "Coming Soon" - the xAI /v1/embeddings endpoint exists but no embedding models are publicly available yet
  • Added notices to EmbeddingsResource, example file, and CHANGELOG
  • Improved error handling in embeddings example to explain 404 errors

Installation

composer require displace/xai-sdk-php:^1.2.1

Full Changelog: v1.2.0...v1.2.1

v1.2.0

Added

Embeddings API Support

• EmbeddingsResource: New resource for the /v1/embeddings endpoint
  • create() method supporting single string or batch array input
  • Optional encodingFormat and dimensions parameters
• EmbeddingsResponse: Response class with helper methods
  • getEmbedding() for single-input convenience
  • getEmbeddings() for all vectors
  • count() for number of embeddings
• Embedding: Individual embedding with index, embedding array, and dimensions helper
• EmbeddingsUsage: Token usage tracking for embeddings
• embeddings.php: Example demonstrating basic usage, batch embeddings, and similarity comparison

Deferred Completions

• DeferredCompletion: Support for long-running requests with polling
  • Status tracking: PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED
  • Helper methods: isPending(), isCompleted(), isFailed(), isFinished()
  • getResult() and getError() for accessing completion data
• ChatResource new methods:
  • createDeferred(): Initiate a deferred completion request
  • retrieveDeferred(): Poll for completion status
  • awaitDeferred(): Convenient wait-with-timeout functionality
• DeferredCompletionException: Exception for deferred completion failures

Concurrent Request Batching

• ConcurrentRequests: Utility for executing multiple API requests
  • run(): Execute callbacks and return RequestResult array
  • all(): Execute all callbacks, throw on any failure
  • settled(): Execute all and return only successful results
  • Configurable concurrency limits
• RequestResult: Result wrapper with functional programming patterns
  • isSuccess(), isFailure(), getValue(), getError()
  • map(), flatMap(), getValueOrDefault()
• BatchException: Exception with detailed failure information

Fluent Request Builder

• ChatRequestBuilder: Builder pattern for complex chat requests
  • All chat parameters: model(), temperature(), maxTokens(), seed(), etc.
  • Message helpers: systemPrompt(), userMessage(), assistantMessage()
  • Tool support: withTool(), withTools(), toolChoice(), parallelToolCalls()
  • Response formats: jsonResponse(), jsonSchema(), responseFormat()
  • build() to get Chat instance, send() to execute immediately
  • reset() for builder reuse

PSR-15 Style Middleware System

• MiddlewareInterface: Interface for request/response interception
• MiddlewareStack: Stack manager with push(), prepend(), remove(), handle()
• LoggingMiddleware: Request/response logging with PSR-3 logger
  • Configurable log levels
  • Sensitive header redaction
  • Body truncation options
• RetryMiddleware: Retry logic with exponential backoff and jitter
• CachingMiddleware: Response caching using ResponseCache
• HttpClient integration:
  • withMiddleware() for adding middleware
  • withMiddlewareStack() for stack replacement
  • getMiddlewareStack() accessor

Response Caching Layer

• ResponseCache: PSR-16 compatible response caching
  • Cache key generation based on request hash
  • TTL configuration per endpoint
  • Skip streaming responses by default
• CacheConfig: Configuration class with factory methods
  • disabled(): Disable caching entirely
  • deterministicOnly(): Only cache requests with seed
  • metadataOnly(): Only cache metadata endpoints
  • Options: cacheableEndpoints, requireSeed, cacheStreaming, endpointTtls
• CachedResponse: Response wrapper with cache metadata

Changed

• HttpConfig: Default maxRetries changed from 0 to 3 (Python SDK parity)
  • Added DEFAULT_MAX_RETRIES constant
  • Added withoutRetries() factory method for disabling retries
• XaiClient: Added embeddings property for accessing EmbeddingsResource
• composer.json: Added psr/simple-cache dependency for caching support

Fixed

• 422 errors now throw BadRequestException instead of generic ApiException (#8)

Documentation

• docs/V2_ROADMAP.md: Comprehensive v2.0 planning document
  • Async support analysis (ReactPHP recommended)
  • gRPC support analysis
  • Voice Agent API analysis (WebSocket)
• docs/FRAMEWORK_INTEGRATIONS.md: Laravel/Symfony package proposals
  • displace/xai-laravel: Facade, Service Provider, Queue integration
  • displace/xai-symfony: Bundle, Autowiring, Messenger integration

Full Changelog: v1.1.0...v1.2.0

v1.1.0

This release adds proper support for server-side tools (x_search, web_search,
code_execution) via the /v1/responses endpoint.

Highlights:

• New ResponsesResource for /v1/responses endpoint
• Response parsers for the output array format
• toResponsesArray() method on all ServerSideTool implementations
• New search.php example

Fixes:

• Server-side tools now work correctly (fixes #6)
• Response format parsing for server-side tools (fixes #7)

Full changelog: https://github.com/DisplaceTech/xai-sdk-php/blob/main/CHANGELOG.md