Forge Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/forge-sdk
   

   Add your Forge API token (found in Forge under Account > API Tokens) to your .env:

   FORGE_TOKEN=your_forge_api_token_here
   

2. First Use Case: Initialize the SDK in a service provider or command:

   use Laravel\Forge\Forge;
   
   $forge = new Forge(config('forge.token'));
   $servers = $forge->servers(); // Fetch all accessible servers
   

3. Key Starting Points:

   • Servers: List, create, or manage servers via $forge->servers().
   • Sites: Deploy a site with $forge->createSite($serverId, $params).
   • Databases: Create a database with $forge->createDatabase($serverId, $params).

Implementation Patterns

Core Workflows

1. Server Provisioning:

   $server = $forge->createServer([
       'provider' => \Laravel\Forge\ServerProviders::DIGITAL_OCEAN,
       'name' => 'api-server',
       'size' => '02',
       'region' => 'nyc3',
   ]);
   // Wait for provisioning (default: 30s timeout)
   $server->waitForProvisioning();
   

2. Site Deployment Automation:

   $site = $forge->createSite($serverId, [
       'name' => 'my-app.example.com',
       'repository' => 'git@github.com:user/repo.git',
   ]);
   // Trigger a deploy after setup
   $site->deploySite();
   

3. Database + User Setup:

   $db = $forge->createDatabase($serverId, [
       'name' => 'app_db',
       'type' => \Laravel\Forge\InstallableServices::MYSQL,
   ]);
   $user = $forge->createDatabaseUser($serverId, [
       'name' => 'app_user',
       'password' => 'secure_password',
       'databases' => [$db->id],
   ]);
   

4. Environment Management: Update .env files dynamically:

   $forge->updateSiteEnvironmentFile($serverId, $siteId, file_get_contents('.env'));
   

Integration Tips

• Laravel Artisan Commands: Create a command to automate server/site creation:

  use Laravel\Forge\Forge;
  
  class ForgeDeployCommand extends Command {
      protected $forge;
  
      public function __construct(Forge $forge) {
          $this->forge = $forge;
      }
  
      public function handle() {
          $server = $this->forge->server($this->argument('server_id'));
          $server->createSite([...]);
      }
  }
  

• Event Listeners: Trigger actions post-deployment (e.g., run migrations):

  $forge->createSite($serverId, $params, true); // Wait for completion
  $this->runMigrations(); // Custom logic after site is ready
  

• Configuration Management: Store Forge credentials in Laravel’s config/forge.php:

  'token' => env('FORGE_TOKEN'),
  'timeout' => 120, // Default timeout in seconds
  

• Error Handling: Wrap SDK calls in try-catch blocks:

  try {
      $forge->createSite($serverId, $params);
  } catch (\Laravel\Forge\Exceptions\TimeoutException $e) {
      Log::error("Site creation timed out: " . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Async Operations:

   • Methods like createSite() or createServer() may return immediately but require polling (e.g., $server->isReady()).
   • Fix: Use $wait = true (default) or manually check $resource->fresh()->status.

2. Rate Limiting:

   • Forge’s API enforces rate limits (~60 requests/minute).
   • Fix: Implement exponential backoff in retries:

     $attempts = 0;
     while ($attempts < 3) {
         try {
             $forge->createDatabase($serverId, $params);
             break;
         } catch (\GuzzleHttp\Exception\RequestException $e) {
             sleep(2 ** $attempts); // Exponential delay
             $attempts++;
         }
     }
     

3. Resource IDs:

   • IDs are not auto-incremented sequentially. Always fetch the latest resource list after creation:

     $site = $forge->createSite($serverId, $params);
     $updatedSites = $forge->sites($serverId); // Refresh list
     $site = collect($updatedSites)->firstWhere('name', $params['name']);
     

4. PHP Version Constraints:

   • Not all providers support all PHP versions (e.g., PHP_85 may not be available on Linode).
   • Fix: Fetch available versions first:

     $versions = $forge->server($serverId)->phpVersions();
     

5. SSH Key Management:

   • Deleting a key revokes access immediately. Ensure backups exist before deletion:

     $key = $forge->sshKey($serverId, $keyId);
     file_put_contents("backup_$keyId.pub", $key->key);
     $key->delete();
     

Debugging Tips

1. Enable Guzzle Debugging: Configure the SDK to log HTTP requests:

   $forge = new Forge($token, [
       'debug' => true,
       'handler' => \GuzzleHttp\HandlerStack::create(new \GuzzleHttp\Handler\CurlHandler()),
   ]);
   

2. Check Resource States: Use fresh() to reload a resource’s latest state:

   $site = $forge->site($serverId, $siteId)->fresh();
   if (!$site->isReady()) {
       throw new \RuntimeException("Site not provisioned yet.");
   }
   

3. Timeout Customization: Adjust timeouts for long-running operations (e.g., backups):

   $forge->setTimeout(300)->restoreBackup($serverId, $configId, $backupId);
   

Extension Points

1. Custom Resource Models: Extend the SDK’s resource classes (e.g., Server, Site) to add domain-specific methods:

   class CustomSite extends \Laravel\Forge\Resources\Site {
       public function enableMaintenanceMode() {
           $this->update(['maintenance_mode' => true]);
       }
   }
   

2. Webhook Integration: Use Forge’s webhooks to trigger Laravel events:

   // In Forge webhook endpoint
   $forge->createWebhook($serverId, $siteId, [
       'url' => route('forge.webhook'),
       'events' => ['deploy_started', 'deploy_finished'],
   ]);
   

3. Recipe Automation: Chain recipes for complex setups:

   $forge->runRecipe('laravel', ['php_version' => '8.2']);
   $forge->runRecipe('node', ['version' => '18']);
   

4. Backup Automation: Schedule backups via Laravel’s scheduler:

   $schedule->command('forge:backup-server {server_id}')->daily();
   

5. Provider-Specific Logic: Handle provider quirks (e.g., Linode vs. DigitalOcean):

   $server = $forge->server($serverId);
   if ($server->provider === \Laravel\Forge\ServerProviders::LINODE) {
       $server->update(['backup_enabled' => true]);
   }