Skip to content

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

fix(php-sdk): use UUID-formatted crawl idempotency keys

Kris Oeiaf25dae5d02b
diff --git a/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php b/apps/php-sdk/src/Laravel/Tools/FirecrawlCrawl.php
index 57de61109..f70521a9f 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
limit: $limit,
scrapeOptions: ScrapeOptions::with(formats: ['markdown']),
integration: self::INTEGRATION,
- idempotencyKey: bin2hex(random_bytes(16)),
+ idempotencyKey: $this->newIdempotencyKey(),
),
);
@@ -76,6 +76,18 @@ class FirecrawlCrawl extends FirecrawlTool
});
}
+ /**
+ * The API only accepts UUID-formatted idempotency keys.
+ */
+ private function newIdempotencyKey(): string
+ {
+ $bytes = random_bytes(16);
+ $bytes[6] = chr((ord($bytes[6]) & 0x0f) | 0x40);
+ $bytes[8] = chr((ord($bytes[8]) & 0x3f) | 0x80);
+
+ return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4));
+ }
+
/**
* The status field keeps failed or cancelled crawls visible even when
* partial pages came back. Pagination cursors are reported, not
diff --git a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlCrawlTest.php b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlCrawlTest.php
index aacadacf6..a11d7f198 100644
--- a/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlCrawlTest.php
+++ b/apps/php-sdk/tests/Unit/LaravelTools/FirecrawlCrawlTest.php
@@ -39,7 +39,8 @@ it('crawls a site and returns status and pages as JSON', function (): void {
expect($body['limit'])->toBe(5);
expect($body['scrapeOptions']['formats'])->toBe(['markdown']);
expect($body['integration'])->toBe('_laravel-ai');
- expect($history[0]['request']->getHeaderLine('x-idempotency-key'))->toMatch('/^[0-9a-f]{32}$/');
+ expect($history[0]['request']->getHeaderLine('x-idempotency-key'))
+ ->toMatch('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/');
});
it('clamps the page limit between 1 and 25', function (): void {
@@ -73,7 +74,7 @@ it('reuses the same idempotency key across HTTP retries of the start request', f
$retryKey = $history[1]['request']->getHeaderLine('x-idempotency-key');
expect($history[0]['request']->getMethod())->toBe('POST');
expect($history[1]['request']->getMethod())->toBe('POST');
- expect($firstKey)->toMatch('/^[0-9a-f]{32}$/');
+ expect($firstKey)->toMatch('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/');
expect($retryKey)->toBe($firstKey);
});