Skip to content

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

feat(php-sdk): add versioning, CI workflows, and publishing infrastructure

firecrawl-spring[bot]769d778d80e1
diff --git a/.github/scripts/check_version_has_incremented.py b/.github/scripts/check_version_has_incremented.py
index 34c56d838..295e46594 100644
--- a/.github/scripts/check_version_has_incremented.py
+++ b/.github/scripts/check_version_has_incremented.py
@@ -3,7 +3,7 @@ checks local versions against published versions.
# Usage:
-python .github/scripts/check_version_has_incremented.py js ./apps/js-sdk/firecrawl @mendable/firecrawl-js
+python .github/scripts/check_version_has_incremented.py js ./apps/js-sdk/firecrawl @mendable/firecrawl-js
Local version: 0.0.22
Published version: 0.0.21
true
@@ -18,6 +18,11 @@ Local version: 1.0.0
Published version: 0.0.0 (0.0.0 means not yet published on Maven Central)
true
+python .github/scripts/check_version_has_incremented.py php ./apps/php-sdk firecrawl/firecrawl-php
+Local version: 1.0.0
+Published version: 0.0.0 (0.0.0 means not yet published on Packagist)
+true
+
"""
import json
import os
@@ -82,6 +87,36 @@ def get_maven_central_version(package_name: str) -> str:
return version_match.group(1).strip()
return "0.0.0"
+def get_php_version(file_path: str) -> str:
+ """Extract version string from PHP Version.php file."""
+ version_file = Path(file_path).read_text()
+ version_match = re.search(r"SDK_VERSION\s*=\s*['\"]([^'\"]*)['\"]", version_file)
+ if version_match:
+ return version_match.group(1).strip()
+ raise RuntimeError("Unable to find SDK_VERSION string in Version.php.")
+
+def get_packagist_version(package_name: str) -> str:
+ """Get latest version of PHP package from Packagist. package_name should be vendor/package."""
+ url = f"https://packagist.org/packages/{package_name}.json"
+ response = requests.get(url)
+ if response.status_code == 404:
+ return "0.0.0"
+ response.raise_for_status()
+ data = response.json()
+ package_data = data.get("package", {})
+ versions = package_data.get("versions", {})
+ # Filter out dev versions and find highest stable version
+ stable_versions = []
+ for v in versions:
+ if "dev" not in v and v.startswith("v"):
+ stable_versions.append(v.lstrip("v"))
+ elif "dev" not in v and re.match(r"^\d", v):
+ stable_versions.append(v)
+ if not stable_versions:
+ return "0.0.0"
+ stable_versions.sort(key=lambda x: parse_version(x), reverse=True)
+ return stable_versions[0]
+
# def get_rust_version(file_path: str) -> str:
# """Extract version string from Cargo.toml."""
# cargo_toml = toml.load(file_path)
@@ -121,6 +156,11 @@ if __name__ == "__main__":
current_version = get_gradle_version(os.path.join(package_path, 'build.gradle.kts'))
# Get published version from Maven Central
published_version = get_maven_central_version(package_name)
+ elif package_type == "php":
+ # Get current version from src/Version.php
+ current_version = get_php_version(os.path.join(package_path, 'src', 'Version.php'))
+ # Get published version from Packagist
+ published_version = get_packagist_version(package_name)
# if package_type == "rust":
# # Get current version from Cargo.toml
# current_version = get_rust_version(os.path.join(package_path, 'Cargo.toml'))
@@ -128,7 +168,7 @@ if __name__ == "__main__":
# published_version = get_crates_version(package_name)
else:
- raise ValueError("Invalid package type. Use 'python', 'js', or 'java'.")
+ raise ValueError("Invalid package type. Use 'python', 'js', 'java', or 'php'.")
# Print versions for debugging
# print(f"Local version: {current_version}")
diff --git a/.github/workflows/publish-php-sdk.yml b/.github/workflows/publish-php-sdk.yml
new file mode 100644
index 000000000..df15eb6a8
--- /dev/null
+++ b/.github/workflows/publish-php-sdk.yml
@@ -0,0 +1,54 @@
+name: Publish PHP SDK
+
+on:
+ workflow_dispatch:
+ push:
+ branches:
+ - main
+ paths:
+ - 'apps/php-sdk/**'
+
+jobs:
+ publish:
+ name: Publish to Packagist
+ runs-on: blacksmith-2vcpu-ubuntu-2404
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v5
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.x'
+
+ - name: Install version check dependencies
+ run: pip install requests packaging
+
+ - name: Run version check script
+ id: version_check
+ run: |
+ VERSION_INCREMENTED=$(python .github/scripts/check_version_has_incremented.py php ./apps/php-sdk firecrawl/firecrawl-php)
+ echo "VERSION_INCREMENTED=$VERSION_INCREMENTED" >> $GITHUB_ENV
+
+ - name: Set up PHP
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: '8.3'
+ tools: composer:v2
+
+ - name: Install dependencies
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ working-directory: ./apps/php-sdk
+ run: composer install --no-dev --prefer-dist --no-interaction
+
+ - name: Validate composer.json
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ working-directory: ./apps/php-sdk
+ run: composer validate --strict
+
+ - name: Notify Packagist
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ run: |
+ curl -s -X POST "https://packagist.org/api/update-package?username=${{ secrets.PACKAGIST_USERNAME }}&apiToken=${{ secrets.PACKAGIST_TOKEN }}" \
+ -d '{"repository":{"url":"https://github.com/firecrawl/firecrawl"}}'
diff --git a/.github/workflows/test-php-sdk.yml b/.github/workflows/test-php-sdk.yml
new file mode 100644
index 000000000..40d1ff7d5
--- /dev/null
+++ b/.github/workflows/test-php-sdk.yml
@@ -0,0 +1,123 @@
+name: PHP SDK Test Suite
+
+on:
+ pull_request:
+ branches:
+ - main
+ paths:
+ - apps/php-sdk/**
+ - .github/workflows/test-php-sdk.yml
+ push:
+ branches:
+ - main
+ paths:
+ - apps/php-sdk/**
+ workflow_dispatch:
+
+jobs:
+ lint:
+ name: Static Analysis
+ runs-on: blacksmith-2vcpu-ubuntu-2404
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: Set up PHP
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: '8.3'
+ tools: composer:v2
+
+ - name: Get Composer cache directory
+ id: composer-cache
+ working-directory: ./apps/php-sdk
+ run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+ - name: Cache Composer dependencies
+ uses: actions/cache@v4
+ with:
+ path: ${{ steps.composer-cache.outputs.dir }}
+ key: ${{ runner.os }}-composer-${{ hashFiles('apps/php-sdk/composer.json') }}
+ restore-keys: |
+ ${{ runner.os }}-composer-
+
+ - name: Install dependencies
+ working-directory: ./apps/php-sdk
+ run: composer install --prefer-dist --no-interaction
+
+ - name: Validate composer.json
+ working-directory: ./apps/php-sdk
+ run: composer validate --strict
+
+ - name: Run PHPStan
+ working-directory: ./apps/php-sdk
+ run: vendor/bin/phpstan analyse --no-progress
+
+ test:
+ name: Test (PHP ${{ matrix.php }}, Laravel ${{ matrix.laravel }})
+ runs-on: blacksmith-2vcpu-ubuntu-2404
+ if: >-
+ github.event_name == 'workflow_dispatch' ||
+ github.event_name == 'pull_request' ||
+ (github.event_name == 'push' && github.ref == 'refs/heads/main')
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - php: '8.1'
+ laravel: '10.*'
+ testbench: '8.*'
+ - php: '8.2'
+ laravel: '10.*'
+ testbench: '8.*'
+ - php: '8.2'
+ laravel: '11.*'
+ testbench: '9.*'
+ - php: '8.3'
+ laravel: '11.*'
+ testbench: '9.*'
+ - php: '8.3'
+ laravel: '12.*'
+ testbench: '10.*'
+ - php: '8.4'
+ laravel: '12.*'
+ testbench: '10.*'
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: Set up PHP ${{ matrix.php }}
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: ${{ matrix.php }}
+ tools: composer:v2
+ coverage: none
+
+ - name: Get Composer cache directory
+ id: composer-cache
+ working-directory: ./apps/php-sdk
+ run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+ - name: Cache Composer dependencies
+ uses: actions/cache@v4
+ with:
+ path: ${{ steps.composer-cache.outputs.dir }}
+ key: ${{ runner.os }}-php${{ matrix.php }}-laravel${{ matrix.laravel }}-composer-${{ hashFiles('apps/php-sdk/composer.json') }}
+ restore-keys: |
+ ${{ runner.os }}-php${{ matrix.php }}-laravel${{ matrix.laravel }}-composer-
+ ${{ runner.os }}-php${{ matrix.php }}-composer-
+
+ - name: Install dependencies with Laravel ${{ matrix.laravel }}
+ working-directory: ./apps/php-sdk
+ run: |
+ composer require "illuminate/contracts:${{ matrix.laravel }}" "illuminate/support:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+ composer update --prefer-dist --no-interaction
+
+ - name: Run unit tests
+ working-directory: ./apps/php-sdk
+ run: vendor/bin/pest --ci
+
+ - name: Run E2E tests
+ if: env.FIRECRAWL_API_KEY != ''
+ working-directory: ./apps/php-sdk
+ env:
+ FIRECRAWL_API_KEY: ${{ secrets.FIRECRAWL_API_KEY }}
+ run: vendor/bin/pest --ci --group=e2e
diff --git a/apps/php-sdk/.gitignore b/apps/php-sdk/.gitignore
index 93bc9f165..e9f24e62e 100644
--- a/apps/php-sdk/.gitignore
+++ b/apps/php-sdk/.gitignore
@@ -3,5 +3,6 @@
composer.lock
.phpunit.result.cache
.php-cs-fixer.cache
+.phpstan-cache
phpstan.neon
.env
diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.md
new file mode 100644
index 000000000..3289a0d27
--- /dev/null
+++ b/apps/php-sdk/CHANGELOG.md
@@ -0,0 +1,24 @@
+# Changelog
+
+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.0.0] - 2026-04-13
+
+### Added
+- Initial release with Firecrawl v2 API support
+- Scrape: `scrape()`, `interact()`, `stopInteractiveBrowser()`
+- Crawl: `crawl()`, `startCrawl()`, `getCrawlStatus()`, `cancelCrawl()`, `getCrawlErrors()`
+- Batch Scrape: `batchScrape()`, `startBatchScrape()`, `getBatchScrapeStatus()`, `cancelBatchScrape()`
+- Map: `map()`
+- Search: `search()`
+- Agent: `agent()`, `startAgent()`, `getAgentStatus()`, `cancelAgent()`
+- Browser: `browser()`, `browserExecute()`, `deleteBrowser()`, `listBrowsers()`
+- Usage: `getConcurrency()`, `getCreditUsage()`
+- Automatic polling with pagination for async jobs (crawl, batch scrape, agent)
+- Retry with exponential backoff for transient failures (408, 409, 502, 5xx)
+- Typed exception hierarchy: `FirecrawlException`, `AuthenticationException`, `RateLimitException`, `JobTimeoutException`
+- Laravel integration: auto-discovered service provider, publishable config, `Firecrawl` facade
+- PHP 8.1+ support with named parameters and readonly properties
diff --git a/apps/php-sdk/composer.json b/apps/php-sdk/composer.json
index 3c2032765..3760c4f67 100644
--- a/apps/php-sdk/composer.json
+++ b/apps/php-sdk/composer.json
@@ -12,6 +12,7 @@
"laravel",
"php"
],
+ "homepage": "https://firecrawl.dev",
"require": {
"php": "^8.1",
"guzzlehttp/guzzle": "^7.9",
@@ -20,10 +21,16 @@
},
"require-dev": {
"friendsofphp/php-cs-fixer": "^3",
- "orchestra/testbench": "^9|^10",
- "pestphp/pest": "^3",
- "phpstan/phpstan": "^2",
- "phpunit/phpunit": "^11"
+ "illuminate/contracts": "^10.0|^11.0|^12.0",
+ "illuminate/support": "^10.0|^11.0|^12.0",
+ "orchestra/testbench": "^8|^9|^10",
+ "pestphp/pest": "^2|^3",
+ "phpstan/phpstan": "^1|^2",
+ "phpunit/phpunit": "^10|^11"
+ },
+ "suggest": {
+ "illuminate/contracts": "Required for Laravel integration (^10.0|^11.0|^12.0)",
+ "illuminate/support": "Required for Laravel integration (^10.0|^11.0|^12.0)"
},
"autoload": {
"psr-4": {
diff --git a/apps/php-sdk/phpstan.neon.dist b/apps/php-sdk/phpstan.neon.dist
new file mode 100644
index 000000000..7f41d24e5
--- /dev/null
+++ b/apps/php-sdk/phpstan.neon.dist
@@ -0,0 +1,12 @@
+parameters:
+ level: 6
+ paths:
+ - src
+ tmpDir: .phpstan-cache
+ ignoreErrors:
+ # Laravel Facade and ServiceProvider may not be installed
+ -
+ message: '#Class Illuminate\\\\#'
+ paths:
+ - src/Laravel/*
+ reportUnmatched: false
diff --git a/apps/php-sdk/src/Client/FirecrawlHttpClient.php b/apps/php-sdk/src/Client/FirecrawlHttpClient.php
index 9837f79cb..47ebf560d 100644
--- a/apps/php-sdk/src/Client/FirecrawlHttpClient.php
+++ b/apps/php-sdk/src/Client/FirecrawlHttpClient.php
@@ -7,6 +7,7 @@ namespace Firecrawl\Client;
use Firecrawl\Exceptions\AuthenticationException;
use Firecrawl\Exceptions\FirecrawlException;
use Firecrawl\Exceptions\RateLimitException;
+use Firecrawl\Version;
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Exception\ConnectException;
@@ -81,6 +82,7 @@ final class FirecrawlHttpClient
'Authorization' => 'Bearer ' . $this->apiKey,
'Content-Type' => 'application/json',
'Accept' => 'application/json',
+ 'User-Agent' => 'firecrawl-php/' . Version::SDK_VERSION,
], $extraHeaders);
$options = [
diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.php
new file mode 100644
index 000000000..70b8e45a5
--- /dev/null
+++ b/apps/php-sdk/src/Version.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl;
+
+final class Version
+{
+ public const SDK_VERSION = '1.0.0';
+}