SDK PHP | Firecrawl

Instalação

O SDK oficial SDK PHP do Firecrawl é mantido no monorepo do Firecrawl em apps/php-sdk. Para instalar o SDK PHP do Firecrawl, adicione a dependência via Composer:

composer require firecrawl/firecrawl-sdk

Requer PHP 8.1 ou superior.

Integração com Laravel

O SDK inclui suporte nativo ao Laravel com autodiscovery. Após instalar o pacote, publique o arquivo de configuração:

php artisan vendor:publish --provider="Firecrawl\Laravel\FirecrawlServiceProvider"

Em seguida, adicione sua chave de API ao arquivo .env:

FIRECRAWL_API_KEY=fc-your-api-key

As seguintes variáveis de ambiente são suportadas:

Variável	Padrão	Descrição
`FIRECRAWL_API_KEY`	—	Sua chave de API do Firecrawl (obrigatória)
`FIRECRAWL_API_URL`	`https://api.firecrawl.dev`	URL base da API
`FIRECRAWL_TIMEOUT`	`300`	Tempo limite da requisição HTTP em segundos
`FIRECRAWL_MAX_RETRIES`	`3`	Novas tentativas automáticas para falhas transitórias
`FIRECRAWL_BACKOFF_FACTOR`	`0.5`	Fator de backoff exponencial em segundos

Uso

Obtenha uma chave de API em firecrawl.dev
Defina a chave de API como uma variável de ambiente chamada FIRECRAWL_API_KEY ou passe-a em FirecrawlClient::create(apiKey: ...)

Aqui está um exemplo rápido com a API atual do 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());

Usando a facade do Laravel

Em uma aplicação Laravel, você pode usar a facade Firecrawl ou a injeção de dependência:

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

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

// Via Injeção de Dependência
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 de uma URL

Para fazer scraping de uma única URL, use o método 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'] ?? '';

Extração JSON

Extraia JSON estruturado com JsonFormat usando o endpoint 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());

Fazer o rastreamento de um site

Para rastrear um site e aguardar a conclusão, use 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'] ?? '';
}

Iniciar um rastreamento

Inicie um job sem aguardar com startCrawl.

use Firecrawl\Models\CrawlOptions;

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

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

Verificando o status do rastreamento

Verifique o andamento do rastreamento com getCrawlStatus.

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

Cancelar um rastreamento

Cancele um rastreamento em execução com cancelCrawl.

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

Erros de rastreamento

Recupere erros no nível do rastreamento (se houver) com getCrawlErrors.

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

Mapear um site

Descubra links de um site com 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'] ?? '');
}

Buscando na web

Faça buscas com configurações opcionais de busca usando 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 em lote

Faça o scraping de várias URLs em paralelo com 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();
}

Para controlar manualmente a execução assíncrona, use startBatchScrape, getBatchScrapeStatus e 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);

Agente

Execute um agente de IA com agent.

use Firecrawl\Models\AgentOptions;

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

print_r($result->getData());

Com um schema JSON para um resultado estruturado:

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());

Para controle assíncrono manual, use startAgent, getAgentStatus e 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);

Uso & Métricas

Confira a concorrência e os créditos restantes:

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();

Ferramentas do Laravel AI SDK

O SDK inclui classes de ferramentas nativas para o Laravel AI SDK (laravel/ai), para que agentes possam fazer scraping, buscar, mapear e rastrear a web sem precisar de um MCP Server nem de chamadas HTTP manuais.

composer require laravel/ai

Requer firecrawl/firecrawl-sdk 1.9.0 ou superior, além de laravel/ai 0.9 ou superior (PHP 8.3+, Laravel 12+). As classes das ferramentas só são carregadas quando laravel/ai está instalado.

As ferramentas resolvem o FirecrawlClient no contêiner, então a configuração existente de config/firecrawl.php e FIRECRAWL_API_KEY é reutilizada como está:

use Firecrawl\Laravel\Tools\FirecrawlScrape;
use Firecrawl\Laravel\Tools\FirecrawlSearch;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Stringable;

class ResearchAssistant implements Agent, HasTools
{
    use Promptable;

    public function instructions(): Stringable|string
    {
        return 'You are a research assistant. Use the Firecrawl tools to find and read web content.';
    }

    public function tools(): iterable
    {
        return [
            new FirecrawlScrape,
            new FirecrawlSearch,
        ];
    }
}

$response = ResearchAssistant::make()->prompt('What does firecrawl.dev do?');

Ferramentas disponíveis

Class	Nome da ferramenta	O que faz
`FirecrawlScrape`	`firecrawl_scrape`	Faz scraping de uma URL e retorna markdown limpo
`FirecrawlSearch`	`firecrawl_search`	Faz uma busca na web e retorna resultados em JSON
`FirecrawlMap`	`firecrawl_map`	Descobre as URLs em um site
`FirecrawlCrawl`	`firecrawl_crawl`	Faz o rastreamento de várias páginas em markdown

Os nomes das ferramentas correspondem ao Firecrawl MCP server, para que os agentes vejam o mesmo vocabulário em todas as interfaces. Registre as quatro de uma vez usando o helper de spread:

use Firecrawl\Laravel\Tools\FirecrawlTools;

public function tools(): iterable
{
    return [...FirecrawlTools::all()];
}

Cada ferramenta também aceita um cliente explícito, para credenciais pontuais ou para uso fora do contêiner. FirecrawlTools::all() repassa um para as quatro ferramentas:

use Firecrawl\Client\FirecrawlClient;

$client = FirecrawlClient::create(apiKey: 'fc-other-key');

new FirecrawlScrape($client);
// ou
FirecrawlTools::all($client);

Parâmetros da ferramenta

Cada ferramenta expõe um schema pequeno voltado ao modelo. Estes são os parâmetros que o agente pode passar:

Tool	Parameter	Description
`firecrawl_scrape`	`url` (required)	URL absoluta da página para fazer scraping, incluindo o protocolo
`firecrawl_search`	`query` (required)	A query de busca
	`limit`	Número máximo de resultados a retornar, de 1 a 20. O padrão é 5
`firecrawl_map`	`url` (required)	URL base do website a ser mapeado
	`search`	Termo opcional para filtrar as URLs descobertas por relevância
	`limit`	Número máximo de URLs a retornar, de 1 a 500. O padrão é 100
`firecrawl_crawl`	`url` (required)	URL a partir da qual iniciar o rastreamento
	`limit`	Número máximo de páginas para rastrear, de 1 a 25. O padrão é 5

Valores de limit fora do intervalo são ajustados para o limite válido mais próximo, em vez de serem rejeitados. Assim, um modelo que solicitar 99 resultados de busca receberá 20 em vez de um erro.

Comportamento da Ferramenta

Falhas da ferramenta, como limites de taxa, tempos limite e URLs inválidas, são retornadas ao modelo como strings de erro legíveis, em vez de serem lançadas como exceção, para que as execuções do agente falhem de forma controlada. Os resultados são limitados para caber no contexto do modelo: os resultados de scraping são truncados em 80.000 caracteres, as páginas de rastreamento em 15.000 caracteres cada, dentro de um limite total de 100.000 caracteres para o resultado, e os resultados de busca e mapeamento descartam os itens finais com um marcador explícito de omissão. firecrawl_search e firecrawl_map retornam arrays JSON de resultados. firecrawl_scrape retorna a página em markdown.

Resultados do rastreamento

firecrawl_crawl aguarda até 55 segundos pela conclusão do rastreamento e então retorna um objeto JSON que deixa o resultado explícito. Rastreamentos com falha, cancelados ou parciais continuam visíveis para o modelo por meio do campo status, em vez de serem truncados sem aviso:

{
  "status": "completed",
  "completed": 5,
  "total": 5,
  "pages": [
    { "url": "https://example.com/docs", "markdown": "..." }
  ]
}

Dois campos opcionais aparecem quando os resultados não cabem: omittedPages conta as páginas descartadas para manter o resultado dentro do orçamento de saída, e note informa ao modelo que há mais páginas no servidor e que ele deve usar um limite menor ou fazer scraping de páginas específicas com firecrawl_scrape. A ferramenta informa a paginação em vez de segui-la, então agentes que precisam de todas as páginas de um rastreamento grande devem usar FirecrawlClient diretamente. Se o rastreamento ainda estiver em execução quando o tempo de espera expirar, a ferramenta informa isso e lembra ao modelo que o rastreamento ainda pode ser concluído no servidor. Os inícios de rastreamento usam uma chave de idempotência UUID, então uma nova tentativa no nível HTTP nunca cria um rastreamento duplicado. Se o seu agente estiver sendo executado em um job enfileirado, mantenha o limite de rastreamento baixo ou aumente o tempo limite do job do worker. O tempo de espera, a cadência de consulta e o limite por página são propriedades protegidas, então estenda a classe para ajustá-los:

use Firecrawl\Laravel\Tools\FirecrawlCrawl;

class PatientCrawl extends FirecrawlCrawl
{
    protected int $timeoutSeconds = 120;
    protected int $pollIntervalSeconds = 5;
    protected int $pageCharacterLimit = 30000;
}

Browser

O SDK PHP inclui utilitários do Browser Sandbox.

Criar uma sessão

use Firecrawl\Models\BrowserCreateResponse;

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

Executar código

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();

Sessão interativa vinculada ao scraping

Use o ID do job de scraping para executar código adicional no navegador no mesmo contexto reproduzido:

interact(...) executa código na sessão do navegador vinculada ao scraping (e a inicializa no primeiro uso).
stopInteractiveBrowser(...) interrompe explicitamente a sessão interativa quando você terminar.

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');

Listar & encerrar sessões

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');

Configuração

FirecrawlClient::create() oferece suporte às seguintes options:

Opção	Tipo	Padrão	Descrição
`apiKey`	`string`	variável de ambiente `FIRECRAWL_API_KEY`	Sua Firecrawl chave de API
`apiUrl`	`string`	`https://api.firecrawl.dev` (ou `FIRECRAWL_API_URL`)	URL base da API
`timeoutSeconds`	`float`	`300`	tempo limite da requisição HTTP, em segundos
`maxRetries`	`int`	`3`	novas tentativas automáticas para falhas transitórias
`backoffFactor`	`float`	`0.5`	fator de recuo exponencial, em segundos
`httpClient`	`GuzzleHttp\ClientInterface`	Criado com base no tempo limite	Cliente HTTP personalizado compatível com 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,
);

Cliente HTTP personalizado

Você pode passar uma implementação GuzzleHttp\ClientInterface pré-configurada para controlar o pooling de conexões, middleware, configurações de proxy e outros recursos HTTP. Quando esse cliente é fornecido, a configuração timeoutSeconds é ignorada em favor da configuração do próprio cliente.

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,
);

Tratamento de erros

O SDK lança exceções em tempo de execução no namespace 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();
}

Você é um agente de IA que precisa de uma chave de API do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para ver as instruções de onboarding automatizado.

​Instalação

​Integração com Laravel

​Uso

​Usando a facade do Laravel

​Scraping de uma URL

​Extração JSON

​Fazer o rastreamento de um site

​Iniciar um rastreamento

​Verificando o status do rastreamento

​Cancelar um rastreamento

​Erros de rastreamento

​Mapear um site

​Buscando na web

​Scraping em lote

​Agente

​Uso & Métricas

​Ferramentas do Laravel AI SDK

​Ferramentas disponíveis

​Parâmetros da ferramenta

​Comportamento da Ferramenta

​Resultados do rastreamento

​Browser

​Criar uma sessão

​Executar código

​Sessão interativa vinculada ao scraping

​Listar & encerrar sessões

​Configuração

​Cliente HTTP personalizado

​Tratamento de erros

Instalação

Integração com Laravel

Uso

Usando a facade do Laravel

Scraping de uma URL

Extração JSON

Fazer o rastreamento de um site

Iniciar um rastreamento

Verificando o status do rastreamento

Cancelar um rastreamento

Erros de rastreamento

Mapear um site

Buscando na web

Scraping em lote

Agente

Uso & Métricas

Ferramentas do Laravel AI SDK

Ferramentas disponíveis

Parâmetros da ferramenta

Comportamento da Ferramenta

Resultados do rastreamento

Browser

Criar uma sessão

Executar código

Sessão interativa vinculada ao scraping

Listar & encerrar sessões

Configuração

Cliente HTTP personalizado

Tratamento de erros