PHP - Firecrawl Docs

安装#

官方 PHP SDK 在 Firecrawl 的 monorepo 中维护，位于 apps/php-sdk。

要安装 Firecrawl PHP SDK，请通过 Composer 添加此依赖：

composer require firecrawl/firecrawl-sdk

Note

需要 PHP 8.1 或更高版本。

Laravel 集成#

该 SDK 提供对 Laravel 的原生支持，并支持自动发现。安装该软件包后，请发布配置文件：

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

然后将你的 API 密钥添加到 .env 文件中：

FIRECRAWL_API_KEY=fc-your-api-key

支持以下环境变量：

变量	默认值	描述
`FIRECRAWL_API_KEY`	—	你的 Firecrawl API 密钥 (必填)
`FIRECRAWL_API_URL`	`https://api.firecrawl.dev`	API 基础 URL
`FIRECRAWL_TIMEOUT`	`300`	HTTP 请求超时时间 (秒)
`FIRECRAWL_MAX_RETRIES`	`3`	临时故障时的自动重试次数
`FIRECRAWL_BACKOFF_FACTOR`	`0.5`	指数退避系数 (秒)

使用方式#

从 firecrawl.dev 获取 API 密钥
将 API 密钥设置为名为 FIRECRAWL_API_KEY 的环境变量，或通过 FirecrawlClient::create(apiKey: ...) 传入 API 密钥

以下是一个基于当前 SDK API 的简要示例：

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

使用 Laravel 门面#

在 Laravel 应用中，可以使用 Firecrawl 门面，或通过依赖注入：

use Firecrawl\Client\FirecrawlClient;use Firecrawl\Laravel\Facades\Firecrawl;// 通过 Facade$doc = Firecrawl::scrape('https://example.com');// 通过依赖注入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()]);    }}

抓取 URL#

如需抓取单个 URL，请使用 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'] ?? '';

JSON 提取#

通过 scrape 端点，使用 JsonFormat 提取结构化 JSON：

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

爬取网站#

要爬取网站并等待其完成，请使用 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'] ?? '';}

开始爬取#

使用 startCrawl 启动任务，无需等待。

use Firecrawl\Models\CrawlOptions;$start = $client->startCrawl(    'https://firecrawl.dev',    CrawlOptions::with(limit: 100));echo 'Job ID: ' . $start->getId();

查看爬取状态#

使用 getCrawlStatus 查看爬取进度。

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

取消爬取#

使用 cancelCrawl 取消正在进行中的爬取。

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

爬取错误#

使用 getCrawlErrors 获取爬取过程中的错误 (如有) 。

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

网站映射#

使用 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'] ?? '');}

搜索网页#

使用 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'] ?? '');}

批量抓取#

使用 batchScrape 并行抓取多个 URL。

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

如需手动控制异步流程，请使用 startBatchScrape、getBatchScrapeStatus 和 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);

代理#

使用 agent 运行 AI 代理。

use Firecrawl\Models\AgentOptions;$result = $client->agent(    AgentOptions::with(        prompt: 'Find the pricing plans for Firecrawl and compare them',    ));print_r($result->getData());

使用结构化输出的 JSON schema：

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

如需手动控制异步执行，请使用 startAgent、getAgentStatus 和 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);

使用方式与指标#

查看并发数和剩余额度：

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

Laravel AI SDK 工具#

该 SDK 内置了适用于 Laravel AI SDK (laravel/ai) 的原生工具类，因此代理无需 MCP 服务器或手动发起 HTTP 调用，即可抓取、搜索、映射和爬取网页。

composer require laravel/ai

Note

需要 firecrawl/firecrawl-sdk 1.9.0 或更高版本，以及 laravel/ai 0.9 或更高版本 (PHP 8.3+、Laravel 12+) 。这些工具类仅在安装了 laravel/ai 后才会加载。

这些工具会从容器中解析出 FirecrawlClient，因此你现有的 config/firecrawl.php 和 FIRECRAWL_API_KEY 配置可直接原样复用：

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

可用工具#

类	工具名称	功能
`FirecrawlScrape`	`firecrawl_scrape`	抓取单个 URL 并返回干净的 markdown
`FirecrawlSearch`	`firecrawl_search`	进行网页搜索，返回 JSON 结果
`FirecrawlMap`	`firecrawl_map`	发现网站中的 URL
`FirecrawlCrawl`	`firecrawl_crawl`	将多个页面爬取为 markdown

这些工具名称与 Firecrawl MCP 服务器一致，因此代理在不同入口看到的术语也保持统一。可使用 spread helper 一次性注册这四个工具：

use Firecrawl\Laravel\Tools\FirecrawlTools;public function tools(): iterable{    return [...FirecrawlTools::all()];}

每个工具也都支持显式传入客户端，适用于临时凭证或在容器外部使用。FirecrawlTools::all() 会将该客户端传给全部四个工具：

use Firecrawl\Client\FirecrawlClient;$client = FirecrawlClient::create(apiKey: 'fc-other-key');new FirecrawlScrape($client);// 或FirecrawlTools::all($client);

工具参数#

每个工具都会提供一个面向模型的小型 schema。以下是代理可传递的参数：

工具	参数	描述
`firecrawl_scrape`	`url` (必填)	要抓取页面的绝对 URL，包括协议
`firecrawl_search`	`query` (必填)	搜索词
	`limit`	返回结果的最大数量，1–20。默认值为 5
`firecrawl_map`	`url` (必填)	要映射的网站基础 URL
	`search`	可选关键词，用于按相关性筛选已发现的 URL
	`limit`	返回 URL 的最大数量，1–500。默认值为 100
`firecrawl_crawl`	`url` (必填)	开始爬取的 URL
	`limit`	爬取页面的最大数量，1–25。默认值为 5

超出范围的 limit 值不会被拒绝，而是会自动调整到最近的边界值，因此当模型请求 99 个搜索结果时，返回的是 20 个，而不是报错。

工具行为#

限流、超时和无效 URL 等工具故障不会以抛出异常的形式处理，而是作为可读的错误字符串返回给模型，因此代理运行可以优雅降级。为保持在模型上下文范围内，输出大小会受到限制：scrape 结果会截断至 80,000 个字符；crawl 结果在总结果预算为 100,000 个字符的前提下，每页截断至 15,000 个字符；search 和 map 结果则会移除末尾条目，并用明确的标记说明有内容被省略。

firecrawl_search 和 firecrawl_map 返回 JSON 结果数组。firecrawl_scrape 以 markdown 格式返回页面。

抓取结果#

firecrawl_crawl 最多会等待 55 秒让抓取完成，随后返回一个明确体现结果的 JSON 对象。失败、已取消或部分完成的抓取结果会通过 status 字段继续对模型可见，而不会被静默截断：

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

当结果装不下时，会出现两个可选字段：omittedPages 表示为控制在输出预算内而省略的页面数，note 则会告知模型服务器上还有更多页面，并提示它使用更小的 limit，或通过 firecrawl_scrape 抓取特定页面。该工具会报告分页信息，而不会继续跟随分页，因此需要获取大型爬取全部页面的代理应直接使用 FirecrawlClient。

如果 wait 到期时爬取仍在进行中，工具会明确说明，并提醒模型该爬取仍可能在服务器端继续完成。启动爬取时会附带一个 UUID 幂等键，因此 HTTP 层面的重试绝不会创建重复的爬取。

如果你的代理运行在排队任务中，请将爬取 limit 保持得较小，或提高 worker 的任务超时时间。wait、poll 频率和每页上限都是受保护属性，因此请通过继承该类来调整它们：

use Firecrawl\Laravel\Tools\FirecrawlCrawl;class PatientCrawl extends FirecrawlCrawl{    protected int $timeoutSeconds = 120;    protected int $pollIntervalSeconds = 5;    protected int $pageCharacterLimit = 30000;}

浏览器#

PHP SDK 提供了浏览器 Sandbox 辅助函数。

创建会话#

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

执行代码#

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

与抓取任务绑定的交互式会话#

使用抓取任务 ID，在同一重放上下文中运行后续浏览器代码：

interact(...) 会在与抓取任务绑定的浏览器会话中运行代码 (首次使用时会自动初始化该会话) 。
stopInteractiveBrowser(...) 会在你使用完毕后显式停止该交互式会话。

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

列出并关闭会话#

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

配置#

FirecrawlClient::create() 支持以下选项：

选项	类型	默认值	描述
`apiKey`	`string`	`FIRECRAWL_API_KEY` 环境变量	你的 Firecrawl API 密钥
`apiUrl`	`string`	`https://api.firecrawl.dev` (或 `FIRECRAWL_API_URL`)	API 基础 URL
`timeoutSeconds`	`float`	`300`	HTTP 请求超时时间 (秒)
`maxRetries`	`int`	`3`	发生临时故障时自动重试
`backoffFactor`	`float`	`0.5`	指数退避系数 (秒)
`httpClient`	`GuzzleHttp\ClientInterface`	根据 timeout 构建	自定义的 Guzzle 兼容 HTTP 客户端

use Firecrawl\Client\FirecrawlClient;$client = FirecrawlClient::create(    apiKey: 'fc-your-api-key',    apiUrl: 'https://api.firecrawl.dev',    timeoutSeconds: 300,    maxRetries: 3,    backoffFactor: 0.5,);

自定义 HTTP 客户端#

你可以传入一个预先配置的 GuzzleHttp\ClientInterface 实现，用于控制连接池、中间件、代理设置及其他 HTTP 功能。提供该实现后，timeoutSeconds 设置将被忽略，改为以客户端自身的配置为准。

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

错误处理#

SDK 会抛出位于 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();}

你是需要 Firecrawl API 密钥的 AI 代理吗？请参见 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化接入说明。