PHP SDK | EvoCrawl

Installation

The official PHP SDK is maintained in the EvoCrawl monorepo at apps/php-sdk. To install the EvoCrawl PHP SDK, add the dependency via Composer:

composer require evocrawl/evocrawl-sdk

Requires PHP 8.1 or later.

Laravel Integration

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

php artisan vendor:publish --provider="Evocrawl\Laravel\EvocrawlServiceProvider"

Then add your API key to your .env file:

EVOCRAWL_API_KEY=fc-your-api-key

The following environment variables are supported:

Variable	Default	Description
`EVOCRAWL_API_KEY`	—	Your EvoCrawl API key (required)
`EVOCRAWL_API_URL`	`https://api.evocrawl.com`	API base URL
`EVOCRAWL_TIMEOUT`	`300`	HTTP request timeout in seconds
`EVOCRAWL_MAX_RETRIES`	`3`	Automatic retries for transient failures
`EVOCRAWL_BACKOFF_FACTOR`	`0.5`	Exponential backoff factor in seconds

Usage

Get an API key from evocrawl.com
Set the API key as an environment variable named EVOCRAWL_API_KEY, or pass it with EvocrawlClient::create(apiKey: ...)

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

use Evocrawl\Client\EvocrawlClient;
use Evocrawl\Models\CrawlOptions;
use Evocrawl\Models\ScrapeOptions;

$client = EvocrawlClient::fromEnv();

$doc = $client->scrape(
    'https://evocrawl.com',
    ScrapeOptions::with(formats: ['markdown'])
);

$crawl = $client->crawl(
    'https://evocrawl.com',
    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 Evocrawl facade or dependency injection:

use Evocrawl\Client\EvocrawlClient;
use Evocrawl\Laravel\Facades\Evocrawl;

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

// Via Dependency Injection
class ScrapeController
{
    public function __construct(
        private readonly EvocrawlClient $evocrawl,
    ) {}

    public function index()
    {
        $doc = $this->evocrawl->scrape('https://example.com');
        return response()->json(['markdown' => $doc->getMarkdown()]);
    }
}

Scraping a URL

To scrape a single URL, use the scrape method.

use Evocrawl\Models\Document;
use Evocrawl\Models\ScrapeOptions;

$doc = $client->scrape(
    'https://evocrawl.com',
    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:

use Evocrawl\Models\JsonFormat;
use Evocrawl\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.

use Evocrawl\Models\CrawlOptions;
use Evocrawl\Models\ScrapeOptions;

$job = $client->crawl(
    'https://evocrawl.com',
    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.

use Evocrawl\Models\CrawlOptions;

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

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

Checking Crawl Status

Check crawl progress with getCrawlStatus.

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

Cancelling a Crawl

Cancel a running crawl with cancelCrawl.

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

Crawl Errors

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

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

Mapping a Website

Discover links on a site using map.

use Evocrawl\Models\MapOptions;

$data = $client->map(
    'https://evocrawl.com',
    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.

use Evocrawl\Models\SearchOptions;

$results = $client->search(
    'evocrawl 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.

use Evocrawl\Models\BatchScrapeOptions;
use Evocrawl\Models\ScrapeOptions;

$job = $client->batchScrape(
    ['https://evocrawl.com', 'https://evocrawl.com/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:

use Evocrawl\Models\BatchScrapeOptions;
use Evocrawl\Models\ScrapeOptions;

$start = $client->startBatchScrape(
    ['https://evocrawl.com', 'https://evocrawl.com/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.

use Evocrawl\Models\AgentOptions;

$result = $client->agent(
    AgentOptions::with(
        prompt: 'Find the pricing plans for EvoCrawl and compare them',
    )
);

print_r($result->getData());

With a JSON schema for structured output:

use Evocrawl\Models\AgentOptions;

$result = $client->agent(
    AgentOptions::with(
        prompt: 'Extract pricing plan details',
        urls: ['https://evocrawl.com'],
        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:

use Evocrawl\Models\AgentOptions;

$start = $client->startAgent(
    AgentOptions::with(
        prompt: 'Summarize what Evocrawl does in one sentence',
        urls: ['https://evocrawl.com'],
    )
);

$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:

use Evocrawl\Models\ConcurrencyCheck;
use Evocrawl\Models\CreditUsage;

$concurrency = $client->getConcurrency();
echo 'Concurrency: ' . $concurrency->getConcurrency() . '/' . $concurrency->getMaxConcurrency();

$credits = $client->getCreditUsage();
echo 'Remaining credits: ' . $credits->getRemainingCredits();

Browser

The PHP SDK includes Browser Sandbox helpers.

Create a Session

use Evocrawl\Models\BrowserCreateResponse;

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

Execute Code

use Evocrawl\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.

use Evocrawl\Models\BrowserExecuteResponse;
use Evocrawl\Models\BrowserDeleteResponse;
use Evocrawl\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

use Evocrawl\Models\BrowserListResponse;
use Evocrawl\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

EvocrawlClient::create() supports the following options:

Option	Type	Default	Description
`apiKey`	`string`	`EVOCRAWL_API_KEY` env var	Your EvoCrawl API key
`apiUrl`	`string`	`https://api.evocrawl.com` (or `EVOCRAWL_API_URL` for self-hosted)	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

use Evocrawl\Client\EvocrawlClient;

$client = EvocrawlClient::create(
    apiKey: 'fc-your-api-key',
    apiUrl: 'https://api.evocrawl.com',
    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.

use Evocrawl\Client\EvocrawlClient;
use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient([
    'proxy' => 'http://proxy.example.com:8080',
    'timeout' => 60,
    'connect_timeout' => 10,
]);

$client = EvocrawlClient::create(
    apiKey: 'fc-your-api-key',
    httpClient: $guzzle,
);

Error Handling

The SDK throws runtime exceptions under Evocrawl\Exceptions.

use Evocrawl\Exceptions\AuthenticationException;
use Evocrawl\Exceptions\EvocrawlException;
use Evocrawl\Exceptions\JobTimeoutException;
use Evocrawl\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 (EvocrawlException $e) {
    echo 'Error ' . $e->getStatusCode() . ': ' . $e->getMessage();
}

Are you an AI agent that needs a EvoCrawl API key? See evocrawl.com/agent-onboarding/SKILL.md for automated onboarding instructions.

Overall

Official

PHP

Installation

Laravel Integration

Usage

Using the Laravel Facade

Scraping a URL

JSON Extraction

Crawling a Website

Start a Crawl

Checking Crawl Status

Cancelling a Crawl

Crawl Errors

Mapping a Website

Searching the Web

Batch Scraping

Agent

Usage & Metrics

Browser

Create a Session

Execute Code

Scrape-Bound Interactive Session

List & Close Sessions

Configuration

Custom HTTP Client

Error Handling

​Installation

​Laravel Integration

​Usage

​Using the Laravel Facade

​Scraping a URL

​JSON Extraction

​Crawling a Website

​Start a Crawl

​Checking Crawl Status

​Cancelling a Crawl

​Crawl Errors

​Mapping a Website

​Searching the Web

​Batch Scraping

​Agent

​Usage & Metrics

​Browser

​Create a Session

​Execute Code

​Scrape-Bound Interactive Session

​List & Close Sessions

​Configuration

​Custom HTTP Client

​Error Handling

Installation

Laravel Integration

Usage

Using the Laravel Facade

Scraping a URL

JSON Extraction

Crawling a Website

Start a Crawl

Checking Crawl Status

Cancelling a Crawl

Crawl Errors

Mapping a Website

Searching the Web

Batch Scraping

Agent

Usage & Metrics

Browser

Create a Session

Execute Code

Scrape-Bound Interactive Session

List & Close Sessions

Configuration

Custom HTTP Client

Error Handling