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

> El SDK de PHP de Firecrawl es un wrapper de la API de Firecrawl que te ayuda a convertir sitios web en markdown fácilmente.

<h2 id="installation">
  Instalación
</h2>

El SDK oficial de PHP se mantiene en el monorepo de Firecrawl, en [apps/php-sdk](https://github.com/firecrawl/firecrawl/tree/main/apps/php-sdk).

Para instalar el SDK de PHP de Firecrawl, añade la dependencia con Composer:

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

<Note>Requiere PHP 8.1 o superior.</Note>

<h3 id="laravel-integration">
  Integración con Laravel
</h3>

El SDK incluye soporte nativo para Laravel con autodetección. Después de instalar el paquete, publica el archivo de configuración:

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

A continuación, agrega tu clave de API al archivo `.env`:

```env theme={null}
FIRECRAWL_API_KEY=fc-your-api-key
```

Se admiten las siguientes variables de entorno:

| Variable | Predeterminado | Descripción |
| - | - | - |
| `FIRECRAWL_API_KEY` | — | Tu clave de API de Firecrawl (obligatoria) |
| `FIRECRAWL_API_URL` | `https://api.firecrawl.dev` | URL base de la API |
| `FIRECRAWL_TIMEOUT` | `300` | Tiempo de espera de la solicitud HTTP, en segundos |
| `FIRECRAWL_MAX_RETRIES` | `3` | Reintentos automáticos para fallos transitorios |
| `FIRECRAWL_BACKOFF_FACTOR` | `0.5` | Factor de retroceso exponencial, en segundos |

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

1. Obtén una clave de API en [firecrawl.dev](https://firecrawl.dev)
2. Configura la clave de API como una variable de entorno llamada `FIRECRAWL_API_KEY`, o pásala con `FirecrawlClient::create(apiKey: ...)`

Aquí tienes un ejemplo rápido con la API actual del 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">
  Uso del facade de Laravel
</h3>

En una aplicación de Laravel, puedes utilizar el facade `Firecrawl` o la inyección de dependencias:

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

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

// Vía inyección de dependencias
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 una URL
</h3>

Para hacer scraping de una sola URL, usa el 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">
  Extracción JSON
</h4>

Extrae JSON estructurado con `JsonFormat` mediante el 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">
  Rastreo de un sitio web
</h3>

Para rastrear un sitio web y esperar a que finalice, usa `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 un rastreo
</h3>

Inicia un trabajo sin esperar con `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">
  Consultar el estado del rastreo
</h3>

Consulta el progreso del rastreo con `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 un rastreo
</h3>

Cancela un rastreo en curso con `cancelCrawl`.

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

<h3 id="crawl-errors">
  Errores de rastreo
</h3>

Consulta los errores del rastreo (si los hay) con `getCrawlErrors`.

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

<h3 id="mapping-a-website">
  Mapeo de un sitio web
</h3>

Descubre enlaces de un sitio utilizando `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">
  Buscar en la Web
</h3>

Realiza una búsqueda con ajustes de búsqueda opcionales utilizando `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 por lotes
</h3>

Realiza scraping de varias URL en paralelo con `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 la ejecución asíncrona, usa `startBatchScrape`, `getBatchScrapeStatus` y `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>

Ejecuta un agente con IA mediante `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());
```

Con un esquema JSON para una salida estructurada:

```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 controlar manualmente la ejecución asíncrona, usa `startAgent`, `getAgentStatus` y `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>

Consulta la concurrencia y los 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">
  Herramientas de Laravel AI SDK
</h2>

El SDK incluye clases de herramientas nativas para el [Laravel AI SDK](https://laravel.com/docs/ai-sdk) (`laravel/ai`), de modo que los agentes puedan hacer scraping, buscar, mapear y rastrear la web sin un MCP Server ni llamadas HTTP manuales.

```bash theme={null}
composer require laravel/ai
```

<Note>Requiere `firecrawl/firecrawl-sdk` 1.9.0 o posterior, además de `laravel/ai` 0.9 o posterior (PHP 8.3+, Laravel 12+). Las clases de las herramientas solo se cargan cuando `laravel/ai` está instalado.</Note>

Las herramientas resuelven `FirecrawlClient` desde el contenedor, por lo que se reutiliza tu configuración actual de `config/firecrawl.php` y `FIRECRAWL_API_KEY` tal cual:

```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">
  Herramientas disponibles
</h3>

| Clase | Nombre de la herramienta | Qué hace |
| - | - | - |
| `FirecrawlScrape` | `firecrawl_scrape` | Hace scraping de una URL y devuelve markdown limpio |
| `FirecrawlSearch` | `firecrawl_search` | Busca en la web y devuelve resultados en JSON |
| `FirecrawlMap` | `firecrawl_map` | Descubre las URL de un sitio web |
| `FirecrawlCrawl` | `firecrawl_crawl` | Rastrea varias páginas y las convierte en markdown |

Los nombres de las herramientas coinciden con los del Firecrawl MCP server, por lo que los agentes ven la misma terminología en todas las interfaces. Registra las cuatro a la vez con el helper spread:

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

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

Cada herramienta también acepta un cliente explícito, para credenciales puntuales o para usarlo fuera del contenedor. `FirecrawlTools::all()` se lo pasa a las cuatro herramientas:

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

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

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

<h3 id="tool-parameters">
  Parámetros de las herramientas
</h3>

Cada herramienta expone un esquema pequeño pensado para el modelo. Estos son los parámetros que el agente puede proporcionar:

| Herramienta | Parámetro | Descripción |
| - | - | - |
| `firecrawl_scrape` | `url` (obligatorio) | URL absoluta de la página a la que se le hará scraping, incluido el protocolo |
| `firecrawl_search` | `query` (obligatorio) | La consulta de búsqueda |
| | `limit` | Número máximo de resultados que se devolverán, 1–20. El valor predeterminado es 5 |
| `firecrawl_map` | `url` (obligatorio) | URL base del sitio web que se va a mapear |
| | `search` | Término opcional para filtrar las URL descubiertas por relevancia |
| | `limit` | Número máximo de URL que se devolverán, 1–500. El valor predeterminado es 100 |
| `firecrawl_crawl` | `url` (obligatorio) | URL desde la que iniciar el rastreo |
| | `limit` | Número máximo de páginas que se rastrearán, 1–25. El valor predeterminado es 5 |

Los valores de `limit` fuera de rango se ajustan al límite más cercano en lugar de rechazarse, por lo que un modelo que solicite 99 resultados de búsqueda recibirá 20 en lugar de un error.

<h3 id="tool-behavior">
  Comportamiento de la herramienta
</h3>

Los fallos de la herramienta, como límites de tasa, tiempos de espera y URL no válidas, se devuelven al modelo como cadenas de error legibles en lugar de generar excepciones, para que las ejecuciones del agente sigan funcionando de forma controlada. Las salidas se limitan para mantenerse dentro del contexto del modelo: los resultados de scraping se truncan a 80.000 caracteres, las páginas de rastreo a 15.000 caracteres cada una dentro de un presupuesto total de 100.000 caracteres por resultado completo, y los resultados de search y mapeo eliminan los elementos del final con un marcador explícito de omisión.

`firecrawl_search` y `firecrawl_map` devuelven arrays JSON de resultados. `firecrawl_scrape` devuelve la página en markdown.

<h3 id="crawl-results">
  Resultados del rastreo
</h3>

`firecrawl_crawl` espera hasta 55 segundos a que termine el rastreo y luego devuelve un objeto JSON que deja explícito el resultado. Los rastreos fallidos, cancelados o parciales siguen siendo visibles para el modelo a través del campo `status`, en lugar de truncarse sin avisar:

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

Aparecen dos campos opcionales cuando los resultados no caben: `omittedPages` cuenta las páginas omitidas para mantenerse dentro del presupuesto de salida, y `note` le indica al modelo que existen más páginas en el servidor y que debe usar un límite más bajo o hacer scraping de páginas específicas con `firecrawl_scrape`. La herramienta informa sobre la paginación en lugar de seguirla, por lo que los agentes que necesitan todas las páginas de un rastreo grande deben usar `FirecrawlClient` directamente.

Si el rastreo sigue en ejecución cuando expira la espera, la herramienta lo indica y le recuerda al modelo que el rastreo aún puede completarse del lado del servidor. Los inicios de rastreo incluyen una clave de idempotencia UUID, por lo que un reintento a nivel HTTP nunca crea un rastreo duplicado.

Si tu agente se ejecuta dentro de un trabajo en cola, mantén pequeño el límite del rastreo o aumenta el timeout del trabajo del worker. La espera, la frecuencia de poll y el límite por página son propiedades protegidas, así que extiende la clase para ajustarlas:

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

El SDK de PHP incluye funciones auxiliares para Browser Sandbox.

<h3 id="create-a-session">
  Crear una sesión
</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">
  Ejecutar 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">
  Sesión interactiva vinculada al scraping
</h3>

Usa un ID de trabajo de scraping para ejecutar código adicional del navegador en el mismo contexto reproducido:

* `interact(...)` ejecuta código en la sesión de navegador vinculada al scraping (y la inicializa la primera vez que se usa).
* `stopInteractiveBrowser(...)` detiene explícitamente la sesión interactiva cuando hayas terminado.

```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 & cerrar sesiones
</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">
  Configuración
</h2>

`FirecrawlClient::create()` admite las siguientes opciones:

| Opción | Tipo | Predeterminado | Descripción |
| - | - | - | - |
| `apiKey` | `string` | variable de entorno `FIRECRAWL_API_KEY` | Tu clave de API de Firecrawl |
| `apiUrl` | `string` | `https://api.firecrawl.dev` (o `FIRECRAWL_API_URL`) | URL base de la API |
| `timeoutSeconds` | `float` | `300` | Tiempo de espera de la solicitud HTTP en segundos |
| `maxRetries` | `int` | `3` | Reintentos automáticos para fallos transitorios |
| `backoffFactor` | `float` | `0.5` | Factor de retroceso exponencial en segundos |
| `httpClient` | `GuzzleHttp\ClientInterface` | Se crea a partir del tiempo de espera | Cliente HTTP personalizado compatible con 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>

Puedes pasar una implementación preconfigurada de `GuzzleHttp\ClientInterface` para controlar el pool de conexiones, el middleware, la configuración del proxy y otras funciones HTTP. Si se proporciona, la configuración `timeoutSeconds` se ignora y se utiliza la configuración del propio 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">
  Manejo de errores
</h2>

El SDK lanza excepciones de tiempo de ejecución en el espacio de nombres `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();
}
```

> ¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para obtener instrucciones de incorporación automática.


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