Skip to content

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

fix(php-sdk): harden Laravel AI tool guard against non-SDK exceptions

Kris Oeibcd0283bc509
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php
index 9c2ae12b9..37983d2f6 100644
--- a/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php
+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php
@@ -50,7 +50,7 @@ class FirecrawlCrawl extends FirecrawlTool
return "Crawl finished with status [{$job->getStatus()}] but returned no pages.";
}
- return json_encode($pages, JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
+ return $this->toJson($pages);
});
}
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlMap.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlMap.php
index c1271a9f3..91136b88b 100644
--- a/apps/php-sdk/src/Laravel/Tools/FirecrawlMap.php
+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlMap.php
@@ -48,7 +48,7 @@ class FirecrawlMap extends FirecrawlTool
return 'No URLs discovered.';
}
- return json_encode($links, JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
+ return $this->toJson($links);
});
}
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlSearch.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlSearch.php
index 9372e334f..64fffa777 100644
--- a/apps/php-sdk/src/Laravel/Tools/FirecrawlSearch.php
+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlSearch.php
@@ -42,7 +42,7 @@ class FirecrawlSearch extends FirecrawlTool
return 'No results found.';
}
- return json_encode($web, JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
+ return $this->toJson($web);
});
}
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlTool.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlTool.php
index d2bf81495..640adc186 100644
--- a/apps/php-sdk/src/Laravel/Tools/FirecrawlTool.php
+++ b/apps/php-sdk/src/Laravel/Tools/FirecrawlTool.php
@@ -32,6 +32,8 @@ abstract class FirecrawlTool implements Tool
/**
* Run a Firecrawl call, returning failures as strings so the model can
* see the error and recover instead of aborting the whole agent run.
+ * Non-SDK failures (e.g. container resolution, JSON encoding) are also
+ * converted to strings so `handle()` never throws.
*
* @param callable(): string $callback
*/
@@ -41,9 +43,20 @@ abstract class FirecrawlTool implements Tool
return $callback();
} catch (FirecrawlException $exception) {
return 'Firecrawl request failed: ' . $exception->getMessage();
+ } catch (\Throwable $exception) {
+ return 'Tool execution failed: ' . $exception->getMessage();
}
}
+ /** @param array<int|string, mixed> $data */
+ protected function toJson(array $data): string
+ {
+ return json_encode(
+ $data,
+ JSON_UNESCAPED_SLASHES | JSON_INVALID_UTF8_SUBSTITUTE | JSON_THROW_ON_ERROR,
+ );
+ }
+
protected function documentContent(Document $document): string
{
$content = $document->getMarkdown()
diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php
index b4c2b4592..5c7272b76 100644
--- a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php
+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php
@@ -2,8 +2,10 @@
declare(strict_types=1);
+use Firecrawl\Client\FirecrawlClient;
use Firecrawl\Laravel\Tools\FirecrawlScrape;
use GuzzleHttp\Psr7\Response;
+use Illuminate\Container\Container;
use Illuminate\JsonSchema\JsonSchemaTypeFactory;
use Laravel\Ai\ObjectSchema;
use Laravel\Ai\Tools\Request;
@@ -63,6 +65,35 @@ it('returns API failures as readable strings instead of throwing', function ():
expect($result)->toStartWith('Firecrawl request failed:');
});
+it('resolves the client from the container when none is injected', function (): void {
+ $container = new Container();
+ $container->instance(FirecrawlClient::class, fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'data' => ['markdown' => '# Via Container']])),
+ ]));
+ Container::setInstance($container);
+
+ try {
+ $result = (new FirecrawlScrape())->handle(new Request(['url' => 'https://example.com']));
+ } finally {
+ Container::setInstance(null);
+ }
+
+ expect($result)->toBe('# Via Container');
+});
+
+it('converts non-SDK failures into readable strings instead of throwing', function (): void {
+ Container::setInstance(new Container());
+
+ try {
+ // No FirecrawlClient binding — container resolution fails inside handle().
+ $result = (new FirecrawlScrape())->handle(new Request(['url' => 'https://example.com']));
+ } finally {
+ Container::setInstance(null);
+ }
+
+ expect($result)->toStartWith('Tool execution failed:');
+});
+
it('exposes name, description, and a required url parameter', function (): void {
$tool = new FirecrawlScrape(fakeFirecrawlClient([]));