PHP SDK | Firecrawl

インストール

公式PHP SDKは、Firecrawl の monorepo 内にある apps/php-sdk で管理されています。 Firecrawl PHP SDK をインストールするには、Composer で依存関係を追加します。

composer require firecrawl/firecrawl-sdk

PHP 8.1 以降が必要です。

Laravel 連携

SDK は、自動検出に対応した Laravel 向けの充実したサポートを備えています。パッケージをインストールしたら、設定ファイルを公開してください。

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

次に、.env ファイルにAPIキーを追加してください:

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: ...) に渡します

以下は、現在の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;

// ファサード経由
$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抽出

JsonFormat を使用して、scrape エンドポイントから構造化された 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());

Web サイトのクロール

Web サイトをクロールして完了を待つには、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);

Web サイトのマッピング

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

Web を検索

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 Server や手動の HTTP 呼び出しなしで、Web のスクレイピング、検索、マップ、クロールを行えます。

composer require laravel/ai

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

利用可能なツール

Class	Tool name	できること
`FirecrawlScrape`	`firecrawl_scrape`	1 つの URL をスクレイピングし、整形済みの markdown を返します
`FirecrawlSearch`	`firecrawl_search`	Web を検索し、JSON 形式の結果を返します
`FirecrawlMap`	`firecrawl_map`	Web サイト内の URL を見つけます
`FirecrawlCrawl`	`firecrawl_crawl`	複数のページをクロールして markdown に変換します

ツール名は Firecrawl MCP server と一致しているため、エージェントはどのインターフェースでも同じ用語を使えます。スプレッドヘルパーを使うと、4 つすべてを一度に登録できます:

use Firecrawl\Laravel\Tools\FirecrawlTools;

public function tools(): iterable
{
    return [...FirecrawlTools::all()];
}

各ツールは、一時的な認証情報を使う場合やコンテナ外で利用する場合に備えて、明示的にクライアントを受け取ることもできます。FirecrawlTools::all() は、それを4つすべてのツールに渡します：

use Firecrawl\Client\FirecrawlClient;

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

new FirecrawlScrape($client);
// または
FirecrawlTools::all($client);

ツールのパラメータ

各ツールは、モデル向けの小規模なスキーマを公開しています。エージェントが渡せるパラメータは次のとおりです。

ツール	パラメータ	説明
`firecrawl_scrape`	`url` (required)	スクレイピング対象ページの絶対 URL (スキームを含む)
`firecrawl_search`	`query` (required)	検索 query
	`limit`	返す結果の最大数。1～20。デフォルトは 5
`firecrawl_map`	`url` (required)	マップ対象の Web サイトのベース URL
	`search`	検出された URL を関連性で絞り込むための任意の語句
	`limit`	返す URL の最大数。1～500。デフォルトは 100
`firecrawl_crawl`	`url` (required)	クロールの開始元となる URL
	`limit`	クロールするページの最大数。1～25。デフォルトは 5

範囲外の limit 値はエラーとして拒否されず、最も近い上限または下限に補正されます。たとえば、検索結果を 99 件要求したモデルには、エラーではなく 20 件が返されます。

ツールの動作

レート制限、タイムアウト、無効な URL などのツールの失敗は、例外としてスローされるのではなく、人間が読めるエラー文字列としてモデルに返されるため、agent run が致命的に停止せず、適切に処理を継続できます。出力はモデルのコンテキスト内に収まるよう上限が設けられています。スクレイピング結果は 80,000 文字で切り詰められ、クロールしたページは各ページ 15,000 文字までに制限され、結果全体では 100,000 文字の上限があります。また、search と map の結果では、明示的な omitted マーカーを付けて末尾の項目が省略されます。 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": "..." }
  ]
}

結果が収まりきらない場合は、2つの任意フィールドが表示されます。omittedPages は出力上限内に収めるために省かれたページ数を示し、note はサーバー上にまだページが存在すること、また、より小さい limit を使うか firecrawl_scrape で特定のページをスクレイピングすべきことをモデルに伝えます。このツールはページネーションを追跡せず、ページネーションがあることを報告するだけなので、大規模なクロールの全ページが必要なエージェントは FirecrawlClient を直接使用してください。 wait の期限が切れた時点でクロールがまだ実行中の場合、ツールはその旨を伝え、そのクロールがサーバー側で引き続き完了する可能性があることをモデルに知らせます。クロール開始には UUID の冪等性キーが付与されるため、HTTP レベルで再試行しても重複したクロールは作成されません。エージェントがキューに入った job 内で実行される場合は、クロールの limit を小さく保つか、worker の job timeout を延ばしてください。wait、poll の間隔、およびページごとの上限は protected プロパティなので、調整するにはクラスを拡張してください:

use Firecrawl\Laravel\Tools\FirecrawlCrawl;

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

Browser

PHP SDK には、ブラウザサンドボックスを利用するためのヘルパーが含まれています。

セッションの作成

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クライアント

接続プーリング、ミドルウェア、プロキシ設定、その他のHTTP機能を制御するために、事前に設定したGuzzleHttp\ClientInterface実装を渡せます。これを指定すると、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 を参照してください。

​インストール

​Laravel 連携

​使い方

​Laravel ファサードの使用

​URLをスクレイピングする

​JSON抽出

​Web サイトのクロール

​クロールを開始する

​クロールのステータスを確認する

​クロールのキャンセル

​クロールエラー

​Web サイトのマッピング

​Web を検索

​バッチスクレイピング

​エージェント

​使用状況とメトリクス

​Laravel AI SDK ツール

​利用可能なツール

​ツールのパラメータ

​ツールの動作

​クロール結果

​Browser

​セッションの作成

​コードの実行

​スクレイピングに紐づくインタラクティブセッション

​セッションの一覧表示と終了

​設定

​カスタムHTTPクライアント

​エラーハンドリング

インストール

Laravel 連携

使い方

Laravel ファサードの使用

URLをスクレイピングする

JSON抽出

Web サイトのクロール

クロールを開始する

クロールのステータスを確認する

クロールのキャンセル

クロールエラー

Web サイトのマッピング

Web を検索

バッチスクレイピング

エージェント

使用状況とメトリクス

Laravel AI SDK ツール

利用可能なツール

ツールのパラメータ

ツールの動作

クロール結果

Browser

セッションの作成

コードの実行

スクレイピングに紐づくインタラクティブセッション

セッションの一覧表示と終了

設定

カスタムHTTPクライアント

エラーハンドリング