v0.1.0 — First Forge

v0.1.0 — first public release

A modern, type-safe PHP SDK for the Laravel Forge API, built on Saloon v3. Requires PHP 8.4+.

Install

composer require phpdevkits/forge-sdk

Quick start

  use PhpDevKits\ForgeSdk\Forge;

  $forge = Forge::fromEnvironment(); // or new Forge($token, $org)

  // Catalog + account
  $forge->me();
  $forge->providers()->all();

  // Org-scoped resources (immutable chain override)
  $servers = $forge->org('acme')->servers()->all();

  // Drill into a server
  $server = $forge->server($id);
  $server->sshKeys()->create(new CreateSshKeyData(name: 'laptop', key: $pub));
  $site = $server->sites()->create(new CreateSiteData(
      type: SiteType::Laravel, name: 'app', domainMode: 'on-forge',
  ));

  // Deploy + watch
  $site = $forge->server($id)->site($siteId);
  $site->deploymentScript()->update(new UpdateDeploymentScriptData(content: $script));
  $deployment = $site->deploy();

What's included

• Connector — token auth, fromEnvironment() / fromConfig() factories, hybrid organization context
  ($forge->org($slug) immutable clone + OrganizationNotSetException guard).
• Typed exceptions over Saloon's AlwaysThrowOnErrors — BadRequest / Unauthorized / Forbidden / NotFound /
  Validation / RateLimit / Server / Connection.
• Cursor pagination — Page with all() and iterate() on every collection.
• Resources
  • Me
  • Organizations (list / get)
  • Providers catalog — providers, regions, sizes (region- and provider-scoped)
  • Servers — full CRUD + power actions (reboot / power-cycle)
  • SSH keys (per server) — list / get / create / delete
  • Sites (per server) — full CRUD, nested repository / maintenance_mode
  • Deployments (per site) — list / get / trigger, deploy-script get/update, $site->deploy() sugar
  • Daemons / background processes (per server) — full CRUD + actions + log()
• Enums for closed sets: Provider, ServerType, PhpVersion, DatabaseType, UbuntuVersion, ServerAction,
  SiteType, WwwRedirectType, SiteStatus, DeploymentStatus, DaemonUser, DaemonAction.

Quality

• 100% test coverage; fixtures recorded against the live Forge API with PII redaction.
• Forge spec-vs-runtime divergences documented in docs/FINDINGS.md.

Known limitations

• SSL certificate management isn't wrapped yet (#25) — .on-forge.com sites may need a cert issued via the
  Forge dashboard.
• Server create doesn't yet surface the one-time sudo_password (#30).

Full changelog: see CHANGELOG.md.