Skip to content
Firecrawl Docs
Firecrawl Docs
Oficial

PHP

O SDK PHP do Firecrawl é um wrapper da API do Firecrawl para ajudar você a converter websites em markdown com facilidade.

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.

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ávelPadrãoDescrição
FIRECRAWL_API_KEY—Sua chave de API do Firecrawl (obrigatória)
FIRECRAWL_API_URLhttps://api.firecrawl.devURL base da API
FIRECRAWL_TIMEOUT300Tempo limite da requisição HTTP em segundos
FIRECRAWL_MAX_RETRIES3Novas tentativas automáticas para falhas transitórias
FIRECRAWL_BACKOFF_FACTOR0.5Fator de backoff exponencial em segundos
  1. Obtenha uma chave de API em firecrawl.dev
  2. 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());

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

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'] ?? '';

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

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'] ?? '';
}

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

Verifique o andamento do rastreamento com getCrawlStatus.

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

Cancele um rastreamento em execução com cancelCrawl.

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

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

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

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'] ?? '');
}

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'] ?? '');
}

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

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

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

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?');
ClassNome da ferramentaO que faz
FirecrawlScrapefirecrawl_scrapeFaz scraping de uma URL e retorna markdown limpo
FirecrawlSearchfirecrawl_searchFaz uma busca na web e retorna resultados em JSON
FirecrawlMapfirecrawl_mapDescobre as URLs em um site
FirecrawlCrawlfirecrawl_crawlFaz 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);

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

ToolParameterDescription
firecrawl_scrapeurl (required)URL absoluta da página para fazer scraping, incluindo o protocolo
firecrawl_searchquery (required)A query de busca
limitNúmero máximo de resultados a retornar, de 1 a 20. O padrão é 5
firecrawl_mapurl (required)URL base do website a ser mapeado
searchTermo opcional para filtrar as URLs descobertas por relevância
limitNúmero máximo de URLs a retornar, de 1 a 500. O padrão é 100
firecrawl_crawlurl (required)URL a partir da qual iniciar o rastreamento
limitNú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.

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.

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;
}

O SDK PHP inclui utilitários do Browser Sandbox.

use Firecrawl\Models\BrowserCreateResponse;

$session = $client->browser(ttl: 120, activityTtl: 60, streamWebView: true);
echo $session->getId();
echo $session->getCdpUrl();
echo $session->getLiveViewUrl();
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();

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

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

OpçãoTipoPadrãoDescrição
apiKeystringvariável de ambiente FIRECRAWL_API_KEYSua Firecrawl chave de API
apiUrlstringhttps://api.firecrawl.dev (ou FIRECRAWL_API_URL)URL base da API
timeoutSecondsfloat300tempo limite da requisição HTTP, em segundos
maxRetriesint3novas tentativas automáticas para falhas transitórias
backoffFactorfloat0.5fator de recuo exponencial, em segundos
httpClientGuzzleHttp\ClientInterfaceCriado com base no tempo limiteCliente 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,
);

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

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.

Was this page helpful?Suggest editsRaise issue
Previous.NETNextElixir

On this page

InstalaçãoIntegração com LaravelUsoUsando a facade do LaravelScraping de uma URLExtração JSONFazer o rastreamento de um siteIniciar um rastreamentoVerificando o status do rastreamentoCancelar um rastreamentoErros de rastreamentoMapear um siteBuscando na webScraping em loteAgenteUso & MétricasFerramentas do Laravel AI SDKFerramentas disponíveisParâmetros da ferramentaComportamento da FerramentaResultados do rastreamentoBrowserCriar uma sessãoExecutar códigoSessão interativa vinculada ao scrapingListar & encerrar sessõesConfiguraçãoCliente HTTP personalizadoTratamento de erros