Saltar al contenido principal

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:
VariablePredeterminadoDescripción
FIRECRAWL_API_KEYTu clave de API de Firecrawl (obligatoria)
FIRECRAWL_API_URLhttps://api.firecrawl.devURL base de la API
FIRECRAWL_TIMEOUT300Tiempo de espera de la solicitud HTTP, en segundos
FIRECRAWL_MAX_RETRIES3Reintentos automáticos para fallos transitorios
FIRECRAWL_BACKOFF_FACTOR0.5Factor de retroceso exponencial, en segundos

Uso

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

ClaseNombre de la herramientaQué hace
FirecrawlScrapefirecrawl_scrapeHace scraping de una URL y devuelve markdown limpio
FirecrawlSearchfirecrawl_searchBusca en la web y devuelve resultados en JSON
FirecrawlMapfirecrawl_mapDescubre las URL de un sitio web
FirecrawlCrawlfirecrawl_crawlRastrea 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:
HerramientaParámetroDescripción
firecrawl_scrapeurl (obligatorio)URL absoluta de la página a la que se le hará scraping, incluido el protocolo
firecrawl_searchquery (obligatorio)La consulta de búsqueda
limitNúmero máximo de resultados que se devolverán, 1–20. El valor predeterminado es 5
firecrawl_mapurl (obligatorio)URL base del sitio web que se va a mapear
searchTérmino opcional para filtrar las URL descubiertas por relevancia
limitNúmero máximo de URL que se devolverán, 1–500. El valor predeterminado es 100
firecrawl_crawlurl (obligatorio)URL desde la que iniciar el rastreo
limitNú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ónTipoPredeterminadoDescripción
apiKeystringvariable de entorno FIRECRAWL_API_KEYTu clave de API de Firecrawl
apiUrlstringhttps://api.firecrawl.dev (o FIRECRAWL_API_URL)URL base de la API
timeoutSecondsfloat300Tiempo de espera de la solicitud HTTP en segundos
maxRetriesint3Reintentos automáticos para fallos transitorios
backoffFactorfloat0.5Factor de retroceso exponencial en segundos
httpClientGuzzleHttp\ClientInterfaceSe crea a partir del tiempo de esperaCliente 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.