> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-ul56gh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP

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

<h2 id="installation">
  Instalação
</h2>

O SDK oficial SDK PHP do Firecrawl é mantido no monorepo do Firecrawl em [apps/php-sdk](https://github.com/firecrawl/firecrawl/tree/main/apps/php-sdk).

Para instalar o SDK PHP do Firecrawl, adicione a dependência via Composer:

```bash theme={null}
composer require firecrawl/firecrawl-sdk
```

<Note>Requer PHP 8.1 ou superior.</Note>

<h3 id="laravel-integration">
  Integração com Laravel
</h3>

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

```bash theme={null}
php artisan vendor:publish --provider="Firecrawl\Laravel\FirecrawlServiceProvider"
```

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

```env theme={null}
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 |

<h2 id="usage">
  Uso
</h2>

1. Obtenha uma chave de API em [firecrawl.dev](https://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:

```php theme={null}
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());
```

<h3 id="using-the-laravel-facade">
  Usando a facade do Laravel
</h3>

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

```php theme={null}
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()]);
    }
}
```

<h3 id="scraping-a-url">
  Scraping de uma URL
</h3>

Para fazer scraping de uma única URL, use o método `scrape`.

```php theme={null}
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'] ?? '';
```

<h4 id="json-extraction">
  Extração JSON
</h4>

Extraia JSON estruturado com `JsonFormat` usando o endpoint `scrape`:

```php theme={null}
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());
```

<h3 id="crawling-a-website">
  Fazer o rastreamento de um site
</h3>

Para rastrear um site e aguardar a conclusão, use `crawl`.

```php theme={null}
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'] ?? '';
}
```

<h3 id="start-a-crawl">
  Iniciar um rastreamento
</h3>

Inicie um job sem aguardar com `startCrawl`.

```php theme={null}
use Firecrawl\Models\CrawlOptions;

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

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

<h3 id="checking-crawl-status">
  Verificando o status do rastreamento
</h3>

Verifique o andamento do rastreamento com `getCrawlStatus`.

```php theme={null}
$status = $client->getCrawlStatus($start->getId());
echo 'Status: ' . $status->getStatus();
echo 'Progress: ' . $status->getCompleted() . '/' . $status->getTotal();
```

<h3 id="cancelling-a-crawl">
  Cancelar um rastreamento
</h3>

Cancele um rastreamento em execução com `cancelCrawl`.

```php theme={null}
$result = $client->cancelCrawl($start->getId());
print_r($result);
```

<h3 id="crawl-errors">
  Erros de rastreamento
</h3>

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

```php theme={null}
$errors = $client->getCrawlErrors($start->getId());
print_r($errors);
```

<h3 id="mapping-a-website">
  Mapear um site
</h3>

Descubra links de um site com `map`.

```php theme={null}
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'] ?? '');
}
```

<h3 id="searching-the-web">
  Buscando na web
</h3>

Faça buscas com configurações opcionais de busca usando `search`.

```php theme={null}
use Firecrawl\Models\SearchOptions;

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

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

<h3 id="batch-scraping">
  Scraping em lote
</h3>

Faça o scraping de várias URLs em paralelo com `batchScrape`.

```php theme={null}
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`:

```php theme={null}
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);
```

<h3 id="agent">
  Agente
</h3>

Execute um agente de IA com `agent`.

```php theme={null}
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:

```php theme={null}
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`:

```php theme={null}
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);
```

<h3 id="usage-metrics">
  Uso & Métricas
</h3>

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

```php theme={null}
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();
```

<h2 id="laravel-ai-sdk-tools">
  Ferramentas do Laravel AI SDK
</h2>

O SDK inclui classes de ferramentas nativas para o [Laravel AI SDK](https://laravel.com/docs/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.

```bash theme={null}
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.</Note>

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á:

```php theme={null}
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?');
```

<h3 id="available-tools">
  Ferramentas disponíveis
</h3>

| 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:

```php theme={null}
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:

```php theme={null}
use Firecrawl\Client\FirecrawlClient;

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

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

<h3 id="tool-parameters">
  Parâmetros da ferramenta
</h3>

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.

<h3 id="tool-behavior">
  Comportamento da Ferramenta
</h3>

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.

<h3 id="crawl-results">
  Resultados do rastreamento
</h3>

`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:

```json theme={null}
{
  "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:

```php theme={null}
use Firecrawl\Laravel\Tools\FirecrawlCrawl;

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

<h2 id="browser">
  Browser
</h2>

O SDK PHP inclui utilitários do Browser Sandbox.

<h3 id="create-a-session">
  Criar uma sessão
</h3>

```php theme={null}
use Firecrawl\Models\BrowserCreateResponse;

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

<h3 id="execute-code">
  Executar código
</h3>

```php theme={null}
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();
```

<h3 id="scrape-bound-interactive-session">
  Sessão interativa vinculada ao scraping
</h3>

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.

```php theme={null}
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');
```

<h3 id="list-close-sessions">
  Listar & encerrar sessões
</h3>

```php theme={null}
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');
```

<h2 id="configuration">
  Configuração
</h2>

`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 |

```php theme={null}
use Firecrawl\Client\FirecrawlClient;

$client = FirecrawlClient::create(
    apiKey: 'fc-your-api-key',
    apiUrl: 'https://api.firecrawl.dev',
    timeoutSeconds: 300,
    maxRetries: 3,
    backoffFactor: 0.5,
);
```

<h3 id="custom-http-client">
  Cliente HTTP personalizado
</h3>

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.

```php theme={null}
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,
);
```

<h2 id="error-handling">
  Tratamento de erros
</h2>

O SDK lança exceções em tempo de execução no namespace `Firecrawl\Exceptions`.

```php theme={null}
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](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver as instruções de onboarding automatizado.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.