> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-dne9il.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP

> Firecrawl PHP SDK is a wrapper around the Firecrawl API to help you easily turn websites into markdown.

## Installation

The official PHP SDK is maintained in the Firecrawl monorepo at [apps/php-sdk](https://github.com/firecrawl/firecrawl/tree/main/apps/php-sdk).

To install the Firecrawl PHP SDK, add the dependency via Composer:

```bash theme={null}
composer require firecrawl/firecrawl-sdk
```

<Note>Requires PHP 8.1 or later.</Note>

### Laravel Integration

The SDK includes first-class Laravel support with auto-discovery. After installing the package, publish the configuration file:

```bash theme={null}
php artisan vendor:publish --provider="Firecrawl\Laravel\FirecrawlServiceProvider"
```

Then add your API key to your `.env` file:

```env theme={null}
FIRECRAWL_API_KEY=fc-your-api-key
```

The following environment variables are supported:

| Variable                   | Default                     | Description                              |
| -------------------------- | --------------------------- | ---------------------------------------- |
| `FIRECRAWL_API_KEY`        | —                           | Your Firecrawl API key (required)        |
| `FIRECRAWL_API_URL`        | `https://api.firecrawl.dev` | API base URL                             |
| `FIRECRAWL_TIMEOUT`        | `300`                       | HTTP request timeout in seconds          |
| `FIRECRAWL_MAX_RETRIES`    | `3`                         | Automatic retries for transient failures |
| `FIRECRAWL_BACKOFF_FACTOR` | `0.5`                       | Exponential backoff factor in seconds    |

## Usage

1. Get an API key from [firecrawl.dev](https://firecrawl.dev)
2. Set the API key as an environment variable named `FIRECRAWL_API_KEY`, or pass it with `FirecrawlClient::create(apiKey: ...)`

Here is a quick example using the current SDK API surface:

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

### Using the Laravel Facade

In a Laravel application you can use the `Firecrawl` facade or dependency injection:

```php theme={null}
use Firecrawl\Client\FirecrawlClient;
use Firecrawl\Laravel\Facades\Firecrawl;

// Via Facade
$doc = Firecrawl::scrape('https://example.com');

// Via Dependency Injection
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 a URL

To scrape a single URL, use the `scrape` method.

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

#### JSON Extraction

Extract structured JSON with `JsonFormat` via the `scrape` endpoint:

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

### Crawling a Website

To crawl a website and wait for completion, use `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'] ?? '';
}
```

### Start a Crawl

Start a job without waiting using `startCrawl`.

```php theme={null}
use Firecrawl\Models\CrawlOptions;

$start = $client->startCrawl(
    'https://firecrawl.dev',
    CrawlOptions::with(limit: 100)
);

echo 'Job ID: ' . $start->getId();
```

### Checking Crawl Status

Check crawl progress with `getCrawlStatus`.

```php theme={null}
$status = $client->getCrawlStatus($start->getId());
echo 'Status: ' . $status->getStatus();
echo 'Progress: ' . $status->getCompleted() . '/' . $status->getTotal();
```

### Cancelling a Crawl

Cancel a running crawl with `cancelCrawl`.

```php theme={null}
$result = $client->cancelCrawl($start->getId());
print_r($result);
```

### Crawl Errors

Fetch crawl-level errors (if any) with `getCrawlErrors`.

```php theme={null}
$errors = $client->getCrawlErrors($start->getId());
print_r($errors);
```

### Mapping a Website

Discover links on a site using `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'] ?? '');
}
```

### Searching the Web

Search with optional search settings using `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'] ?? '');
}
```

### Batch Scraping

Scrape multiple URLs in parallel using `batchScrape`.

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

For manual async control, use `startBatchScrape`, `getBatchScrapeStatus`, and `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

Run an AI-powered agent with `agent`.

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

With a JSON schema for structured output:

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

For manual async control, use `startAgent`, `getAgentStatus`, and `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);
```

### Usage & Metrics

Check concurrency and remaining credits:

```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 Tools

The SDK ships native tool classes for the [Laravel AI SDK](https://laravel.com/docs/ai-sdk) (`laravel/ai`), so agents can scrape, search, map, and crawl the web without an MCP server or manual HTTP calls.

```bash theme={null}
composer require laravel/ai
```

<Note>Requires `firecrawl/firecrawl-sdk` 1.9.0 or later, plus `laravel/ai` 0.9 or later (PHP 8.3+, Laravel 12+). The tool classes only load when `laravel/ai` is installed.</Note>

The tools resolve the `FirecrawlClient` from the container, so your existing `config/firecrawl.php` and `FIRECRAWL_API_KEY` setup is reused as is:

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

### Available Tools

| Class             | Tool name          | What it does                             |
| ----------------- | ------------------ | ---------------------------------------- |
| `FirecrawlScrape` | `firecrawl_scrape` | Scrape one URL and return clean markdown |
| `FirecrawlSearch` | `firecrawl_search` | Search the web, returns JSON results     |
| `FirecrawlMap`    | `firecrawl_map`    | Discover the URLs on a website           |
| `FirecrawlCrawl`  | `firecrawl_crawl`  | Crawl multiple pages into markdown       |

The tool names match the Firecrawl MCP server, so agents see the same vocabulary across surfaces. Register all four at once with the spread helper:

```php theme={null}
use Firecrawl\Laravel\Tools\FirecrawlTools;

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

Every tool also accepts an explicit client, for one off credentials or use outside the container. `FirecrawlTools::all()` passes one to all four tools:

```php theme={null}
use Firecrawl\Client\FirecrawlClient;

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

new FirecrawlScrape($client);
// or
FirecrawlTools::all($client);
```

### Tool Parameters

Each tool exposes a small, model-facing schema. These are the parameters the agent can pass:

| Tool               | Parameter          | Description                                              |
| ------------------ | ------------------ | -------------------------------------------------------- |
| `firecrawl_scrape` | `url` (required)   | Absolute URL of the page to scrape, including the scheme |
| `firecrawl_search` | `query` (required) | The search query                                         |
|                    | `limit`            | Maximum results to return, 1–20. Defaults to 5           |
| `firecrawl_map`    | `url` (required)   | Base URL of the website to map                           |
|                    | `search`           | Optional term to filter discovered URLs by relevance     |
|                    | `limit`            | Maximum URLs to return, 1–500. Defaults to 100           |
| `firecrawl_crawl`  | `url` (required)   | URL to start crawling from                               |
|                    | `limit`            | Maximum pages to crawl, 1–25. Defaults to 5              |

Out-of-range `limit` values are clamped to the nearest bound rather than rejected, so a model that asks for 99 search results gets 20 instead of an error.

### Tool Behavior

Tool failures such as rate limits, timeouts, and invalid URLs are returned to the model as readable error strings rather than thrown, so agent runs degrade gracefully. Outputs are capped to stay within model context: scrape results truncate at 80,000 characters, crawl pages at 15,000 characters each under a 100,000 character whole result budget, and search and map results drop tail items with an explicit omitted marker.

`firecrawl_search` and `firecrawl_map` return JSON arrays of results. `firecrawl_scrape` returns the page as markdown.

### Crawl Results

`firecrawl_crawl` waits up to 55 seconds for the crawl to finish, then returns a JSON object that makes the outcome explicit. Failed, cancelled, or partial crawls stay visible to the model through the `status` field rather than being silently truncated:

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

Two optional fields appear when results don't fit: `omittedPages` counts pages dropped to stay inside the output budget, and `note` tells the model that more pages exist on the server and that it should use a smaller limit or scrape specific pages with `firecrawl_scrape`. The tool reports pagination instead of following it, so agents that need every page of a large crawl should use `FirecrawlClient` directly.

If the crawl is still running when the wait expires, the tool says so and reminds the model the crawl may still complete server-side. Crawl starts carry a UUID idempotency key, so an HTTP-level retry never creates a duplicate crawl.

If your agent runs inside a queued job, keep the crawl limit small or raise the worker's job timeout. The wait, poll cadence, and per-page cap are protected properties, so extend the class to tune them:

```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

The PHP SDK includes Browser Sandbox helpers.

### Create a Session

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

### Execute Code

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

### Scrape-Bound Interactive Session

Use a scrape job ID to run follow-up browser code in the same replayed context:

* `interact(...)` runs code in the scrape-bound browser session (and initializes it on first use).
* `stopInteractiveBrowser(...)` explicitly stops the interactive session when you are done.

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

### List & Close Sessions

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

## Configuration

`FirecrawlClient::create()` supports the following options:

| Option           | Type                         | Default                                              | Description                              |
| ---------------- | ---------------------------- | ---------------------------------------------------- | ---------------------------------------- |
| `apiKey`         | `string`                     | `FIRECRAWL_API_KEY` env var                          | Your Firecrawl API key                   |
| `apiUrl`         | `string`                     | `https://api.firecrawl.dev` (or `FIRECRAWL_API_URL`) | API base URL                             |
| `timeoutSeconds` | `float`                      | `300`                                                | HTTP request timeout in seconds          |
| `maxRetries`     | `int`                        | `3`                                                  | Automatic retries for transient failures |
| `backoffFactor`  | `float`                      | `0.5`                                                | Exponential backoff factor in seconds    |
| `httpClient`     | `GuzzleHttp\ClientInterface` | Built from timeout                                   | Custom Guzzle-compatible HTTP client     |

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

### Custom HTTP Client

You can pass a pre-configured `GuzzleHttp\ClientInterface` implementation to control connection pooling, middleware, proxy settings, and other HTTP features. When provided, the `timeoutSeconds` setting is ignored in favor of the client's own configuration.

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

## Error Handling

The SDK throws runtime exceptions under `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();
}
```

> Are you an AI agent that needs a Firecrawl API key? See [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for automated onboarding instructions.