Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
index 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.php
new file mode 100644
index 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');
+});