Skip to content

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

feat(php-sdk): add developer search (#5276)

Erik Engervallcebc195e783a
diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.md
index 65198527e..f63bda829 100644
--- a/apps/php-sdk/CHANGELOG.md
+++ b/apps/php-sdk/CHANGELOG.md
@@ -5,6 +5,15 @@ All notable changes to the Firecrawl PHP SDK will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.16.6] - 2026-10-20
+
+### Added
+- `developerSearch()` calls `POST /v2/search/developer`, the developer index
+ of public repositories, GitHub issues, merged pull requests, READMEs and code
+ documentation, with every filter the API takes (`DeveloperSearchOptions`)
+ and a typed `DeveloperSearchResponse`. It replaces the deprecated
+ `searchGithub()`, which stops responding after 2026-11-03.
+
## [1.16.5] - 2026-10-19
### Fixed
diff --git a/apps/php-sdk/README.md b/apps/php-sdk/README.md
index 9d8658af6..f8427edb5 100644
--- a/apps/php-sdk/README.md
+++ b/apps/php-sdk/README.md
@@ -241,6 +241,24 @@ foreach ($result->getWeb() as $item) {
}
```
+### Developer search
+
+Search public repositories, GitHub issues, merged pull requests, READMEs and code documentation. `developerSearch` replaces the deprecated `searchGithub`.
+
+```php
+use Firecrawl\Models\DeveloperSearchOptions;
+
+$response = $client->developerSearch('retry an http request with exponential backoff', DeveloperSearchOptions::with(
+ k: 5,
+ types: ['issue', 'pull_request'],
+ repos: ['square/okhttp'],
+));
+
+foreach ($response->getResults() as $result) {
+ echo $result->getTitle() . ': ' . $result->getUrl() . "\n";
+}
+```
+
### Agent
```php
diff --git a/apps/php-sdk/src/Client/FirecrawlClient.php b/apps/php-sdk/src/Client/FirecrawlClient.php
index 9f62c891b..8121cc72f 100644
--- a/apps/php-sdk/src/Client/FirecrawlClient.php
+++ b/apps/php-sdk/src/Client/FirecrawlClient.php
@@ -25,6 +25,8 @@ use Firecrawl\Models\CrawlJob;
use Firecrawl\Models\CrawlOptions;
use Firecrawl\Models\CrawlResponse;
use Firecrawl\Models\CreditUsage;
+use Firecrawl\Models\DeveloperSearchOptions;
+use Firecrawl\Models\DeveloperSearchResponse;
use Firecrawl\Models\Document;
use Firecrawl\Models\MapData;
use Firecrawl\Models\MapOptions;
@@ -182,10 +184,9 @@ final class FirecrawlClient
/**
* Search GitHub research content.
*
- * @deprecated Stops responding after 2026-11-03. Use the developer index at
- * GET or POST /v2/search/developer, which this SDK does not wrap yet, so
- * call it directly. It does not carry over the score breakdown or the web
- * fallback results.
+ * @deprecated Stops responding after 2026-11-03. Use {@see self::developerSearch()},
+ * which does not carry over the score breakdown or the web fallback
+ * results.
* @param array<string, mixed> $options
* @return array<string, mixed>
*/
@@ -197,6 +198,29 @@ final class FirecrawlClient
)));
}
+ /**
+ * Search the developer index: public repositories, GitHub issues, merged
+ * pull requests, READMEs and code documentation.
+ *
+ * @throws FirecrawlException if the query is blank
+ */
+ public function developerSearch(string $query, ?DeveloperSearchOptions $options = null): DeveloperSearchResponse
+ {
+ if (trim($query) === '') {
+ throw new FirecrawlException('Query cannot be empty');
+ }
+
+ $body = ['query' => $query];
+ if ($options !== null) {
+ $body = array_merge($body, $options->toArray());
+ }
+ $body['origin'] = 'php-sdk@' . Version::SDK_VERSION;
+
+ return DeveloperSearchResponse::fromArray(
+ $this->assertSuccess($this->http->post('/v2/search/developer', $body)),
+ );
+ }
+
/**
* Interact with the scrape-bound browser session for a scrape job.
*/
diff --git a/apps/php-sdk/src/Models/DeveloperSearchOptions.php b/apps/php-sdk/src/Models/DeveloperSearchOptions.php
new file mode 100644
index 000000000..0eea9fa7d
--- /dev/null
+++ b/apps/php-sdk/src/Models/DeveloperSearchOptions.php
@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/** Filters for {@see \Firecrawl\Client\FirecrawlClient::developerSearch()}. Unset fields are omitted from the request. */
+final class DeveloperSearchOptions
+{
+ /**
+ * @param list<string>|null $types
+ * @param list<string>|null $repos
+ * @param list<string>|null $sources
+ * @param list<string>|null $topic
+ */
+ private function __construct(
+ private readonly ?int $k = null,
+ private readonly ?int $passages = null,
+ private readonly ?array $types = null,
+ private readonly ?array $repos = null,
+ private readonly ?array $sources = null,
+ private readonly ?string $language = null,
+ private readonly ?array $topic = null,
+ private readonly ?string $license = null,
+ private readonly ?int $minStars = null,
+ private readonly ?int $maxStars = null,
+ private readonly ?bool $archived = null,
+ private readonly ?bool $fork = null,
+ private readonly ?string $skills = null,
+ ) {}
+
+ /**
+ * @param int|null $k Total ranked results, 1 to 100 (default 10).
+ * @param int|null $passages Passages per result, 1 to 5 (default 1).
+ * @param list<string>|null $types Result kinds: "doc", "issue", "pull_request", "readme" (default all).
+ * @param list<string>|null $repos GitHub owner/name filters, at most 20.
+ * @param list<string>|null $sources Developer documentation source IDs, at most 20.
+ * @param string|null $language One case-insensitive GitHub Linguist primary language.
+ * @param list<string>|null $topic Repository topics that must all match, at most 8.
+ * @param string|null $license One case-insensitive SPDX repository license identifier.
+ * @param string|null $skills "only" returns packaged agent-skill evidence only.
+ */
+ public static function with(
+ ?int $k = null,
+ ?int $passages = null,
+ ?array $types = null,
+ ?array $repos = null,
+ ?array $sources = null,
+ ?string $language = null,
+ ?array $topic = null,
+ ?string $license = null,
+ ?int $minStars = null,
+ ?int $maxStars = null,
+ ?bool $archived = null,
+ ?bool $fork = null,
+ ?string $skills = null,
+ ): self {
+ return new self(
+ $k, $passages, $types, $repos, $sources, $language, $topic,
+ $license, $minStars, $maxStars, $archived, $fork, $skills,
+ );
+ }
+
+ /** @return array<string, mixed> */
+ public function toArray(): array
+ {
+ $fields = [
+ 'k' => $this->k,
+ 'passages' => $this->passages,
+ 'types' => $this->types,
+ 'repos' => $this->repos,
+ 'sources' => $this->sources,
+ 'language' => $this->language,
+ 'topic' => $this->topic,
+ 'license' => $this->license,
+ 'min_stars' => $this->minStars,
+ 'max_stars' => $this->maxStars,
+ 'archived' => $this->archived,
+ 'fork' => $this->fork,
+ 'skills' => $this->skills,
+ ];
+
+ return array_filter($fields, fn (mixed $v): bool => $v !== null);
+ }
+}
diff --git a/apps/php-sdk/src/Models/DeveloperSearchPassage.php b/apps/php-sdk/src/Models/DeveloperSearchPassage.php
new file mode 100644
index 000000000..cef68cb13
--- /dev/null
+++ b/apps/php-sdk/src/Models/DeveloperSearchPassage.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/** One matched passage of a developer search result. */
+final class DeveloperSearchPassage
+{
+ public function __construct(
+ private readonly string $text = '',
+ private readonly ?string $citationUrl = null,
+ ) {}
+
+ /** @param array<string, mixed> $data */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ text: (string) ($data['text'] ?? ''),
+ citationUrl: isset($data['citation_url']) ? (string) $data['citation_url'] : null,
+ );
+ }
+
+ public function getText(): string
+ {
+ return $this->text;
+ }
+
+ public function getCitationUrl(): ?string
+ {
+ return $this->citationUrl;
+ }
+}
diff --git a/apps/php-sdk/src/Models/DeveloperSearchRepoStatus.php b/apps/php-sdk/src/Models/DeveloperSearchRepoStatus.php
new file mode 100644
index 000000000..5e975f4cb
--- /dev/null
+++ b/apps/php-sdk/src/Models/DeveloperSearchRepoStatus.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/** Whether a requested repository is indexed, and which result kinds it has. */
+final class DeveloperSearchRepoStatus
+{
+ /** @param array{issue: bool, pullRequest: bool, readme: bool} $types */
+ public function __construct(
+ private readonly string $repo = '',
+ private readonly bool $indexed = false,
+ private readonly array $types = ['issue' => false, 'pullRequest' => false, 'readme' => false],
+ ) {}
+
+ /** @param array<string, mixed> $data */
+ public static function fromArray(array $data): self
+ {
+ $types = is_array($data['types'] ?? null) ? $data['types'] : [];
+
+ return new self(
+ repo: (string) ($data['repo'] ?? ''),
+ indexed: (bool) ($data['indexed'] ?? false),
+ types: [
+ 'issue' => (bool) ($types['issue'] ?? false),
+ 'pullRequest' => (bool) ($types['pullRequest'] ?? false),
+ 'readme' => (bool) ($types['readme'] ?? false),
+ ],
+ );
+ }
+
+ public function getRepo(): string
+ {
+ return $this->repo;
+ }
+
+ public function isIndexed(): bool
+ {
+ return $this->indexed;
+ }
+
+ /** @return array{issue: bool, pullRequest: bool, readme: bool} */
+ public function getTypes(): array
+ {
+ return $this->types;
+ }
+}
diff --git a/apps/php-sdk/src/Models/DeveloperSearchResponse.php b/apps/php-sdk/src/Models/DeveloperSearchResponse.php
new file mode 100644
index 000000000..86c060498
--- /dev/null
+++ b/apps/php-sdk/src/Models/DeveloperSearchResponse.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/** Response from {@see \Firecrawl\Client\FirecrawlClient::developerSearch()}. */
+final class DeveloperSearchResponse
+{
+ /**
+ * @param list<DeveloperSearchResult> $results
+ * @param list<DeveloperSearchRepoStatus>|null $repos
+ * @param list<DeveloperSearchSourceStatus>|null $sources
+ */
+ public function __construct(
+ private readonly bool $success = true,
+ private readonly bool $partial = false,
+ private readonly array $results = [],
+ private readonly ?array $repos = null,
+ private readonly ?array $sources = null,
+ ) {}
+
+ /** @param array<string, mixed> $data */
+ public static function fromArray(array $data): self
+ {
+ $list = static fn (mixed $items): array => is_array($items) ? array_values(array_filter($items, 'is_array')) : [];
+
+ return new self(
+ success: (bool) ($data['success'] ?? true),
+ partial: (bool) ($data['partial'] ?? false),
+ results: array_map(DeveloperSearchResult::fromArray(...), $list($data['results'] ?? null)),
+ repos: is_array($data['repos'] ?? null)
+ ? array_map(DeveloperSearchRepoStatus::fromArray(...), $list($data['repos']))
+ : null,
+ sources: is_array($data['sources'] ?? null)
+ ? array_map(DeveloperSearchSourceStatus::fromArray(...), $list($data['sources']))
+ : null,
+ );
+ }
+
+ public function isSuccess(): bool
+ {
+ return $this->success;
+ }
+
+ /** Whether the API marked the response as partial. */
+ public function isPartial(): bool
+ {
+ return $this->partial;
+ }
+
+ /** @return list<DeveloperSearchResult> */
+ public function getResults(): array
+ {
+ return $this->results;
+ }
+
+ /**
+ * Present only when the repos filter was set.
+ *
+ * @return list<DeveloperSearchRepoStatus>|null
+ */
+ public function getRepos(): ?array
+ {
+ return $this->repos;
+ }
+
+ /**
+ * Present only when the sources filter was set.
+ *
+ * @return list<DeveloperSearchSourceStatus>|null
+ */
+ public function getSources(): ?array
+ {
+ return $this->sources;
+ }
+}
diff --git a/apps/php-sdk/src/Models/DeveloperSearchResult.php b/apps/php-sdk/src/Models/DeveloperSearchResult.php
new file mode 100644
index 000000000..fb7e333de
--- /dev/null
+++ b/apps/php-sdk/src/Models/DeveloperSearchResult.php
@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/** One ranked developer search result. */
+final class DeveloperSearchResult
+{
+ /**
+ * @param list<DeveloperSearchPassage> $passages
+ * @param string|array<string, mixed>|null $license
+ */
+ public function __construct(
+ private readonly string $id = '',
+ private readonly string $url = '',
+ private readonly ?string $title = null,
+ private readonly array $passages = [],
+ private readonly string|array|null $license = null,
+ ) {}
+
+ /** @param array<string, mixed> $data */
+ public static function fromArray(array $data): self
+ {
+ $passages = is_array($data['passages'] ?? null) ? $data['passages'] : [];
+ $license = $data['license'] ?? null;
+
+ return new self(
+ id: (string) ($data['id'] ?? ''),
+ url: (string) ($data['url'] ?? ''),
+ title: isset($data['title']) ? (string) $data['title'] : null,
+ passages: array_map(
+ static fn (array $passage): DeveloperSearchPassage => DeveloperSearchPassage::fromArray($passage),
+ array_values(array_filter($passages, 'is_array')),
+ ),
+ license: is_string($license) || is_array($license) ? $license : null,
+ );
+ }
+
+ public function getId(): string
+ {
+ return $this->id;
+ }
+
+ public function getUrl(): string
+ {
+ return $this->url;
+ }
+
+ public function getTitle(): ?string
+ {
+ return $this->title;
+ }
+
+ /** @return list<DeveloperSearchPassage> */
+ public function getPassages(): array
+ {
+ return $this->passages;
+ }
+
+ /**
+ * An SPDX identifier string, or a disclosure object (as an array) when the license is not a plain identifier.
+ *
+ * @return string|array<string, mixed>|null
+ */
+ public function getLicense(): string|array|null
+ {
+ return $this->license;
+ }
+}
diff --git a/apps/php-sdk/src/Models/DeveloperSearchSourceStatus.php b/apps/php-sdk/src/Models/DeveloperSearchSourceStatus.php
new file mode 100644
index 000000000..adebcfe3b
--- /dev/null
+++ b/apps/php-sdk/src/Models/DeveloperSearchSourceStatus.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/** Whether a requested documentation source is indexed. */
+final class DeveloperSearchSourceStatus
+{
+ public function __construct(
+ private readonly string $source = '',
+ private readonly bool $indexed = false,
+ ) {}
+
+ /** @param array<string, mixed> $data */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ source: (string) ($data['source'] ?? ''),
+ indexed: (bool) ($data['indexed'] ?? false),
+ );
+ }
+
+ public function getSource(): string
+ {
+ return $this->source;
+ }
+
+ public function isIndexed(): bool
+ {
+ return $this->indexed;
+ }
+}
diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.php
index c8ab50163..4179761c8 100644
--- a/apps/php-sdk/src/Version.php
+++ b/apps/php-sdk/src/Version.php
@@ -6,5 +6,5 @@ namespace Firecrawl;
final class Version
{
- public const SDK_VERSION = '1.16.5';
+ public const SDK_VERSION = '1.16.6';
}
diff --git a/apps/php-sdk/tests/Unit/DeveloperSearchTest.php b/apps/php-sdk/tests/Unit/DeveloperSearchTest.php
new file mode 100644
index 000000000..4d8613af4
--- /dev/null
+++ b/apps/php-sdk/tests/Unit/DeveloperSearchTest.php
@@ -0,0 +1,136 @@
+<?php
+
+declare(strict_types=1);
+
+use Firecrawl\Exceptions\FirecrawlException;
+use Firecrawl\Models\DeveloperSearchOptions;
+use Firecrawl\Version;
+use GuzzleHttp\Psr7\Response;
+
+it('posts the query, filters and origin to the developer index', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode([
+ 'success' => true,
+ 'partial' => false,
+ 'results' => [
+ [
+ 'id' => 'issue:square/okhttp#1',
+ 'url' => 'https://github.com/square/okhttp/issues/1',
+ 'title' => 'retry',
+ 'passages' => [['text' => 'use backoff', 'citation_url' => 'https://github.com/square/okhttp/issues/1#c1']],
+ 'license' => ['state' => 'licensed', 'spdx_id' => 'Apache-2.0'],
+ ],
+ [
+ 'id' => 'readme:square/okhttp',
+ 'url' => 'https://github.com/square/okhttp',
+ 'passages' => [],
+ 'license' => 'Apache-2.0',
+ ],
+ ],
+ 'repos' => [[
+ 'repo' => 'square/okhttp',
+ 'indexed' => true,
+ 'types' => ['issue' => true, 'pullRequest' => true, 'readme' => false],
+ ]],
+ ])),
+ ], $history);
+
+ $response = $client->developerSearch('retry backoff', DeveloperSearchOptions::with(
+ k: 5,
+ types: ['issue'],
+ repos: ['square/okhttp'],
+ minStars: 100,
+ ));
+
+ $request = $history[0]['request'];
+ expect($request->getMethod())->toBe('POST');
+ expect($request->getUri()->getPath())->toBe('/v2/search/developer');
+
+ $body = json_decode((string) $request->getBody(), true);
+ expect($body)->toBe([
+ 'query' => 'retry backoff',
+ 'k' => 5,
+ 'types' => ['issue'],
+ 'repos' => ['square/okhttp'],
+ 'min_stars' => 100,
+ 'origin' => 'php-sdk@' . Version::SDK_VERSION,
+ ]);
+
+ expect($response->isSuccess())->toBeTrue();
+ expect($response->isPartial())->toBeFalse();
+ expect($response->getResults())->toHaveCount(2);
+
+ $first = $response->getResults()[0];
+ expect($first->getId())->toBe('issue:square/okhttp#1');
+ expect($first->getTitle())->toBe('retry');
+ expect($first->getPassages()[0]->getCitationUrl())->toBe('https://github.com/square/okhttp/issues/1#c1');
+ expect($first->getLicense())->toBe(['state' => 'licensed', 'spdx_id' => 'Apache-2.0']);
+
+ $second = $response->getResults()[1];
+ expect($second->getTitle())->toBeNull();
+ expect($second->getLicense())->toBe('Apache-2.0');
+
+ $repo = $response->getRepos()[0];
+ expect($repo->getRepo())->toBe('square/okhttp');
+ expect($repo->isIndexed())->toBeTrue();
+ expect($repo->getTypes()['pullRequest'])->toBeTrue();
+ expect($repo->getTypes()['readme'])->toBeFalse();
+ expect($response->getSources())->toBeNull();
+});
+
+it('sends only the query and origin when no options are given', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'results' => []])),
+ ], $history);
+
+ $response = $client->developerSearch('okhttp interceptor');
+
+ $body = json_decode((string) $history[0]['request']->getBody(), true);
+ expect(array_keys($body))->toBe(['query', 'origin']);
+ expect($response->getResults())->toBe([]);
+ expect($response->getRepos())->toBeNull();
+});
+
+it('rejects a blank query before sending a request', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([], $history);
+
+ expect(fn () => $client->developerSearch(' '))->toThrow(FirecrawlException::class, 'Query cannot be empty');
+ expect($history)->toHaveCount(0);
+});
+
+it('serializes every developer search filter with the API field names', function (): void {
+ $options = DeveloperSearchOptions::with(
+ k: 10,
+ passages: 2,
+ types: ['doc'],
+ repos: ['square/okhttp'],
+ sources: ['okhttp-docs'],
+ language: 'Kotlin',
+ topic: ['http'],
+ license: 'Apache-2.0',
+ minStars: 10,
+ maxStars: 1000,
+ archived: false,
+ fork: false,
+ skills: 'only',
+ );
+
+ expect($options->toArray())->toBe([
+ 'k' => 10,
+ 'passages' => 2,
+ 'types' => ['doc'],
+ 'repos' => ['square/okhttp'],
+ 'sources' => ['okhttp-docs'],
+ 'language' => 'Kotlin',
+ 'topic' => ['http'],
+ 'license' => 'Apache-2.0',
+ 'min_stars' => 10,
+ 'max_stars' => 1000,
+ 'archived' => false,
+ 'fork' => false,
+ 'skills' => 'only',
+ ]);
+});