SDK de PHP | Firecrawl

Instalación

El SDK oficial de PHP se mantiene en el monorepo de Firecrawl, en apps/php-sdk. Para instalar el SDK de PHP de Firecrawl, añade la dependencia con Composer:

composer require firecrawl/firecrawl-sdk

Requiere PHP 8.1 o superior.

Integración con Laravel

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

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

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

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

Uso

Obtén una clave de API en firecrawl.dev
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:

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

Uso del facade de Laravel

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

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

Scraping de una URL

Para hacer scraping de una sola URL, usa el 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'] ?? '';

Extracción JSON

Extrae JSON estructurado con JsonFormat mediante el 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());

Rastreo de un sitio web

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

Inicia un trabajo sin esperar con startCrawl.

use Firecrawl\Models\CrawlOptions;

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

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

Consultar el estado del rastreo

Consulta el progreso del rastreo con getCrawlStatus.

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

Cancelar un rastreo

Cancela un rastreo en curso con cancelCrawl.

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

Errores de rastreo

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

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

Mapeo de un sitio web

Descubre enlaces de un sitio utilizando 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'] ?? '');
}

Buscar en la Web

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

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

Ejecuta un agente con IA mediante agent.

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:

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:

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

Consulta la concurrencia y los 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();

Herramientas de Laravel AI SDK

El SDK incluye clases de herramientas nativas para el Laravel 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.

composer require laravel/ai

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.

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:

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

Herramientas disponibles

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:

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:

use Firecrawl\Client\FirecrawlClient;

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

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

Parámetros de las herramientas

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.

Comportamiento de la herramienta

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.

Resultados del rastreo

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:

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

use Firecrawl\Laravel\Tools\FirecrawlCrawl;

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

Browser

El SDK de PHP incluye funciones auxiliares para Browser Sandbox.

Crear una sesión

use Firecrawl\Models\BrowserCreateResponse;

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

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

Sesión interactiva vinculada al scraping

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.

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 & cerrar sesiones

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

Configuración

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

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

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.

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

Manejo de errores

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

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

​Instalación

​Integración con Laravel

​Uso

​Uso del facade de Laravel

​Scraping de una URL

​Extracción JSON

​Rastreo de un sitio web

​Iniciar un rastreo

​Consultar el estado del rastreo

​Cancelar un rastreo

​Errores de rastreo

​Mapeo de un sitio web

​Buscar en la Web

​Scraping por lotes

​Agente

​Uso & métricas

​Herramientas de Laravel AI SDK

​Herramientas disponibles

​Parámetros de las herramientas

​Comportamiento de la herramienta

​Resultados del rastreo

​Browser

​Crear una sesión

​Ejecutar código

​Sesión interactiva vinculada al scraping

​Listar & cerrar sesiones

​Configuración

​Cliente HTTP personalizado

​Manejo de errores

Instalación

Integración con Laravel

Uso

Uso del facade de Laravel

Scraping de una URL

Extracción JSON

Rastreo de un sitio web

Iniciar un rastreo

Consultar el estado del rastreo

Cancelar un rastreo

Errores de rastreo

Mapeo de un sitio web

Buscar en la Web

Scraping por lotes

Agente

Uso & métricas

Herramientas de Laravel AI SDK

Herramientas disponibles

Parámetros de las herramientas

Comportamiento de la herramienta

Resultados del rastreo

Browser

Crear una sesión

Ejecutar código

Sesión interactiva vinculada al scraping

Listar & cerrar sesiones

Configuración

Cliente HTTP personalizado

Manejo de errores