Anthropic Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mozex/anthropic-php
   

   The package auto-discovers a PSR-18 HTTP client (Guzzle/Symfony by default).

2. First API Call:

   use Anthropic\Anthropic;
   
   $client = Anthropic::client(config('services.anthropic.key'));
   $response = $client->messages()->create([
       'model' => 'claude-sonnet-4-6',
       'messages' => [['role' => 'user', 'content' => 'Hello']],
   ]);
   echo $response->content[0]->text;
   

3. Key Config: Store your API key in .env:

   ANTHROPIC_KEY=your_api_key_here
   

   Then reference it in config/services.php:

   'anthropic' => [
       'key' => env('ANTHROPIC_KEY'),
   ],
   

First Use Case: Chatbot Endpoint

Create a ChatService facade:

// app/Services/ChatService.php
namespace App\Services;

use Anthropic\Anthropic;
use Illuminate\Support\Facades\Facade;

class ChatService extends Facade {
    protected static function getFacadeAccessor() {
        return 'anthropic';
    }
}

Register the service provider:

// config/app.php
'providers' => [
    // ...
    Mozex\AnthropicLaravel\AnthropicServiceProvider::class,
],

Now use it in a controller:

use App\Services\ChatService;

class ChatController extends Controller {
    public function ask(string $question) {
        $response = ChatService::messages()->create([
            'model' => 'claude-sonnet-4-6',
            'messages' => [['role' => 'user', 'content' => $question]],
        ]);
        return response()->json(['answer' => $response->content[0]->text]);
    }
}

Implementation Patterns

1. Service Layer Abstraction

Pattern: Wrap Anthropic calls in domain-specific services to:

• Hide API complexity
• Add business logic
• Centralize error handling

Example:

// app/Services/CustomerSupportService.php
class CustomerSupportService {
    public function __construct(protected AnthropicClient $client) {}

    public function handleTicket(string $ticketContent): string {
        $response = $this->client->messages()->create([
            'model' => 'claude-opus-4-6',
            'max_tokens' => 2048,
            'messages' => [
                ['role' => 'system', 'content' => 'You are a customer support agent.'],
                ['role' => 'user', 'content' => $ticketContent],
            ],
        ]);

        return $response->content[0]->text;
    }
}

2. Streaming Responses

Pattern: Process streaming responses in real-time for:

• Chat UIs
• Large text generation
• Progressive rendering

Example with Laravel Echo:

// app/Http/Controllers/StreamController.php
class StreamController extends Controller {
    public function generateStream(string $prompt) {
        $stream = ChatService::messages()->createStreamed([
            'model' => 'claude-sonnet-4-6',
            'messages' => [['role' => 'user', 'content' => $prompt]],
        ]);

        return response()->stream(function () use ($stream) {
            foreach ($stream as $chunk) {
                if ($chunk->type === 'content_block_delta' &&
                    $chunk->delta->type === 'text_delta') {
                    echo $chunk->delta->text;
                    flush();
                }
            }
        });
    }
}

3. Tool Integration

Pattern: Use tools for:

• Database queries
• External API calls
• Custom business logic

Example:

// app/Services/InventoryService.php
class InventoryService {
    public function checkStock(string $productId): array {
        $response = ChatService::messages()->create([
            'model' => 'claude-sonnet-4-6',
            'tools' => [
                [
                    'name' => 'get_inventory',
                    'description' => 'Check stock levels for a product',
                    'input_schema' => [
                        'type' => 'object',
                        'properties' => [
                            'product_id' => ['type' => 'string'],
                        ],
                        'required' => ['product_id'],
                    ],
                ],
            ],
            'messages' => [
                ['role' => 'user', 'content' => 'What is the stock level for product ' . $productId],
            ],
        ]);

        // Handle tool call
        if (isset($response->content[0]) && $response->content[0]->name === 'get_inventory') {
            return $this->fetchFromDatabase($response->content[0]->input['product_id']);
        }

        return ['error' => 'No tool call detected'];
    }
}

4. Batch Processing

Pattern: Process multiple requests efficiently:

• User queries in bulk
• Data validation
• Parallel operations

Example:

// app/Jobs/ProcessUserQueries.php
class ProcessUserQueries implements ShouldQueue {
    public function handle() {
        $queries = UserQuery::where('processed', false)->get();

        $batch = ChatService::batches()->create([
            'model' => 'claude-sonnet-4-6',
            'messages' => $queries->map(fn($q) => [
                'role' => 'user',
                'content' => $q->query,
            ])->toArray(),
        ]);

        foreach ($batch->results as $index => $result) {
            $queries[$index]->update(['response' => $result->content[0]->text]);
        }
    }
}

5. File Integration

Pattern: Upload and reference files:

• PDFs
• Images
• Generated content

Example:

// app/Services/DocumentProcessor.php
class DocumentProcessor {
    public function processDocument(string $filePath, string $prompt) {
        $file = ChatService::files()->upload([
            'file' => fopen($filePath, 'r'),
        ]);

        $response = ChatService::messages()->create([
            'model' => 'claude-opus-4-6',
            'betas' => ['files-api-2025-04-14'],
            'messages' => [
                [
                    'role' => 'user',
                    'content' => [
                        ['type' => 'text', 'text' => $prompt],
                        ['type' => 'document', 'source' => [
                            'type' => 'file',
                            'file_id' => $file->id,
                        ]],
                    ],
                ],
            ],
        ]);

        return $response->content[0]->text;
    }
}

6. Error Handling

Pattern: Centralize error responses:

• API rate limits
• Invalid inputs
• Model refusals

Example:

// app/Exceptions/Handler.php
class Handler extends ExceptionHandler {
    public function render($request, Throwable $exception) {
        if ($exception instanceof \Anthropic\Exceptions\AnthropicException) {
            return response()->json([
                'error' => $exception->getMessage(),
                'type' => $exception->getType(),
                'code' => $exception->getCode(),
                'meta' => $exception->getMeta(),
            ], $exception->getStatusCode());
        }

        return parent::render($request, $exception);
    }
}

Gotchas and Tips

1. Rate Limits and Meta Data

• Gotcha: Forgetting to check $response->meta() before making subsequent calls.
• Tip: Always inspect meta()->requestLimit and meta()->tokenLimit:

  $remainingRequests = $response->meta()->requestLimit->remaining;
  $remainingTokens = $response->meta()->tokenLimit->remaining;
  

• Pattern: Create a decorator:

  class RateLimitedClient {
      public function __construct(protected AnthropicClient $client) {}
  
      public function safeCreate(array $parameters) {
          $response = $this->client->messages()->create($parameters);
  
          if ($response->meta()->requestLimit->remaining < 5) {
              sleep($response->meta()->requestLimit->resetAt->getTimestamp() - time() + 1);
          }
  
          return $response;
      }
  }
  

2. Streaming Edge Cases

• Gotcha: Not handling non-text delta types (e.g., tool_use_delta).
• Tip: Filter deltas explicitly:

  foreach ($stream as $chunk) {
      if ($chunk->type === 'content_block_delta' &&
          $chunk->delta->type === 'text_delta') {
          echo $chunk->delta->text;
      }
      // Handle other delta types (e.g., tool_use_delta)
  }
  

• Performance Tip: Use response()->stream() for large streams to avoid memory issues.

3. Tool Use Quirks

• Gotcha: Tools may return nested structures that aren't JSON-serializable.
• Tip: Validate tool inputs before sending:

  $toolInput