README

A high-performance, strictly-typed, and enterprise-grade Laravel wrapper for the Exa.ai v2.1 API.

Features

• 🚀 PHP 8.2+ with Asymmetric Visibility and Property Hooks (PHP 8.4)
• 🔧 Fluent Builder Pattern for maximum IDE discoverability
• 🛡️ Strictly Typed DTOs - No raw arrays reach the end-user
• 🔄 Automatic Retries with exponential backoff for 429 and 5xx errors
• 📊 Laravel Context Integration for enterprise observability
• 🔑 Multi-Connection Support for managing multiple API keys
• ✅ PHPStan Level 9 compliant

Requirements

• PHP 8.2 or higher
• Laravel 10.x, 11.x, or 12.x

Installation

composer require sepehr-mohseni/exaravel

Publish the configuration file:

php artisan vendor:publish --tag=exaravel-config

Add your API key to your .env file:

EXA_API_KEY=your-api-key-here

Usage

Search

use Sepehr_Mohseni\Exaravel\Facades\Exa;
use Sepehr_Mohseni\Exaravel\Enums\SearchType;
use Sepehr_Mohseni\Exaravel\Enums\Category;

// Basic search
$results = Exa::search('Laravel best practices')->get();

// Advanced search with fluent builder
$results = Exa::search('Machine learning frameworks')
    ->type(SearchType::Neural)
    ->category(Category::GitHub)
    ->numResults(20)
    ->includeDomains(['github.com', 'gitlab.com'])
    ->excludeDomains(['stackoverflow.com'])
    ->startPublishedDate('2024-01-01')
    ->endPublishedDate(new DateTime('now'))
    ->withContents(text: true, highlights: true)
    ->withAutoprompt()
    ->get();

// Iterate over results
foreach ($results as $result) {
    echo $result->title . ' - ' . $result->url . PHP_EOL;
}

// Get first result directly
$firstResult = Exa::search('PHP 8.4 features')->first();

Find Similar

// Find content similar to a URL
$results = Exa::findSimilar('https://laravel.com/docs/eloquent')
    ->numResults(10)
    ->excludeSourceDomain()
    ->category(Category::ResearchPaper)
    ->withContents(text: true, summary: true)
    ->get();

Get Contents

// Retrieve full content for specific document IDs
$contents = Exa::contents(['doc-id-1', 'doc-id-2', 'doc-id-3'])
    ->withText(maxCharacters: 10000)
    ->withMarkdown()
    ->withHighlights(perUrl: 3)
    ->withSummary('What are the key points?')
    ->get();

foreach ($contents as $content) {
    echo $content->title . PHP_EOL;
    echo $content->getPreferredContent(); // Returns markdown if available, otherwise text
}

Answer (Agentic Endpoint)

// Get a direct answer with citations
$response = Exa::answer('What are the new features in PHP 8.4?')
    ->numResults(5)
    ->neural()
    ->includeDomains(['php.net', 'wiki.php.net'])
    ->systemPrompt('You are a PHP expert. Provide detailed technical explanations.')
    ->get();

echo $response->answer;

foreach ($response->citations as $citation) {
    echo "Source: {$citation->url}" . PHP_EOL;
}

// Get just the answer text
$answerText = Exa::answer('Explain Laravel service providers')->text();

Working with Results

$results = Exa::search('Laravel packages')->get();

// Collection-like methods
$urls = $results->urls();
$titles = $results->titles();

// Filter results
$highScoring = $results->filter(fn ($result) => $result->score > 0.8);

// Map results
$summaries = $results->map(fn ($result) => [
    'title' => $result->title,
    'url' => $result->url,
]);

// Check results
if ($results->isEmpty()) {
    echo 'No results found';
}

echo "Found {$results->count()} results";

Multiple Connections

Configure multiple API keys in config/exaravel.php:

'connections' => [
    'default' => [
        'api_key' => env('EXA_API_KEY'),
    ],
    'premium' => [
        'api_key' => env('EXA_PREMIUM_API_KEY'),
        'timeout' => 60,
    ],
],

Use a specific connection:

$results = Exa::using('premium')
    ->search('Complex query')
    ->get();

// Or use a custom API key on the fly
$results = Exa::withApiKey('custom-key')
    ->search('Query')
    ->get();

Error Handling

use Sepehr_Mohseni\Exaravel\Exceptions\AuthenticationException;
use Sepehr_Mohseni\Exaravel\Exceptions\RateLimitException;
use Sepehr_Mohseni\Exaravel\Exceptions\InsufficientCreditsException;
use Sepehr_Mohseni\Exaravel\Exceptions\ValidationException;

try {
    $results = Exa::search('query')->get();
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (RateLimitException $e) {
    // Rate limit exceeded
    $retryAfter = $e->retryAfter; // seconds to wait
} catch (InsufficientCreditsException $e) {
    // Need more API credits
} catch (ValidationException $e) {
    // Invalid request parameters
    $errors = $e->errors;
}

Livecrawl Mode

use Sepehr_Mohseni\Exaravel\Enums\LivecrawlMode;

$results = Exa::search('Latest tech news')
    ->livecrawl(LivecrawlMode::Always, timeout: 10000)
    ->get();

Configuration

// config/exaravel.php

return [
    'api_key' => env('EXA_API_KEY'),
    'base_url' => env('EXA_BASE_URL', 'https://api.exa.ai'),
    'timeout' => env('EXA_TIMEOUT', 30),
    'connect_timeout' => env('EXA_CONNECT_TIMEOUT', 10),
    
    'retry' => [
        'times' => env('EXA_RETRY_TIMES', 3),
        'sleep_milliseconds' => env('EXA_RETRY_SLEEP', 500),
        'when' => [429, 500, 502, 503, 504],
    ],
    
    'default_search_type' => env('EXA_DEFAULT_SEARCH_TYPE', 'auto'),
    'default_num_results' => env('EXA_DEFAULT_NUM_RESULTS', 10),
    
    'logging' => [
        'enabled' => env('EXA_LOGGING_ENABLED', false),
        'channel' => env('EXA_LOGGING_CHANNEL', 'stack'),
    ],
];

Testing

composer test

Run static analysis:

composer analyse

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Sepehr Mohseni
• All Contributors

License

The MIT License (MIT). Please see License File for more information.