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 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.pyindex 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-jsLocal version: 0.0.22Published version: 0.0.21true@@ -18,6 +18,11 @@ Local version: 1.0.0Published 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 jsonimport 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 Centralpublished_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.ymlnew file mode 100644index 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.ymlnew file mode 100644index 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=e2ediff --git a/apps/php-sdk/.gitignore b/apps/php-sdk/.gitignoreindex 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-cachephpstan.neon.envdiff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.mdnew file mode 100644index 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 propertiesdiff --git a/apps/php-sdk/composer.json b/apps/php-sdk/composer.jsonindex 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.distnew file mode 100644index 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: falsediff --git a/apps/php-sdk/src/Client/FirecrawlHttpClient.php b/apps/php-sdk/src/Client/FirecrawlHttpClient.phpindex 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.phpnew file mode 100644index 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';+}