Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(php-sdk): add FirecrawlCrawl Laravel AI tool

Kris Oei0c4dda2b0011
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php
new file mode 100644
index 000000000..9c2ae12b9
--- /dev/null
+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php
@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Laravel\Tools;
+
+use Firecrawl\Models\CrawlOptions;
+use Firecrawl\Models\Document;
+use Firecrawl\Models\ScrapeOptions;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Laravel\Ai\Tools\Request;
+
+class FirecrawlCrawl extends FirecrawlTool
+{
+ public function name(): string
+ {
+ return 'firecrawl_crawl';
+ }
+
+ public function description(): string
+ {
+ return 'Crawl a website with Firecrawl starting from a URL, following its links and returning '
+ . 'each crawled page as a {url, markdown} object in a JSON array. This is a slower, '
+ . 'multi-page operation that waits for the crawl to finish β€” prefer firecrawl_scrape when '
+ . 'you only need one known page, and keep the page limit small.';
+ }
+
+ public function handle(Request $request): string
+ {
+ return $this->guard(function () use ($request): string {
+ $limit = min(max($request->integer('limit') ?: 5, 1), 25);
+
+ $job = $this->client()->crawl(
+ (string) $request->string('url'),
+ CrawlOptions::with(
+ limit: $limit,
+ scrapeOptions: ScrapeOptions::with(formats: ['markdown']),
+ integration: self::INTEGRATION,
+ ),
+ );
+
+ $pages = array_map(fn (Document $document): array => [
+ 'url' => $document->getMetadata()['sourceURL']
+ ?? $document->getMetadata()['url']
+ ?? null,
+ 'markdown' => $this->documentContent($document),
+ ], $job->getData());
+
+ if ($pages === []) {
+ return "Crawl finished with status [{$job->getStatus()}] but returned no pages.";
+ }
+
+ return json_encode($pages, JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
+ });
+ }
+
+ /** @return array<string, \Illuminate\JsonSchema\Types\Type> */
+ public function schema(JsonSchema $schema): array
+ {
+ return [
+ 'url' => $schema->string()
+ ->description('The URL to start crawling from (e.g. https://example.com/docs).')
+ ->required(),
+ 'limit' => $schema->integer()->min(1)->max(25)
+ ->description('Maximum number of pages to crawl. Defaults to 5, capped at 25 to keep responses manageable.'),
+ ];
+ }
+}
diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlCrawlTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlCrawlTest.php
new file mode 100644
index 000000000..1e70fd3a0
--- /dev/null
+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlCrawlTest.php
@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+use Firecrawl\Laravel\Tools\FirecrawlCrawl;
+use GuzzleHttp\Psr7\Response;
+use Illuminate\JsonSchema\JsonSchemaTypeFactory;
+use Laravel\Ai\ObjectSchema;
+use Laravel\Ai\Tools\Request;
+
+it('crawls a site and returns pages as JSON', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ // POST /v2/crawl β€” start the job
+ new Response(200, [], json_encode(['success' => true, 'id' => 'job-1'])),
+ // GET /v2/crawl/job-1 β€” first poll, already completed
+ new Response(200, [], json_encode([
+ 'success' => true,
+ 'status' => 'completed',
+ 'total' => 1,
+ 'completed' => 1,
+ 'data' => [
+ ['markdown' => '# Page 1', 'metadata' => ['sourceURL' => 'https://example.com/p1']],
+ ],
+ ])),
+ ], $history);
+
+ $result = (new FirecrawlCrawl($client))->handle(new Request(['url' => 'https://example.com']));
+
+ expect(json_decode($result, true))->toBe([
+ ['url' => 'https://example.com/p1', 'markdown' => '# Page 1'],
+ ]);
+
+ $body = json_decode((string) $history[0]['request']->getBody(), true);
+ expect($body['url'])->toBe('https://example.com');
+ expect($body['limit'])->toBe(5);
+ expect($body['scrapeOptions']['formats'])->toBe(['markdown']);
+ expect($body['integration'])->toBe('laravel-ai');
+});
+
+it('clamps the page limit between 1 and 25', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'id' => 'job-1'])),
+ new Response(200, [], json_encode([
+ 'success' => true, 'status' => 'completed', 'total' => 0, 'completed' => 0, 'data' => [],
+ ])),
+ ], $history);
+
+ (new FirecrawlCrawl($client))->handle(new Request(['url' => 'https://example.com', 'limit' => 500]));
+
+ $body = json_decode((string) $history[0]['request']->getBody(), true);
+ expect($body['limit'])->toBe(25);
+});
+
+it('reports crawls that finish without pages', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'id' => 'job-1'])),
+ new Response(200, [], json_encode([
+ 'success' => true, 'status' => 'failed', 'total' => 0, 'completed' => 0, 'data' => [],
+ ])),
+ ]);
+
+ $result = (new FirecrawlCrawl($client))->handle(new Request(['url' => 'https://example.com']));
+
+ expect($result)->toBe('Crawl finished with status [failed] but returned no pages.');
+});
+
+it('returns API failures as readable strings instead of throwing', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(400, [], json_encode(['error' => 'Invalid URL'])),
+ ]);
+
+ $result = (new FirecrawlCrawl($client))->handle(new Request(['url' => 'not-a-url']));
+
+ expect($result)->toStartWith('Firecrawl request failed:');
+});
+
+it('exposes name and a schema with required url and optional limit', function (): void {
+ $tool = new FirecrawlCrawl(fakeFirecrawlClient([]));
+
+ expect($tool->name())->toBe('firecrawl_crawl');
+
+ $types = $tool->schema(new JsonSchemaTypeFactory());
+ expect($types)->toHaveKeys(['url', 'limit']);
+
+ $jsonSchema = (new ObjectSchema($types))->toSchema();
+ expect($jsonSchema['required'])->toContain('url');
+ expect($jsonSchema['required'])->not->toContain('limit');
+});