SDK PHP | Evocrawl

Installation

Le SDK PHP officiel est maintenu dans le monorepo de Evocrawl à l’emplacement apps/php-sdk. Pour installer le SDK PHP de Evocrawl, ajoutez la dépendance via Composer :

composer require firecrawl/firecrawl-sdk

Nécessite PHP 8.1 ou version ultérieure.

Intégration Laravel

Le SDK inclut une prise en charge native de Laravel avec découverte automatique. Après avoir installé le package, publiez le fichier de configuration :

php artisan vendor:publish --provider="Evocrawl\Laravel\EvocrawlServiceProvider"

Ajoutez ensuite votre clé API à votre fichier .env :

FIRECRAWL_API_KEY=fc-your-api-key

Les variables d’environnement suivantes sont prises en charge :

Variable	Par défaut	Description
`FIRECRAWL_API_KEY`	—	Votre clé API Evocrawl (obligatoire)
`FIRECRAWL_API_URL`	`https://api.evocrawl.com`	URL de base de l’API
`FIRECRAWL_TIMEOUT`	`300`	Délai d’expiration des requêtes HTTP, en secondes
`FIRECRAWL_MAX_RETRIES`	`3`	Tentatives automatiques en cas d’échecs temporaires
`FIRECRAWL_BACKOFF_FACTOR`	`0.5`	Facteur de backoff exponentiel, en secondes

Utilisation

Obtenez une clé API sur evocrawl.com
Définissez la clé API comme variable d’environnement nommée FIRECRAWL_API_KEY, ou passez-la à EvocrawlClient::create(apiKey: ...)

Voici un exemple rapide avec l’API actuelle du SDK :

use Evocrawl\Client\EvocrawlClient;
use Evocrawl\Models\CrawlOptions;
use Evocrawl\Models\ScrapeOptions;

$client = EvocrawlClient::fromEnv();

$doc = $client->scrape(
    'https://evocrawl.com',
    ScrapeOptions::with(formats: ['markdown'])
);

$crawl = $client->crawl(
    'https://evocrawl.com',
    CrawlOptions::with(limit: 5)
);

echo $doc->getMarkdown();
echo 'Crawled pages: ' . count($crawl->getData());

Utiliser la façade Laravel

Dans une application Laravel, vous pouvez utiliser la façade Evocrawl ou l’injection de dépendances :

use Evocrawl\Client\EvocrawlClient;
use Evocrawl\Laravel\Facades\Evocrawl;

// Via Facade
$doc = Evocrawl::scrape('https://example.com');

// Via injection de dépendances
class ScrapeController
{
    public function __construct(
        private readonly EvocrawlClient $firecrawl,
    ) {}

    public function index()
    {
        $doc = $this->firecrawl->scrape('https://example.com');
        return response()->json(['markdown' => $doc->getMarkdown()]);
    }
}

Scraping d’une URL

Pour effectuer le scraping d’une seule URL, utilisez la méthode scrape.

use Evocrawl\Models\Document;
use Evocrawl\Models\ScrapeOptions;

$doc = $client->scrape(
    'https://evocrawl.com',
    ScrapeOptions::with(
        formats: ['markdown', 'html'],
        onlyMainContent: true,
        waitFor: 5000,
    )
);

echo $doc->getMarkdown();
echo $doc->getMetadata()['title'] ?? '';

Extraction de JSON

Extrayez du JSON structuré avec JsonFormat via le point de terminaison scrape :

use Evocrawl\Models\JsonFormat;
use Evocrawl\Models\ScrapeOptions;

$jsonFmt = JsonFormat::with(
    prompt: 'Extract the product name and price',
    schema: [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'price' => ['type' => 'number'],
        ],
    ],
);

$doc = $client->scrape(
    'https://example.com/product',
    ScrapeOptions::with(formats: [$jsonFmt])
);

print_r($doc->getJson());

Effectuer le crawl d’un site web

Pour effectuer le crawl d’un site web et attendre la fin de l’opération, utilisez crawl.

use Evocrawl\Models\CrawlOptions;
use Evocrawl\Models\ScrapeOptions;

$job = $client->crawl(
    'https://evocrawl.com',
    CrawlOptions::with(
        limit: 50,
        maxDiscoveryDepth: 3,
        scrapeOptions: ScrapeOptions::with(formats: ['markdown']),
    )
);

echo 'Status: ' . $job->getStatus();
echo 'Progress: ' . $job->getCompleted() . '/' . $job->getTotal();

foreach ($job->getData() as $page) {
    echo $page->getMetadata()['sourceURL'] ?? '';
}

Démarrer un crawl

Lancez une tâche sans attendre avec startCrawl.

use Evocrawl\Models\CrawlOptions;

$start = $client->startCrawl(
    'https://evocrawl.com',
    CrawlOptions::with(limit: 100)
);

echo 'Job ID: ' . $start->getId();

Vérification de l’état du crawl

Consultez la progression du crawl avec getCrawlStatus.

$status = $client->getCrawlStatus($start->getId());
echo 'Status: ' . $status->getStatus();
echo 'Progress: ' . $status->getCompleted() . '/' . $status->getTotal();

Annuler un crawl

Pour annuler un crawl en cours, utilisez cancelCrawl.

$result = $client->cancelCrawl($start->getId());
print_r($result);

Erreurs de crawl

Récupérez les erreurs du crawl (le cas échéant) avec getCrawlErrors.

$errors = $client->getCrawlErrors($start->getId());
print_r($errors);

Cartographier un site web

Découvrez les liens d’un site avec map.

use Evocrawl\Models\MapOptions;

$data = $client->map(
    'https://evocrawl.com',
    MapOptions::with(
        limit: 100,
        search: 'blog',
    )
);

foreach ($data->getLinks() as $link) {
    echo ($link['url'] ?? '') . ' - ' . ($link['title'] ?? '');
}

Rechercher sur le Web

Effectuez une recherche avec des paramètres de recherche facultatifs à l’aide de search.

use Evocrawl\Models\SearchOptions;

$results = $client->search(
    'firecrawl web scraping',
    SearchOptions::with(limit: 10)
);

foreach ($results->getWeb() as $result) {
    echo ($result['title'] ?? '') . ' - ' . ($result['url'] ?? '');
}

Scraping par lots

Extrayez plusieurs URL en parallèle à l’aide de batchScrape.

use Evocrawl\Models\BatchScrapeOptions;
use Evocrawl\Models\ScrapeOptions;

$job = $client->batchScrape(
    ['https://evocrawl.com', 'https://evocrawl.com/blog'],
    BatchScrapeOptions::with(
        options: ScrapeOptions::with(formats: ['markdown']),
    )
);

foreach ($job->getData() as $doc) {
    echo $doc->getMarkdown();
}

Pour gérer manuellement l’exécution asynchrone, utilisez startBatchScrape, getBatchScrapeStatus et cancelBatchScrape :

use Evocrawl\Models\BatchScrapeOptions;
use Evocrawl\Models\ScrapeOptions;

$start = $client->startBatchScrape(
    ['https://evocrawl.com', 'https://evocrawl.com/blog'],
    BatchScrapeOptions::with(
        options: ScrapeOptions::with(formats: ['markdown']),
    )
);

$status = $client->getBatchScrapeStatus($start->getId());
echo 'Batch status: ' . $status->getStatus();

$cancel = $client->cancelBatchScrape($start->getId());
print_r($cancel);

Agent

Exécutez un agent propulsé par l’IA avec agent.

use Evocrawl\Models\AgentOptions;

$result = $client->agent(
    AgentOptions::with(
        prompt: 'Find the pricing plans for Evocrawl and compare them',
    )
);

print_r($result->getData());

Avec un schéma JSON pour une sortie structurée :

use Evocrawl\Models\AgentOptions;

$result = $client->agent(
    AgentOptions::with(
        prompt: 'Extract pricing plan details',
        urls: ['https://evocrawl.com'],
        schema: [
            'type' => 'object',
            'properties' => [
                'plans' => [
                    'type' => 'array',
                    'items' => [
                        'type' => 'object',
                        'properties' => [
                            'name' => ['type' => 'string'],
                            'price' => ['type' => 'string'],
                        ],
                    ],
                ],
            ],
        ],
    )
);

print_r($result->getData());

Pour gérer manuellement l’exécution asynchrone, utilisez startAgent, getAgentStatus et cancelAgent :

use Evocrawl\Models\AgentOptions;

$start = $client->startAgent(
    AgentOptions::with(
        prompt: 'Summarize what Evocrawl does in one sentence',
        urls: ['https://evocrawl.com'],
    )
);

$status = $client->getAgentStatus($start->getId());
echo 'Agent status: ' . $status->getStatus();

$cancel = $client->cancelAgent($start->getId());
print_r($cancel);

Utilisation & métriques

Consultez la concurrence et les crédits restants :

use Evocrawl\Models\ConcurrencyCheck;
use Evocrawl\Models\CreditUsage;

$concurrency = $client->getConcurrency();
echo 'Concurrency: ' . $concurrency->getConcurrency() . '/' . $concurrency->getMaxConcurrency();

$credits = $client->getCreditUsage();
echo 'Remaining credits: ' . $credits->getRemainingCredits();

Browser

Le SDK PHP inclut des utilitaires Browser Sandbox.

Créer une session

use Evocrawl\Models\BrowserCreateResponse;

$session = $client->browser(ttl: 120, activityTtl: 60, streamWebView: true);
echo $session->getId();
echo $session->getCdpUrl();
echo $session->getLiveViewUrl();

Exécuter du code

use Evocrawl\Models\BrowserExecuteResponse;

$run = $client->browserExecute(
    sessionId: $session->getId(),
    code: 'await page.goto("https://example.com"); console.log(await page.title());',
    language: 'node',
    timeout: 60,
);

echo $run->getStdout();
echo $run->getExitCode();

Session interactive liée au scraping

Utilisez l’ID d’une tâche de scraping pour exécuter du code navigateur supplémentaire dans le même contexte rejoué :

interact(...) exécute du code dans la session de navigateur liée au scraping (et l’initialise lors de la première utilisation).
stopInteractiveBrowser(...) arrête explicitement la session interactive lorsque vous avez terminé.

use Evocrawl\Models\BrowserExecuteResponse;
use Evocrawl\Models\BrowserDeleteResponse;
use Evocrawl\Models\ScrapeOptions;

$doc = $client->scrape(
    'https://example.com',
    ScrapeOptions::with(formats: ['markdown'])
);

$scrapeJobId = $doc->getMetadata()['scrapeId'] ?? null;
if ($scrapeJobId === null) {
    throw new RuntimeException('scrapeId not found in metadata');
}

$scrapeRun = $client->interact(
    jobId: $scrapeJobId,
    code: 'console.log(page.url());',
    language: 'node',
    timeout: 60,
);

echo $scrapeRun->getStdout();

$deleted = $client->stopInteractiveBrowser($scrapeJobId);
echo 'Deleted: ' . ($deleted->isSuccess() ? 'true' : 'false');

Lister et fermer les sessions

use Evocrawl\Models\BrowserListResponse;
use Evocrawl\Models\BrowserSession;

$active = $client->listBrowsers('active');
foreach ($active->getSessions() as $s) {
    echo $s->getId() . ' - ' . $s->getStatus();
}

$closed = $client->deleteBrowser($session->getId());
echo 'Closed: ' . ($closed->isSuccess() ? 'true' : 'false');

Configuration

EvocrawlClient::create() prend en charge les options suivantes :

Option	Type	Par défaut	Description
`apiKey`	`string`	variable d’environnement `FIRECRAWL_API_KEY`	Votre clé d’API Evocrawl
`apiUrl`	`string`	`https://api.evocrawl.com` (ou `FIRECRAWL_API_URL`)	URL de base de l’API
`timeoutSeconds`	`float`	`300`	Délai d’expiration de la requête HTTP, en secondes
`maxRetries`	`int`	`3`	Nombre de nouvelles tentatives automatiques en cas d’échecs temporaires
`backoffFactor`	`float`	`0.5`	Facteur de backoff exponentiel, en secondes
`httpClient`	`GuzzleHttp\ClientInterface`	Construit à partir du délai d’expiration	Client HTTP personnalisé compatible avec Guzzle

use Evocrawl\Client\EvocrawlClient;

$client = EvocrawlClient::create(
    apiKey: 'fc-your-api-key',
    apiUrl: 'https://api.evocrawl.com',
    timeoutSeconds: 300,
    maxRetries: 3,
    backoffFactor: 0.5,
);

Client HTTP personnalisé

Vous pouvez fournir une implémentation GuzzleHttp\ClientInterface préconfigurée pour contrôler le pool de connexions, le middleware, les paramètres de proxy et d’autres fonctionnalités HTTP. Lorsqu’elle est fournie, le paramètre timeoutSeconds est ignoré au profit de la configuration propre au client.

use Evocrawl\Client\EvocrawlClient;
use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient([
    'proxy' => 'http://proxy.example.com:8080',
    'timeout' => 60,
    'connect_timeout' => 10,
]);

$client = EvocrawlClient::create(
    apiKey: 'fc-your-api-key',
    httpClient: $guzzle,
);

Gestion des erreurs

Le SDK génère des exceptions d’exécution sous Evocrawl\Exceptions.

use Evocrawl\Exceptions\AuthenticationException;
use Evocrawl\Exceptions\EvocrawlException;
use Evocrawl\Exceptions\JobTimeoutException;
use Evocrawl\Exceptions\RateLimitException;

try {
    $doc = $client->scrape('https://example.com');
} catch (AuthenticationException $e) {
    echo 'Auth failed: ' . $e->getMessage();
} catch (RateLimitException $e) {
    echo 'Rate limited: ' . $e->getMessage();
} catch (JobTimeoutException $e) {
    echo 'Job ' . $e->getJobId() . ' timed out after ' . $e->getTimeoutSeconds() . 's';
} catch (EvocrawlException $e) {
    echo 'Error ' . $e->getStatusCode() . ': ' . $e->getMessage();
}

Vous êtes un agent IA et vous avez besoin d’une clé API Evocrawl ? Consultez evocrawl.com/agent-onboarding/SKILL.md pour la procédure d’intégration automatisée.

Global

Officiel

PHP

Installation

Intégration Laravel

Utilisation

Utiliser la façade Laravel

Scraping d’une URL

Extraction de JSON

Effectuer le crawl d’un site web

Démarrer un crawl

Vérification de l’état du crawl

Annuler un crawl

Erreurs de crawl

Cartographier un site web

Rechercher sur le Web

Scraping par lots

Agent

Utilisation & métriques

Browser

Créer une session

Exécuter du code

Session interactive liée au scraping

Lister et fermer les sessions

Configuration

Client HTTP personnalisé

Gestion des erreurs

Global

Officiel

​Installation

​Intégration Laravel

​Utilisation

​Utiliser la façade Laravel

​Scraping d’une URL

​Extraction de JSON

​Effectuer le crawl d’un site web

​Démarrer un crawl

​Vérification de l’état du crawl

​Annuler un crawl

​Erreurs de crawl

​Cartographier un site web

​Rechercher sur le Web

​Scraping par lots

​Agent

​Utilisation & métriques

​Browser

​Créer une session

​Exécuter du code

​Session interactive liée au scraping

​Lister et fermer les sessions

​Configuration

​Client HTTP personnalisé

​Gestion des erreurs

Installation

Intégration Laravel

Utilisation

Utiliser la façade Laravel

Scraping d’une URL

Extraction de JSON

Effectuer le crawl d’un site web

Démarrer un crawl

Vérification de l’état du crawl

Annuler un crawl

Erreurs de crawl

Cartographier un site web

Rechercher sur le Web

Scraping par lots

Agent

Utilisation & métriques

Browser

Créer une session

Exécuter du code

Session interactive liée au scraping

Lister et fermer les sessions

Configuration

Client HTTP personnalisé

Gestion des erreurs