Skip to main content

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:
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:
A continuación, agrega tu clave de API al archivo .env:
Se admiten las siguientes variables de entorno:

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:

Uso del facade de Laravel

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

Scraping de una URL

Para hacer scraping de una sola URL, usa el método scrape.

Extracción JSON

Extrae JSON estructurado con JsonFormat mediante el endpoint scrape:

Rastreo de un sitio web

Para rastrear un sitio web y esperar a que finalice, usa crawl.

Iniciar un rastreo

Inicia un trabajo sin esperar con startCrawl.

Consultar el estado del rastreo

Consulta el progreso del rastreo con getCrawlStatus.

Cancelar un rastreo

Cancela un rastreo en curso con cancelCrawl.

Errores de rastreo

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

Mapeo de un sitio web

Descubre enlaces de un sitio utilizando map.

Buscar en la Web

Realiza una búsqueda con ajustes de búsqueda opcionales utilizando search.

Scraping por lotes

Realiza scraping de varias URL en paralelo con batchScrape.
Para controlar manualmente la ejecución asíncrona, usa startBatchScrape, getBatchScrapeStatus y cancelBatchScrape:

Agente

Ejecuta un agente con IA mediante agent.
Con un esquema JSON para una salida estructurada:
Para controlar manualmente la ejecución asíncrona, usa startAgent, getAgentStatus y cancelAgent:

Uso & métricas

Consulta la concurrencia y los créditos restantes:

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

Herramientas disponibles

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

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

Browser

El SDK de PHP incluye funciones auxiliares para Browser Sandbox.

Crear una sesión

Ejecutar código

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.

Listar & cerrar sesiones

Configuración

FirecrawlClient::create() admite las siguientes opciones:

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.

Manejo de errores

El SDK lanza excepciones de tiempo de ejecución en el espacio de nombres Firecrawl\Exceptions.
¿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.