Skip to content

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

feat(php): add getParseFormats for GET /v2/parse/formats (#4913)

Gergő Móricz40cab376d905
diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.md
index 6d6663a05..87e286058 100644
--- a/apps/php-sdk/CHANGELOG.md
+++ b/apps/php-sdk/CHANGELOG.md
@@ -5,6 +5,13 @@ 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.1] - 2026-10-02
+
+### Added
+- `getParseFormats()` returning a list of `ParseFormat` models (format, kind,
+ extensions, MIME types, availability) from `GET /v2/parse/formats`. Kinds
+ the SDK does not know yet are kept as plain strings.
+
## [1.16.0] - 2026-09-08
### Added
diff --git a/apps/php-sdk/README.md b/apps/php-sdk/README.md
index a9b8badcc..714116f37 100644
--- a/apps/php-sdk/README.md
+++ b/apps/php-sdk/README.md
@@ -153,6 +153,17 @@ $doc = $client->parse($file, ParseOptions::with(
echo $doc->getMarkdown();
```
+List the file formats parse accepts on the deployment you are calling.
+Image formats report `isAvailable() === false` when image OCR is disabled.
+
+```php
+foreach ($client->getParseFormats() as $format) {
+ echo $format->getFormat() . ' (' . $format->getKind() . '): '
+ . implode(', ', $format->getExtensions())
+ . ($format->isAvailable() ? '' : ' [unavailable]') . "\n";
+}
+```
+
### Crawl
```php
diff --git a/apps/php-sdk/src/Client/FirecrawlClient.php b/apps/php-sdk/src/Client/FirecrawlClient.php
index 836f5dbcd..c057b9249 100644
--- a/apps/php-sdk/src/Client/FirecrawlClient.php
+++ b/apps/php-sdk/src/Client/FirecrawlClient.php
@@ -32,6 +32,7 @@ use Firecrawl\Models\Monitor;
use Firecrawl\Models\MonitorCheck;
use Firecrawl\Models\MonitorCheckDetail;
use Firecrawl\Models\ParseFile;
+use Firecrawl\Models\ParseFormat;
use Firecrawl\Models\ParseOptions;
use Firecrawl\Models\ScrapeOptions;
use Firecrawl\Models\SearchData;
@@ -259,6 +260,21 @@ final class FirecrawlClient
return Document::fromArray($response['data'] ?? $response);
}
+ /**
+ * List the file formats the parse endpoint accepts on this deployment.
+ *
+ * @return list<ParseFormat>
+ */
+ public function getParseFormats(): array
+ {
+ $response = $this->http->get('/v2/parse/formats');
+
+ return array_values(array_map(
+ static fn (array $item): ParseFormat => ParseFormat::fromArray($item),
+ array_filter($response['data']['formats'] ?? [], 'is_array'),
+ ));
+ }
+
// ================================================================
// CRAWL
// ================================================================
diff --git a/apps/php-sdk/src/Laravel/Facades/Firecrawl.php b/apps/php-sdk/src/Laravel/Facades/Firecrawl.php
index f4cdc7142..49f77d549 100644
--- a/apps/php-sdk/src/Laravel/Facades/Firecrawl.php
+++ b/apps/php-sdk/src/Laravel/Facades/Firecrawl.php
@@ -21,6 +21,7 @@ use Firecrawl\Models\CreditUsage;
use Firecrawl\Models\Document;
use Firecrawl\Models\MapData;
use Firecrawl\Models\MapOptions;
+use Firecrawl\Models\ParseFormat;
use Firecrawl\Models\ScrapeOptions;
use Firecrawl\Models\SearchData;
use Firecrawl\Models\SearchOptions;
@@ -46,6 +47,7 @@ use Illuminate\Support\Facades\Facade;
* @method static BrowserListResponse listBrowsers(?string $status = null)
* @method static ConcurrencyCheck getConcurrency()
* @method static CreditUsage getCreditUsage()
+ * @method static list<ParseFormat> getParseFormats()
*
* @see FirecrawlClient
*/
diff --git a/apps/php-sdk/src/Models/ParseFormat.php b/apps/php-sdk/src/Models/ParseFormat.php
new file mode 100644
index 000000000..b20f000f4
--- /dev/null
+++ b/apps/php-sdk/src/Models/ParseFormat.php
@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/**
+ * A file format accepted by the parse endpoint.
+ *
+ * The kind is kept as a plain string so values added by the API later still
+ * parse; compare it against the KIND_* constants.
+ */
+final class ParseFormat
+{
+ public const KIND_DOCUMENT = 'document';
+ public const KIND_IMAGE = 'image';
+
+ /**
+ * @param list<string> $extensions
+ * @param list<string> $mimeTypes
+ */
+ public function __construct(
+ private readonly string $format = '',
+ private readonly string $kind = '',
+ private readonly array $extensions = [],
+ private readonly array $mimeTypes = [],
+ private readonly bool $available = false,
+ ) {}
+
+ /** @param array<string, mixed> $data */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ format: (string) ($data['format'] ?? ''),
+ kind: (string) ($data['kind'] ?? ''),
+ extensions: self::stringList($data['extensions'] ?? []),
+ mimeTypes: self::stringList($data['mimeTypes'] ?? []),
+ available: ($data['available'] ?? false) === true,
+ );
+ }
+
+ public function getFormat(): string
+ {
+ return $this->format;
+ }
+
+ public function getKind(): string
+ {
+ return $this->kind;
+ }
+
+ public function isDocument(): bool
+ {
+ return $this->kind === self::KIND_DOCUMENT;
+ }
+
+ public function isImage(): bool
+ {
+ return $this->kind === self::KIND_IMAGE;
+ }
+
+ /** @return list<string> */
+ public function getExtensions(): array
+ {
+ return $this->extensions;
+ }
+
+ /** @return list<string> */
+ public function getMimeTypes(): array
+ {
+ return $this->mimeTypes;
+ }
+
+ public function isAvailable(): bool
+ {
+ return $this->available;
+ }
+
+ /** @return list<string> */
+ private static function stringList(mixed $value): array
+ {
+ if (!is_array($value)) {
+ return [];
+ }
+
+ return array_values(array_map('strval', array_filter($value, 'is_scalar')));
+ }
+}
diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.php
index 211466806..8732d8c01 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.0';
+ public const SDK_VERSION = '1.16.1';
}
diff --git a/apps/php-sdk/tests/Unit/ParseFormatsTest.php b/apps/php-sdk/tests/Unit/ParseFormatsTest.php
new file mode 100644
index 000000000..f5cbbbfa3
--- /dev/null
+++ b/apps/php-sdk/tests/Unit/ParseFormatsTest.php
@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+use Firecrawl\Exceptions\AuthenticationException;
+use Firecrawl\Exceptions\FirecrawlException;
+use Firecrawl\Models\ParseFormat;
+use GuzzleHttp\Psr7\Response;
+
+it('fetches parse formats from GET /v2/parse/formats', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode([
+ 'success' => true,
+ 'data' => [
+ 'formats' => [
+ [
+ 'format' => 'pdf',
+ 'kind' => 'document',
+ 'extensions' => ['.pdf'],
+ 'mimeTypes' => ['application/pdf'],
+ 'available' => true,
+ ],
+ [
+ 'format' => 'png',
+ 'kind' => 'image',
+ 'extensions' => ['.png'],
+ 'mimeTypes' => ['image/png'],
+ 'available' => false,
+ ],
+ ],
+ ],
+ ])),
+ ], $history);
+
+ $formats = $client->getParseFormats();
+
+ $request = $history[0]['request'];
+ expect($request->getMethod())->toBe('GET');
+ expect($request->getUri()->getPath())->toBe('/v2/parse/formats');
+ expect($request->getHeaderLine('Authorization'))->toBe('Bearer fc-test');
+
+ expect($formats)->toHaveCount(2);
+ expect($formats[0])->toBeInstanceOf(ParseFormat::class);
+ expect($formats[0]->getFormat())->toBe('pdf');
+ expect($formats[0]->getKind())->toBe(ParseFormat::KIND_DOCUMENT);
+ expect($formats[0]->isDocument())->toBeTrue();
+ expect($formats[0]->getExtensions())->toBe(['.pdf']);
+ expect($formats[0]->getMimeTypes())->toBe(['application/pdf']);
+ expect($formats[0]->isAvailable())->toBeTrue();
+
+ expect($formats[1]->getFormat())->toBe('png');
+ expect($formats[1]->getKind())->toBe(ParseFormat::KIND_IMAGE);
+ expect($formats[1]->isImage())->toBeTrue();
+ expect($formats[1]->getMimeTypes())->toBe(['image/png']);
+ expect($formats[1]->isAvailable())->toBeFalse();
+});
+
+it('keeps unknown kinds and ignores unknown fields', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode([
+ 'success' => true,
+ 'data' => [
+ 'formats' => [
+ [
+ 'format' => 'mp4',
+ 'kind' => 'video',
+ 'extensions' => ['.mp4'],
+ 'mimeTypes' => ['video/mp4'],
+ 'available' => true,
+ 'maxSizeBytes' => 1024,
+ ],
+ ],
+ ],
+ ])),
+ ]);
+
+ $formats = $client->getParseFormats();
+
+ expect($formats)->toHaveCount(1);
+ expect($formats[0]->getFormat())->toBe('mp4');
+ expect($formats[0]->getKind())->toBe('video');
+ expect($formats[0]->isDocument())->toBeFalse();
+ expect($formats[0]->isImage())->toBeFalse();
+ expect($formats[0]->getMimeTypes())->toBe(['video/mp4']);
+});
+
+it('throws AuthenticationException on 401', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(401, [], json_encode(['success' => false, 'error' => 'Unauthorized'])),
+ ]);
+
+ $client->getParseFormats();
+})->throws(AuthenticationException::class, 'Unauthorized');
+
+it('throws FirecrawlException when the endpoint is missing', function (): void {
+ $client = fakeFirecrawlClient([
+ new Response(404, [], json_encode(['success' => false, 'error' => 'Not found'])),
+ ]);
+
+ $client->getParseFormats();
+})->throws(FirecrawlException::class, 'Not found');