PHP - Firecrawl Docs

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

Note

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ênciaclass 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

Note

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);// ouFirecrawlTools::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.