Client Laravel Package

Getting Started

Start by installing the package via Composer: composer require grok-php/client. Next, configure your Grok API key—either in .env as GROK_API_KEY or pass it directly to the client constructor. The client follows a fluent, low-boilerplate pattern: instantiate GrokClient, call chat()->create() for text chat, or vision()->analyze($image, $message) for image analysis, and receive typed responses. First use case: quickly integrate Grok-powered chat into a Laravel controller, e.g., a support bot that sends user queries to Grok and returns AI-generated replies. Second use case: build a visual support assistant by uploading user-submitted images (e.g., via form upload or URL) and analyzing them using vision()->analyze() to extract insights, detect issues, or answer user questions about the image.

Implementation Patterns

Leverage Laravel’s service container to bind GrokClient as a singleton—configure via config/services.php or a service provider. Use dependency injection to pass the client into services or jobs. For chat flows, wrap the client in a domain service (e.g., GrokChatService) to encapsulate prompt engineering, user context assembly, and retry logic. For vision workflows, create a dedicated ImageAnalysisService that handles image preprocessing (e.g., base64 encoding, URL fetching, dimension validation), validates supported vision models (e.g., grok-2-vision-latest), and structures prompts for consistent output. Handle structured responses with pattern matching on chat()->create() or vision()->analyze() output (e.g., extracting content, image metadata, or reasoning). Extend functionality using the built-in extend() method or subclassing to add custom endpoints (like embeddings) or middleware (e.g., logging, rate limiting). Tip: Inject the client’s vision() method separately when vision-specific features are optional, to avoid coupling unrelated logic.

Gotchas and Tips

• API key resolution is sensitive to environment casing—ensure GROK_API_KEY matches exactly; Laravel’s env() is not loaded in config files, so always use config('services.grok.key') at runtime.
• Default timeout is 30s—configure via GROK_TIMEOUT in .env if Grok’s responses are slow or for long-context use cases.
• Vision requests may return image dimensions or model-specific warnings—always validate the model field matches one of the supported ones (grok-2-vision, grok-2-vision-latest, grok-2-vision-1212) to prevent runtime errors. The client auto-validates, but fallback logic is recommended.
• Error handling throws typed exceptions (GrokException, HttpException, ParseException); image uploads (especially large or malformed ones) may trigger ParseException—log raw request IDs and image_checksum (if available) for debugging.
• The client returns stdClass-based response objects by default; enable strict typing or map responses to DTOs (e.g., VisionAnalysisResult) to avoid runtime @property warnings—this is especially critical for vision responses where fields like reasoning, text, and image_details may vary.
• For streaming (chat()->stream()), use SseSubscriber patterns with Laravel Queues—don’t block HTTP responses on long-running streams. New for v1.3.0: Vision does not support streaming; all analyze() calls are synchronous and must be queued for async processing if latency-sensitive.