Skip to content
Firecrawl Docs
Firecrawl Docs
公式

PHP

Firecrawl PHP SDK は、Web サイトを簡単に Markdown に変換できる Firecrawl API のラッパーです。

公式PHP SDKは、Firecrawl の monorepo 内にある apps/php-sdk で管理されています。

Firecrawl PHP SDK をインストールするには、Composer で依存関係を追加します。

composer require firecrawl/firecrawl-sdk
PHP 8.1 以降が必要です。

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_URLhttps://api.firecrawl.devAPIのベースURL
FIRECRAWL_TIMEOUT300HTTPリクエストのタイムアウト (秒)
FIRECRAWL_MAX_RETRIES3一時的な障害に対する自動再試行回数
FIRECRAWL_BACKOFF_FACTOR0.5指数バックオフの係数 (秒)
  1. firecrawl.dev でAPIキーを取得します
  2. 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 アプリケーションでは、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をスクレイピングするには、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'] ?? '';

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

この 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?');
ClassTool nameできること
FirecrawlScrapefirecrawl_scrape1 つの URL をスクレイピングし、整形済みの markdown を返します
FirecrawlSearchfirecrawl_searchWeb を検索し、JSON 形式の結果を返します
FirecrawlMapfirecrawl_mapWeb サイト内の URL を見つけます
FirecrawlCrawlfirecrawl_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_scrapeurl (required)スクレイピング対象ページの絶対 URL (スキームを含む)
firecrawl_searchquery (required)検索 query
limit返す結果の最大数。1～20。デフォルトは 5
firecrawl_mapurl (required)マップ対象の Web サイトのベース URL
search検出された URL を関連性で絞り込むための任意の語句
limit返す URL の最大数。1～500。デフォルトは 100
firecrawl_crawlurl (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;
}

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() は、次のオプションに対応しています。

オプション型デフォルト説明
apiKeystringFIRECRAWL_API_KEY 環境変数お使いの Firecrawl APIキー
apiUrlstringhttps://api.firecrawl.dev (または FIRECRAWL_API_URL)API のベース URL
timeoutSecondsfloat300HTTP リクエストのタイムアウト (秒)
maxRetriesint3一時的な障害に対する自動再試行回数
backoffFactorfloat0.5指数バックオフの係数 (秒)
httpClientGuzzleHttp\ClientInterfacetimeout 設定から構築カスタムの 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実装を渡せます。これを指定すると、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 を参照してください。

Was this page helpful?Suggest editsRaise issue
Previous.NETNextElixir

On this page

インストールLaravel 連携使い方Laravel ファサードの使用URLをスクレイピングするJSON抽出Web サイトのクロールクロールを開始するクロールのステータスを確認するクロールのキャンセルクロールエラーWeb サイトのマッピングWeb を検索バッチスクレイピングエージェント使用状況とメトリクスLaravel AI SDK ツール利用可能なツールツールのパラメータツールの動作クロール結果Browserセッションの作成コードの実行スクレイピングに紐づくインタラクティブセッションセッションの一覧表示と終了設定カスタムHTTPクライアントエラーハンドリング