PHPackages phpdevkits/forge-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. phpdevkits/forge-sdk ActiveLibrary[API Development](/categories/api) phpdevkits/forge-sdk ==================== PHP SDK for Laravel Forge — a modern, type-safe client for the Forge API, built on Saloon. v0.1.0(2w ago)00[11 issues](https://github.com/phpdevkits/forge-sdk/issues)[1 PRs](https://github.com/phpdevkits/forge-sdk/pulls)MITPHPPHP ^8.4CI passing Since May 14Pushed 2w agoCompare [ Source](https://github.com/phpdevkits/forge-sdk)[ Packagist](https://packagist.org/packages/phpdevkits/forge-sdk)[ GitHub Sponsors](https://github.com/fbarrento)[ GitHub Sponsors](https://github.com/phpdevkits)[ RSS](/packages/phpdevkits-forge-sdk/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (11)Versions (30)Used By (0) Forge SDK ========= [](#forge-sdk) [![Tests](https://github.com/phpdevkits/forge-sdk/actions/workflows/tests.yml/badge.svg)](https://github.com/phpdevkits/forge-sdk/actions) [![Total Downloads](https://camo.githubusercontent.com/1ba28ccbf709af63e5d610ef23d9a11e15d2783c4f5399e20cc17d00f6b08d58/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7068706465766b6974732f666f7267652d73646b)](https://packagist.org/packages/phpdevkits/forge-sdk) [![Latest Version](https://camo.githubusercontent.com/f34f4fb71e6ba7401cd841b73c698dc045f495409559cbd6740422ed744e06cb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068706465766b6974732f666f7267652d73646b)](https://packagist.org/packages/phpdevkits/forge-sdk) [![License](https://camo.githubusercontent.com/c8e31dae7e94f2d9628fda698b37bdf50c5bb10bf73691b24c6b11f6ba37bc71/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7068706465766b6974732f666f7267652d73646b)](https://packagist.org/packages/phpdevkits/forge-sdk) --- **Forge SDK** is an ultra-strict, type-safe PHP client for the [Laravel Forge API](https://forge.laravel.com/api-documentation), built on [Saloon v3](https://docs.saloon.dev/). It is engineered for developers who want to automate their Forge infrastructure with the same rigor they apply to their application code — fully typed, immutable, and fail-fast. Why This SDK? ------------- [](#why-this-sdk) The Forge API is JSON:API with cursor pagination, async endpoints, and more than a few places where the documented schema and the live behavior disagree. This SDK absorbs all of that so you don't have to: - **100% Type Coverage**: Every method, property, and parameter is explicitly typed — no `mixed`, no array soup. - **Immutable, hydrated DTOs**: Responses become `final readonly` objects (`Server`, `Site`, `Deployment`, …) with typed fields and `DateTimeImmutable` dates, not loose arrays. - **Fail-fast, typed exceptions**: Every non-2xx response throws a specific exception (`ValidationException`, `NotFoundException`, `RateLimitException`, …) so errors surface at the call site, never silently. - **Pagination that gets out of your way**: Cursor pagination is wrapped in `Page` with a lazy `iterate()` that walks every page for you. - **Framework-agnostic**: No Laravel required. It's plain Saloon — drop it into any PHP 8.4+ project. - **Battle-tested against the real API**: 100% test coverage, with every fixture recorded against live Forge and scrubbed of PII. Spec-vs-runtime divergences we've hit (and how the SDK handles them) are catalogued in [`docs/FINDINGS.md`](docs/FINDINGS.md). Getting Started --------------- [](#getting-started) > **Requires [PHP 8.4+](https://php.net/releases/).** Install via [Composer](https://getcomposer.org): ``` composer require phpdevkits/forge-sdk ``` Grab a personal access token from your [Forge API settings](https://forge.laravel.com/user-profile/api), then build a `Forge` client one of three ways: ``` use PhpDevKits\ForgeSdk\Forge; // 1. Explicit $forge = new Forge(token: 'your-forge-api-token', organization: 'acme'); // 2. From environment (FORGE_TOKEN, optional FORGE_ORGANIZATION) $forge = Forge::fromEnvironment(); // 3. From a JSON config file — ./forge.json, or $FORGE_CONFIG_PATH, or an explicit path $forge = Forge::fromConfig(); ``` The `forge.json` shape: ``` { "token": "your-forge-api-token", "organization": "acme" } ``` Usage ----- [](#usage) ### The authenticated user, organizations, and the provider catalog [](#the-authenticated-user-organizations-and-the-provider-catalog) ``` $user = $forge->me(); // User DTO foreach ($forge->organizations()->iterate() as $organization) { echo $organization->slug.PHP_EOL; } $providers = $forge->providers()->all(); // Page $regions = $forge->provider('digitalocean')->regions()->all(); ``` ### Organization context [](#organization-context) Org-scoped resources read the organization from the constructor / env / config, or you can switch context per call with an immutable clone: ``` $servers = $forge->org('another-org')->servers()->all(); // doesn't mutate $forge ``` Calling an org-scoped resource with no organization set throws `OrganizationNotSetException`. ### Servers [](#servers) ``` use PhpDevKits\ForgeSdk\Data\CreateServerData; use PhpDevKits\ForgeSdk\Data\HetznerServerConfig; use PhpDevKits\ForgeSdk\Enums\{PhpVersion, ServerType, UbuntuVersion}; $server = $forge->servers()->create(new CreateServerData( name: 'web-1', provider: 'hetzner', type: ServerType::App, ubuntuVersion: UbuntuVersion::Ubuntu2404, phpVersion: PhpVersion::Php84, hetzner: new HetznerServerConfig(regionId: 'fsn1', sizeId: 'cax11', networkId: 12345), )); $forge->server($server->id)->reboot(); $forge->server($server->id)->delete(); ``` ### Sites & deployments [](#sites--deployments) ``` use PhpDevKits\ForgeSdk\Data\{CreateSiteData, UpdateDeploymentScriptData}; use PhpDevKits\ForgeSdk\Enums\SiteType; $site = $forge->server($serverId)->sites()->create(new CreateSiteData( type: SiteType::Laravel, name: 'app', domainMode: 'on-forge', )); $forge->server($serverId)->site($site->id) ->deploymentScript()->update(new UpdateDeploymentScriptData(content: $script)); $deployment = $forge->server($serverId)->site($site->id)->deploy(); // Deployment DTO ``` ### SSH keys & daemons [](#ssh-keys--daemons) ``` use PhpDevKits\ForgeSdk\Data\{CreateSshKeyData, CreateDaemonData}; use PhpDevKits\ForgeSdk\Enums\DaemonUser; $forge->server($serverId)->sshKeys()->create(new CreateSshKeyData(name: 'laptop', key: $publicKey)); $forge->server($serverId)->daemons()->create(new CreateDaemonData( name: 'queue-worker', command: 'php artisan queue:work', user: DaemonUser::Forge, )); $forge->server($serverId)->daemon($daemonId)->restart(); ``` ### Pagination [](#pagination) Every collection exposes `all(?Options)` for a single `Page` and `iterate(?Options)` for a lazy `Generator` across all pages: ``` $page = $forge->servers()->all(new ListServersOptions(size: 25, provider: 'hetzner')); if ($page->hasMore()) { $next = $forge->servers()->all(new ListServersOptions(cursor: $page->nextCursor)); } foreach ($forge->servers()->iterate() as $server) { // walks every page automatically } ``` ### Testing your own code [](#testing-your-own-code) It's Saloon underneath, so you can fake Forge in your own suite without touching the network: ``` use PhpDevKits\ForgeSdk\Forge; use PhpDevKits\ForgeSdk\Requests\Me\GetMe; use Saloon\Http\Faking\{MockClient, MockResponse}; $mock = new MockClient([ GetMe::class => MockResponse::make([ 'data' => [ 'id' => '1', 'type' => 'users', 'attributes' => ['name' => 'Test User', 'email' => 'test@example.com'], 'links' => ['self' => ['href' => 'https://forge.laravel.com/api/user']], ], ]), ]); $forge = new Forge('test-token')->withMockClient($mock); ``` > **Tracks the Forge API while it is `v0.x` — minor versions of this SDK may include breaking changes until `1.0`.** Development ----------- [](#development) ``` composer install composer test # full suite: lint, static analysis, type coverage, unit composer test:unit # pest only composer lint # pint + rector autofix ``` Contributing ------------ [](#contributing) Pull requests are welcome — please open an issue first for anything non-trivial so we can agree on the shape. License ------- [](#license) **Forge SDK** was created by **[Francisco Barrento](https://github.com/fbarrento)** under the **[MIT license](https://opensource.org/licenses/MIT)**. ### Health Score 41 — FairBetter than 87% of packages Maintenance97 Actively maintained with recent releases Popularity0 Limited adoption so far Community8 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 96.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 16d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/55e5f328060e43ab78736d6d3b53dd144fe8f175774d77d2bf86985cb8451b21?d=identicon)[fbarrento](/maintainers/fbarrento) --- Top Contributors [![fbarrento](https://avatars.githubusercontent.com/u/8377450?v=4)](https://github.com/fbarrento "fbarrento (29 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)") --- Tags phplaravelsdksaloonapi clientforgelaravel-forge ### Code Quality TestsPest Static AnalysisPHPStan, Rector Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/phpdevkits-forge-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/phpdevkits-forge-sdk/health.svg)](https://phpackages.com/packages/phpdevkits-forge-sdk) ``` ### Alternatives [saloonphp/laravel-plugin The official Laravel plugin for Saloon 806.6M184](/packages/saloonphp-laravel-plugin)[octw/aramex A Library to integrate with Aramex APIs 2926.2k](/packages/octw-aramex)[wxm/pdd-sdk 拼多多 SDK 封装, 调用简单、语义化增强。支持 Laravel/Lumen。 154.8k](/packages/wxm-pdd-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)