SDK PHP | Firecrawl

Installation

Le SDK PHP officiel est maintenu dans le monorepo de Firecrawl à l’emplacement apps/php-sdk. Pour installer le SDK PHP de Firecrawl, 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="Firecrawl\Laravel\FirecrawlServiceProvider"

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 Firecrawl (obligatoire)
`FIRECRAWL_API_URL`	`https://api.firecrawl.dev`	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 firecrawl.dev
Définissez la clé API comme variable d’environnement nommée FIRECRAWL_API_KEY, ou passez-la à FirecrawlClient::create(apiKey: ...)

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

use Firecrawl\Client\FirecrawlClient;
use Firecrawl\Models\CrawlOptions;
use Firecrawl\Models\ScrapeOptions;

$client = FirecrawlClient::fromEnv();

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

$crawl = $client->crawl(
    'https://firecrawl.dev',
    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 Firecrawl ou l’injection de dépendances :

use Firecrawl\Client\FirecrawlClient;
use Firecrawl\Laravel\Facades\Firecrawl;

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

// Via injection de dépendances
class ScrapeController
{
    public function __construct(
        private readonly FirecrawlClient $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 Firecrawl\Models\Document;
use Firecrawl\Models\ScrapeOptions;

$doc = $client->scrape(
    'https://firecrawl.dev',
    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 Firecrawl\Models\JsonFormat;
use Firecrawl\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 Firecrawl\Models\CrawlOptions;
use Firecrawl\Models\ScrapeOptions;

$job = $client->crawl(
    'https://firecrawl.dev',
    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 Firecrawl\Models\CrawlOptions;

$start = $client->startCrawl(
    'https://firecrawl.dev',
    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 Firecrawl\Models\MapOptions;

$data = $client->map(
    'https://firecrawl.dev',
    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 Firecrawl\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 Firecrawl\Models\BatchScrapeOptions;
use Firecrawl\Models\ScrapeOptions;

$job = $client->batchScrape(
    ['https://firecrawl.dev', 'https://firecrawl.dev/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 Firecrawl\Models\BatchScrapeOptions;
use Firecrawl\Models\ScrapeOptions;

$start = $client->startBatchScrape(
    ['https://firecrawl.dev', 'https://firecrawl.dev/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 Firecrawl\Models\AgentOptions;

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

print_r($result->getData());

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

use Firecrawl\Models\AgentOptions;

$result = $client->agent(
    AgentOptions::with(
        prompt: 'Extract pricing plan details',
        urls: ['https://firecrawl.dev'],
        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 Firecrawl\Models\AgentOptions;

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

$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 Firecrawl\Models\ConcurrencyCheck;
use Firecrawl\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 Firecrawl\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 Firecrawl\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 Firecrawl\Models\BrowserExecuteResponse;
use Firecrawl\Models\BrowserDeleteResponse;
use Firecrawl\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 Firecrawl\Models\BrowserListResponse;
use Firecrawl\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

FirecrawlClient::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 Firecrawl
`apiUrl`	`string`	`https://api.firecrawl.dev` (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 Firecrawl\Client\FirecrawlClient;

$client = FirecrawlClient::create(
    apiKey: 'fc-your-api-key',
    apiUrl: 'https://api.firecrawl.dev',
    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 Firecrawl\Client\FirecrawlClient;
use GuzzleHttp\Client as GuzzleClient;

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

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

Gestion des erreurs

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

use Firecrawl\Exceptions\AuthenticationException;
use Firecrawl\Exceptions\FirecrawlException;
use Firecrawl\Exceptions\JobTimeoutException;
use Firecrawl\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 (FirecrawlException $e) {
    echo 'Error ' . $e->getStatusCode() . ': ' . $e->getMessage();
}

Vous êtes un agent IA et vous avez besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/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

​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