Forge Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/forge-sdk
   

   Add your Forge API token to your .env or configuration:

   FORGE_TOKEN=your_forge_api_token_here
   

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

   $forge = new Laravel\Forge\Forge(config('forge.token'));
   

   Fetch all servers to verify connectivity:

   $servers = $forge->servers();
   

3. Key Starting Points:

   • Forge API Docs (for parameter reference)
   • SDK Source (for advanced usage)

Implementation Patterns

Core Workflows

Server Management

• Provisioning:

  $server = $forge->createServer([
      'provider' => ServerProviders::DIGITAL_OCEAN,
      'name' => 'api-server',
      'size' => '02',
      'region' => 'nyc1',
  ]);
  

  Tip: Use $server->waitForReady() to block until provisioning completes.

• Bulk Operations:

  foreach ($forge->servers() as $server) {
      if ($server->size === '01') {
          $server->update(['size' => '02']);
      }
  }
  

Site Deployment Automation

• Git Deployment Pipeline:

  $site = $forge->site($serverId, $siteId);
  $site->installGitRepository(['repository' => 'git@github.com:user/repo.git']);
  $site->deploySite(); // Triggers a deployment
  

• Post-Deploy Hooks:

  $forge->executeSiteCommand($serverId, $siteId, [
      'command' => 'php artisan queue:work --daemon',
  ]);
  

Database Synchronization

• User Permissions:

  $db = $forge->database($serverId, $dbId);
  $db->createUser(['name' => 'app_user', 'password' => 'secure123']);
  $db->grantUserAccess(['user_id' => $userId, 'database_id' => $dbId]);
  

Configuration Management

• Nginx Templates:

  $template = $forge->createNginxTemplate($serverId, [
      'name' => 'custom-php-fpm',
      'content' => file_get_contents('nginx.conf'),
  ]);
  $forge->updateSiteNginxFile($serverId, $siteId, $template->content);
  

Integration Tips

1. Laravel Artisan Commands: Create a command to manage Forge resources:

   php artisan forge:create-server --name=blog --size=01
   

   Example Command:

   $forge = resolve(Forge::class);
   $forge->createServer($this->option('parameters'));
   

2. Event Listeners: Trigger actions on Forge webhook events (e.g., deployment success):

   public function handle(DeploymentSucceeded $event) {
       $forge->executeSiteCommand($event->serverId, $event->siteId, [
           'command' => 'php artisan optimize:clear',
       ]);
   }
   

3. Service Providers: Bind the SDK as a singleton:

   $this->app->singleton(Forge::class, function ($app) {
       return new Forge(config('forge.token'));
   });
   

4. Error Handling: Wrap SDK calls in try-catch blocks:

   try {
       $forge->createSite($serverId, $params);
   } catch (TimeoutException $e) {
       Log::error("Site creation timed out: " . $e->getMessage());
       // Retry logic or notify admin
   }
   

Gotchas and Tips

Pitfalls

1. Async Operations:

   • Methods like createSite() default to waiting for completion. Set $wait = false for non-blocking calls but handle follow-ups manually.
   • Debug Tip: Use $forge->setTimeout(300) for long-running operations (e.g., large server provisioning).

2. Resource IDs:

   • Always validate IDs before use (e.g., $forge->server($id)). Invalid IDs throw NotFoundException.
   • Fix: Fetch resources first and store IDs in your database:

     $server = $forge->servers()->firstWhere('name', 'api-server');
     

3. Rate Limiting:

   • Forge’s API enforces rate limits (~60 requests/minute). Batch operations to avoid throttling.
   • Workaround: Implement exponential backoff in retries:

     $attempts = 0;
     while ($attempts < 3) {
         try {
             $forge->createDatabase($params);
             break;
         } catch (RateLimitException $e) {
             sleep(2 ** $attempts);
             $attempts++;
         }
     }
     

4. State Inconsistencies:

   • After updateSite() or createServer(), refresh the resource to sync local state:

     $site->update($params);
     $site = $forge->site($serverId, $site->id); // Refresh
     

5. SSH Key Management:

   • Deleting SSH keys via the SDK does not immediately revoke access. Manually revoke first:

     $forge->revokeAccessToServer($serverId);
     $forge->deleteSSHKey($serverId, $keyId);
     

Debugging Tips

1. Enable Debug Logging: Configure the SDK’s HTTP client to log requests:

   $forge = new Forge($token, [
       'http_client' => new \GuzzleHttp\Client([
           'debug' => fopen('forge_debug.log', 'w'),
       ]),
   ]);
   

2. Inspect Raw API Responses: Use getLastResponse() to debug failed requests:

   try {
       $forge->createSite($params);
   } catch (\Exception $e) {
       $response = $forge->getLastResponse();
       Log::error("API Response: " . $response->getBody());
   }
   

3. Common Exceptions:

   • InvalidArgumentException: Invalid parameters (e.g., unsupported PHP version).
   • ForgeException: Generic Forge API errors. Check the response body for details.
   • Fix: Validate inputs against Forge’s API docs.

Extension Points

1. Custom Resource Models: Extend SDK classes to add methods. Example:

   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. Example:

   // In your webhook handler
   $forge = new Forge($token);
   $event = $forge->events()->firstWhere('type', 'site.deployed');
   event(new SiteDeployed($event->server_id, $event->site_id));
   

3. Local Testing: Mock the SDK for unit tests:

   $forgeMock = Mockery::mock(Laravel\Forge\Forge::class);
   $forgeMock->shouldReceive('createSite')->andReturn($siteMock);
   $this->app->instance(Forge::class, $forgeMock);
   

4. Configuration Overrides: Override default SDK settings (e.g., timeout) via DI:

   $forge = new Forge($token, [
       'timeout' => 600, // 10 minutes
       'base_uri' => 'https://forge.example.com/api', // Custom Forge instance
   ]);
   

Performance Optimizations

1. Batch Fetching: Reduce API calls by fetching related resources in bulk:

   $server = $forge->server($serverId);
   $sites = $forge->sites($serverId); // Fetches all sites for this server
   

2. Caching: Cache server/site lists if they rarely change:

   $servers = Cache::remember('forge.servers', 300, function () {
       return $forge->servers();
   });
   

3. Parallel Operations: Use Laravel’s parallel helper for independent tasks:

   parallel([
       fn() => $forge->createSite($serverId, $params1),
       fn() => $forge->createDatabase($serverId, $params2),
   ]);