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 Laravel AI SDK tool base class and FirecrawlScrape
Kris Oei0224f5b01984
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlScrape.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlScrape.phpnew file mode 100644index 000000000..7979a2832--- /dev/null+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlScrape.php@@ -0,0 +1,49 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Laravel\Tools;++use Firecrawl\Models\ScrapeOptions;+use Illuminate\Contracts\JsonSchema\JsonSchema;+use Laravel\Ai\Tools\Request;++class FirecrawlScrape extends FirecrawlTool+{+ public function name(): string+ {+ return 'firecrawl_scrape';+ }++ public function description(): string+ {+ return 'Scrape a single web page with Firecrawl and return its content as clean markdown. '+ . 'Use this when you already know the URL of the page you need to read. '+ . 'Handles JavaScript-rendered pages, PDFs, and pages behind anti-bot protection.';+ }++ public function handle(Request $request): string+ {+ return $this->guard(function () use ($request): string {+ $document = $this->client()->scrape(+ (string) $request->string('url'),+ ScrapeOptions::with(+ formats: ['markdown'],+ integration: self::INTEGRATION,+ ),+ );++ return $this->documentContent($document);+ });+ }++ /** @return array<string, \Illuminate\JsonSchema\Types\Type> */+ public function schema(JsonSchema $schema): array+ {+ return [+ 'url' => $schema->string()+ ->description('The absolute URL of the page to scrape, including the scheme (e.g. https://example.com/pricing).')+ ->required(),+ ];+ }+}diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlTool.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlTool.phpnew file mode 100644index 000000000..d2bf81495--- /dev/null+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlTool.php@@ -0,0 +1,62 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Laravel\Tools;++use Firecrawl\Client\FirecrawlClient;+use Firecrawl\Exceptions\FirecrawlException;+use Firecrawl\Models\Document;+use Illuminate\Container\Container;+use Laravel\Ai\Contracts\Tool;++abstract class FirecrawlTool implements Tool+{+ protected const INTEGRATION = 'laravel-ai';++ public function __construct(+ private ?FirecrawlClient $client = null,+ ) {}++ protected function client(): FirecrawlClient+ {+ if ($this->client === null) {+ /** @var FirecrawlClient $resolved */+ $resolved = Container::getInstance()->make(FirecrawlClient::class);+ $this->client = $resolved;+ }++ return $this->client;+ }++ /**+ * Run a Firecrawl call, returning failures as strings so the model can+ * see the error and recover instead of aborting the whole agent run.+ *+ * @param callable(): string $callback+ */+ protected function guard(callable $callback): string+ {+ try {+ return $callback();+ } catch (FirecrawlException $exception) {+ return 'Firecrawl request failed: ' . $exception->getMessage();+ }+ }++ protected function documentContent(Document $document): string+ {+ $content = $document->getMarkdown()+ ?? $document->getSummary()+ ?? $document->getHtml()+ ?? '';++ if ($content === '') {+ return 'No content was returned for this page.';+ }++ $warning = $document->getWarning();++ return $warning !== null ? "Warning: {$warning}\n\n{$content}" : $content;+ }+}diff --git a/apps/php-sdk/tests/Pest.php b/apps/php-sdk/tests/Pest.phpindex 560eff47e..e3c020d42 100644--- a/apps/php-sdk/tests/Pest.php+++ b/apps/php-sdk/tests/Pest.php@@ -2,4 +2,30 @@declare(strict_types=1);+use Firecrawl\Client\FirecrawlClient;+use GuzzleHttp\Client;+use GuzzleHttp\Handler\MockHandler;+use GuzzleHttp\HandlerStack;+use GuzzleHttp\Middleware;+uses()->group('unit')->in('Unit');++/**+ * Build a FirecrawlClient whose HTTP layer is a Guzzle MockHandler queue.+ * Pass an ArrayObject as $history to capture the requests that were sent.+ *+ * @param list<\GuzzleHttp\Psr7\Response> $responses+ */+function fakeFirecrawlClient(array $responses, ?ArrayObject $history = null): FirecrawlClient+{+ $stack = HandlerStack::create(new MockHandler($responses));++ if ($history !== null) {+ $stack->push(Middleware::history($history));+ }++ return FirecrawlClient::create(+ apiKey: 'fc-test',+ httpClient: new Client(['handler' => $stack, 'http_errors' => false]),+ );+}diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.phpnew file mode 100644index 000000000..b4c2b4592--- /dev/null+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php@@ -0,0 +1,77 @@+<?php++declare(strict_types=1);++use Firecrawl\Laravel\Tools\FirecrawlScrape;+use GuzzleHttp\Psr7\Response;+use Illuminate\JsonSchema\JsonSchemaTypeFactory;+use Laravel\Ai\ObjectSchema;+use Laravel\Ai\Tools\Request;++it('scrapes a URL and returns markdown', function (): void {+ $history = new ArrayObject();+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode([+ 'success' => true,+ 'data' => [+ 'markdown' => '# Example Page',+ 'metadata' => ['title' => 'Example', 'sourceURL' => 'https://example.com'],+ ],+ ])),+ ], $history);++ $result = (new FirecrawlScrape($client))->handle(new Request(['url' => 'https://example.com']));++ expect($result)->toBe('# Example Page');++ $body = json_decode((string) $history[0]['request']->getBody(), true);+ expect($body['url'])->toBe('https://example.com');+ expect($body['formats'])->toBe(['markdown']);+ expect($body['integration'])->toBe('laravel-ai');+});++it('prepends scrape warnings to the content', function (): void {+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode([+ 'success' => true,+ 'data' => ['markdown' => '# Partial', 'warning' => 'Page loaded partially'],+ ])),+ ]);++ $result = (new FirecrawlScrape($client))->handle(new Request(['url' => 'https://example.com']));++ expect($result)->toBe("Warning: Page loaded partially\n\n# Partial");+});++it('reports empty documents instead of returning an empty string', function (): void {+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode(['success' => true, 'data' => []])),+ ]);++ $result = (new FirecrawlScrape($client))->handle(new Request(['url' => 'https://example.com']));++ expect($result)->toBe('No content was returned for this page.');+});++it('returns API failures as readable strings instead of throwing', function (): void {+ $client = fakeFirecrawlClient([+ new Response(401, [], json_encode(['error' => 'Unauthorized: invalid token'])),+ ]);++ $result = (new FirecrawlScrape($client))->handle(new Request(['url' => 'https://example.com']));++ expect($result)->toStartWith('Firecrawl request failed:');+});++it('exposes name, description, and a required url parameter', function (): void {+ $tool = new FirecrawlScrape(fakeFirecrawlClient([]));++ expect($tool->name())->toBe('firecrawl_scrape');+ expect((string) $tool->description())->not->toBe('');++ $types = $tool->schema(new JsonSchemaTypeFactory());+ expect($types)->toHaveKey('url');++ $jsonSchema = (new ObjectSchema($types))->toSchema();+ expect($jsonSchema['required'])->toContain('url');+});