> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# PHP
> Firecrawl PHP SDK は、Web サイトを簡単に Markdown に変換できる Firecrawl API のラッパーです。
## インストール
公式PHP SDKは、Firecrawl の monorepo 内にある [apps/php-sdk](https://github.com/firecrawl/firecrawl/tree/main/apps/php-sdk) で管理されています。
Firecrawl PHP SDK をインストールするには、Composer で依存関係を追加します。
```bash theme={null}
composer require firecrawl/firecrawl-sdk
```
PHP 8.1 以降が必要です。
### Laravel 連携
SDK は、自動検出に対応した Laravel 向けの充実したサポートを備えています。パッケージをインストールしたら、設定ファイルを公開してください。
```bash theme={null}
php artisan vendor:publish --provider="Firecrawl\Laravel\FirecrawlServiceProvider"
```
次に、`.env` ファイルにAPIキーを追加してください:
```env theme={null}
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` | 指数バックオフの係数 (秒) |
## 使い方
1. [firecrawl.dev](https://firecrawl.dev) でAPIキーを取得します
2. APIキーを `FIRECRAWL_API_KEY` という名前の環境変数に設定するか、`FirecrawlClient::create(apiKey: ...)` に渡します
以下は、現在のSDK APIを使った簡単な例です。
```php theme={null}
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` ファサードまたは依存性注入を利用できます：
```php theme={null}
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` メソッドを使用します。
```php theme={null}
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 を抽出します：
```php theme={null}
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` を使用します。
```php theme={null}
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` を使用します。
```php theme={null}
use Firecrawl\Models\CrawlOptions;
$start = $client->startCrawl(
'https://firecrawl.dev',
CrawlOptions::with(limit: 100)
);
echo 'Job ID: ' . $start->getId();
```
### クロールのステータスを確認する
`getCrawlStatus` を使ってクロールの進行状況を確認します。
```php theme={null}
$status = $client->getCrawlStatus($start->getId());
echo 'Status: ' . $status->getStatus();
echo 'Progress: ' . $status->getCompleted() . '/' . $status->getTotal();
```
### クロールのキャンセル
実行中のクロールは `cancelCrawl` を使ってキャンセルできます。
```php theme={null}
$result = $client->cancelCrawl($start->getId());
print_r($result);
```
### クロールエラー
`getCrawlErrors` を使って、クロール単位のエラーがあれば取得できます。
```php theme={null}
$errors = $client->getCrawlErrors($start->getId());
print_r($errors);
```
### Web サイトのマッピング
`map` を使ってサイト内のリンクを検出します。
```php theme={null}
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` を使うと、任意の検索設定で検索できます。
```php theme={null}
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を並列にスクレイピングします。
```php theme={null}
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` を使用します：
```php theme={null}
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 エージェントを実行します。
```php theme={null}
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:
```php theme={null}
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` を使用します:
```php theme={null}
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);
```
### 使用状況とメトリクス
並列実行数と残りのクレジットを確認する:
```php theme={null}
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](https://laravel.com/docs/ai-sdk) (`laravel/ai`) 向けのネイティブツールクラスが用意されており、エージェントは MCP Server や手動の HTTP 呼び出しなしで、Web のスクレイピング、検索、マップ、クロールを行えます。
```bash theme={null}
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` の設定をそのまま再利用できます：
```php theme={null}
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 つすべてを一度に登録できます:
```php theme={null}
use Firecrawl\Laravel\Tools\FirecrawlTools;
public function tools(): iterable
{
return [...FirecrawlTools::all()];
}
```
各ツールは、一時的な認証情報を使う場合やコンテナ外で利用する場合に備えて、明示的にクライアントを受け取ることもできます。`FirecrawlTools::all()` は、それを4つすべてのツールに渡します：
```php theme={null}
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` フィールドを通じてモデルから確認できます。
```json theme={null}
{
"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 プロパティなので、調整するにはクラスを拡張してください:
```php theme={null}
use Firecrawl\Laravel\Tools\FirecrawlCrawl;
class PatientCrawl extends FirecrawlCrawl
{
protected int $timeoutSeconds = 120;
protected int $pollIntervalSeconds = 5;
protected int $pageCharacterLimit = 30000;
}
```
## Browser
PHP SDK には、ブラウザサンドボックスを利用するためのヘルパーが含まれています。
### セッションの作成
```php theme={null}
use Firecrawl\Models\BrowserCreateResponse;
$session = $client->browser(ttl: 120, activityTtl: 60, streamWebView: true);
echo $session->getId();
echo $session->getCdpUrl();
echo $session->getLiveViewUrl();
```
### コードの実行
```php theme={null}
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(...)` は、作業完了後にインタラクティブセッションを明示的に停止します。
```php theme={null}
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');
```
### セッションの一覧表示と終了
```php theme={null}
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 クライアント |
```php theme={null}
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`設定は無視され、代わりにクライアント側の設定が使用されます。
```php theme={null}
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` 配下の実行時例外をスローします。
```php theme={null}
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](https://www.firecrawl.dev/agent-onboarding/SKILL.md) を参照してください。