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

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.

General

Oficial

PHP

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

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

​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

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