Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
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.phpnew file mode 100644index 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.phpnew file mode 100644index 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');+});