Skip to content

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

fix(php-sdk): surface success=false API envelopes instead of empty results

Kris Oei76027337ea15
diff --git a/apps/php-sdk/src/Client/FirecrawlClient.php b/apps/php-sdk/src/Client/FirecrawlClient.php
index d1992107d..c704af504 100644
--- a/apps/php-sdk/src/Client/FirecrawlClient.php
+++ b/apps/php-sdk/src/Client/FirecrawlClient.php
@@ -112,7 +112,7 @@ final class FirecrawlClient
}
$body['origin'] ??= 'php-sdk@' . Version::SDK_VERSION;
- $response = $this->http->post('/v2/scrape', $body);
+ $response = $this->assertSuccess($this->http->post('/v2/scrape', $body));
return Document::fromArray($response['data'] ?? $response);
}
@@ -387,7 +387,7 @@ final class FirecrawlClient
$body = array_merge($body, $options->toArray());
}
- $response = $this->http->post('/v2/map', $body);
+ $response = $this->assertSuccess($this->http->post('/v2/map', $body));
return MapData::fromArray($response['data'] ?? $response);
}
@@ -554,7 +554,7 @@ final class FirecrawlClient
}
$body['origin'] ??= 'php-sdk@' . Version::SDK_VERSION;
- $response = $this->http->post('/v2/search', $body);
+ $response = $this->assertSuccess($this->http->post('/v2/search', $body));
return SearchData::fromArray($response['data'] ?? $response);
}
@@ -729,6 +729,23 @@ final class FirecrawlClient
}
}
+ /**
+ * @param array<string, mixed> $response
+ * @return array<string, mixed> the same response, if it does not signal failure
+ */
+ private function assertSuccess(array $response): array
+ {
+ if (($response['success'] ?? null) === false) {
+ $error = $response['error'] ?? null;
+
+ throw new FirecrawlException(is_string($error) && $error !== ''
+ ? $error
+ : 'The API reported the request as unsuccessful.');
+ }
+
+ return $response;
+ }
+
/**
* @param array<string, scalar|null> $params
*/
diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlMapTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlMapTest.php
index 512726387..328ed3ffb 100644
--- a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlMapTest.php
+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlMapTest.php
@@ -58,6 +58,19 @@ it('reports when no URLs were discovered', function (): void {
expect($result)->toBe('No URLs discovered.');
});
+it('surfaces a success:false envelope as an error instead of empty results', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode([
+ 'success' => false,
+ 'error' => 'DNS resolution failed for host: nosuchdomain.example',
+ ])),
+ ]);
+
+ $result = (new FirecrawlMap($client))->handle(new Request(['url' => 'https://nosuchdomain.example']));
+
+ expect($result)->toStartWith('Firecrawl request failed: DNS resolution failed');
+});
+
it('exposes name and a schema with required url', function (): void {
$tool = new FirecrawlMap(fakeFirecrawlClient([]));
diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php
index a3465af9f..0223ab011 100644
--- a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php
+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlScrapeTest.php
@@ -65,6 +65,19 @@ it('returns API failures as readable strings instead of throwing', function ():
expect($result)->toStartWith('Firecrawl request failed:');
});
+it('surfaces a success:false envelope as an error instead of empty content', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode([
+ 'success' => false,
+ 'error' => 'DNS resolution failed for host: nosuchdomain.example',
+ ])),
+ ]);
+
+ $result = (new FirecrawlScrape($client))->handle(new Request(['url' => 'https://nosuchdomain.example']));
+
+ expect($result)->toStartWith('Firecrawl request failed: DNS resolution failed');
+});
+
it('resolves the client from the container when none is injected', function (): void {
$container = new Container();
$container->instance(FirecrawlClient::class, fakeFirecrawlClient([
diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlSearchTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlSearchTest.php
index fc21a97c4..829f8d813 100644
--- a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlSearchTest.php
+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlSearchTest.php
@@ -55,6 +55,19 @@ it('reports when no results were found', function (): void {
expect($result)->toBe('No results found.');
});
+it('surfaces a success:false envelope as an error instead of empty results', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode([
+ 'success' => false,
+ 'error' => 'DNS resolution failed for host: nosuchdomain.example',
+ ])),
+ ]);
+
+ $result = (new FirecrawlSearch($client))->handle(new Request(['query' => 'nosuchdomain.example']));
+
+ expect($result)->toStartWith('Firecrawl request failed: DNS resolution failed');
+});
+
it('exposes name and a schema with required query and optional limit', function (): void {
$tool = new FirecrawlSearch(fakeFirecrawlClient([]));