Skip to content

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

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

Kris Oei71f1a866bc26
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlSearch.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlSearch.php
new file mode 100644
index 000000000..9372e334f
--- /dev/null
+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlSearch.php
@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Laravel\Tools;
+
+use Firecrawl\Models\SearchOptions;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Laravel\Ai\Tools\Request;
+
+class FirecrawlSearch extends FirecrawlTool
+{
+ public function name(): string
+ {
+ return 'firecrawl_search';
+ }
+
+ public function description(): string
+ {
+ return 'Search the web with Firecrawl and return matching results as a JSON array of '
+ . '{title, url, description} objects. Use this to find relevant pages when you do not '
+ . 'already know the URL. Follow up with firecrawl_scrape to read the full content of a result.';
+ }
+
+ public function handle(Request $request): string
+ {
+ return $this->guard(function () use ($request): string {
+ $limit = min(max($request->integer('limit') ?: 5, 1), 20);
+
+ $results = $this->client()->search(
+ (string) $request->string('query'),
+ SearchOptions::with(limit: $limit, integration: self::INTEGRATION),
+ );
+
+ $web = array_map(static fn (array $item): array => [
+ 'title' => $item['title'] ?? null,
+ 'url' => $item['url'] ?? null,
+ 'description' => $item['description'] ?? null,
+ ], $results->getWeb());
+
+ if ($web === []) {
+ return 'No results found.';
+ }
+
+ return json_encode($web, JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
+ });
+ }
+
+ /** @return array<string, \Illuminate\JsonSchema\Types\Type> */
+ public function schema(JsonSchema $schema): array
+ {
+ return [
+ 'query' => $schema->string()
+ ->description('The search query.')
+ ->required(),
+ 'limit' => $schema->integer()->min(1)->max(20)
+ ->description('Maximum number of results to return. Defaults to 5.'),
+ ];
+ }
+}
diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlSearchTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlSearchTest.php
new file mode 100644
index 000000000..fc21a97c4
--- /dev/null
+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlSearchTest.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+use Firecrawl\Laravel\Tools\FirecrawlSearch;
+use GuzzleHttp\Psr7\Response;
+use Illuminate\JsonSchema\JsonSchemaTypeFactory;
+use Laravel\Ai\ObjectSchema;
+use Laravel\Ai\Tools\Request;
+
+it('searches the web and returns JSON results', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode([
+ 'success' => true,
+ 'data' => [
+ 'web' => [
+ ['title' => 'Firecrawl', 'url' => 'https://firecrawl.dev', 'description' => 'Web data API', 'position' => 1],
+ ],
+ ],
+ ])),
+ ], $history);
+
+ $result = (new FirecrawlSearch($client))->handle(new Request(['query' => 'firecrawl']));
+
+ expect(json_decode($result, true))->toBe([
+ ['title' => 'Firecrawl', 'url' => 'https://firecrawl.dev', 'description' => 'Web data API'],
+ ]);
+
+ $body = json_decode((string) $history[0]['request']->getBody(), true);
+ expect($body['query'])->toBe('firecrawl');
+ expect($body['limit'])->toBe(5);
+ expect($body['integration'])->toBe('laravel-ai');
+});
+
+it('clamps the limit between 1 and 20', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'data' => ['web' => []]])),
+ ], $history);
+
+ (new FirecrawlSearch($client))->handle(new Request(['query' => 'x', 'limit' => 99]));
+
+ $body = json_decode((string) $history[0]['request']->getBody(), true);
+ expect($body['limit'])->toBe(20);
+});
+
+it('reports when no results were found', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'data' => ['web' => []]])),
+ ]);
+
+ $result = (new FirecrawlSearch($client))->handle(new Request(['query' => 'x']));
+
+ expect($result)->toBe('No results found.');
+});
+
+it('exposes name and a schema with required query and optional limit', function (): void {
+ $tool = new FirecrawlSearch(fakeFirecrawlClient([]));
+
+ expect($tool->name())->toBe('firecrawl_search');
+
+ $types = $tool->schema(new JsonSchemaTypeFactory());
+ expect($types)->toHaveKeys(['query', 'limit']);
+
+ $jsonSchema = (new ObjectSchema($types))->toSchema();
+ expect($jsonSchema['required'])->toContain('query');
+ expect($jsonSchema['required'])->not->toContain('limit');
+});