Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(php-sdk): add developer search (#5276)
Erik Engervallcebc195e783a
diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.mdindex 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### Fixeddiff --git a/apps/php-sdk/README.md b/apps/php-sdk/README.mdindex 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```phpdiff --git a/apps/php-sdk/src/Client/FirecrawlClient.php b/apps/php-sdk/src/Client/FirecrawlClient.phpindex 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.phpnew file mode 100644index 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.phpnew file mode 100644index 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.phpnew file mode 100644index 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.phpnew file mode 100644index 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.phpnew file mode 100644index 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.phpnew file mode 100644index 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.phpindex 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.phpnew file mode 100644index 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',+ ]);+});