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_API_TOKEN=your_api_token_here
   

2. First Use Case: Initialize the SDK and fetch your organizations:

   $forge = new Laravel\Forge\Forge(config('forge.api_token'));
   $organizations = $forge->organizations();
   $organizationSlug = $organizations[0]->slug; // Use the first org's slug
   

3. Quick Action: List servers in your first organization:

   $servers = $forge->servers($organizationSlug);
   foreach ($servers as $server) {
       echo $server->name . "\n";
   }
   

Where to Look First

• API Reference: Start with the README.md for core methods.
• Laravel Integrations: Explore the Laravel-specific features (e.g., Horizon, Octane) if managing Laravel apps.
• Pagination: Understand CursorPaginator for handling large datasets efficiently.

Implementation Patterns

Core Workflows

Server Provisioning

1. Create a Server:

   $server = $forge->createServer($orgSlug, [
       'provider' => \Laravel\Forge\ServerProviders::DIGITAL_OCEAN,
       'credential_id' => 1,
       'name' => 'production-app',
       'type' => 'app',
       'size' => '02',
       'region' => 'nyc3',
   ]);
   

2. Wait for Provisioning (auto-waits by default):

   $server->waitForProvisioning(); // Explicit wait (optional)
   

Site Management

1. Create a Site with Auto-SSL:

   $site = $forge->createSite($orgSlug, $server->id, [
       'domain' => 'example.com',
       'type' => 'php',
       'ssl' => true,
   ]);
   

2. Update Environment Variables:

   $forge->updateSiteEnvironment($orgSlug, $server->id, $site->id, [
       'APP_ENV' => 'production',
       'DB_HOST' => 'localhost',
   ]);
   

Laravel-Specific Integrations

1. Deploy with GitHub Webhook:

   $forge->createWebhook($orgSlug, $server->id, $site->id, [
       'url' => 'https://github.com/your/repo',
       'branch' => 'main',
   ]);
   

2. Enable Horizon:

   $forge->createHorizon($orgSlug, $server->id, $site->id, [
       'queue' => 'default',
       'supervisor' => true,
   ]);
   

Integration Tips

1. Environment Configuration: Store the Forge API token in Laravel’s config/forge.php:

   return [
       'api_token' => env('FORGE_API_TOKEN'),
   ];
   

   Then inject the SDK via the service container:

   $forge = app(Laravel\Forge\Forge::class);
   

2. Artisan Commands: Create a custom command to manage Forge resources:

   use Laravel\Forge\Forge;
   
   class ForgeDeployCommand extends Command {
       protected $forge;
   
       public function __construct(Forge $forge) {
           parent::__construct();
           $this->forge = $forge;
       }
   
       public function handle() {
           $site = $this->forge->createSite(...);
           $this->info("Site deployed: {$site->domain}");
       }
   }
   

3. Event Listeners: Trigger actions after Laravel events (e.g., Deployed):

   public function handle(Deployed $event) {
       $forge = app(Forge::class);
       $forge->createPushToDeploy($orgSlug, $serverId, $siteId, [
           'branch' => $event->branch,
       ]);
   }
   

4. API Rate Limiting: Handle TooManyRequestsException by implementing retry logic:

   try {
       $forge->createSite(...);
   } catch (\Laravel\Forge\Exceptions\TooManyRequestsException $e) {
       sleep($e->retryAfter);
       retry();
   }
   

Gotchas and Tips

Pitfalls

1. Organization Slug Requirement:

   • Issue: Forgetting to include the organizationSlug in API v2 endpoints (e.g., servers()).
   • Fix: Always fetch $organizationSlug first via $forge->organizations().

2. Async Operation Timeouts:

   • Issue: Long-running operations (e.g., createSite) may exceed the default 30-second timeout.
   • Fix: Adjust timeout explicitly:

     $forge->setTimeout(120)->createSite(...); // 2-minute timeout
     

3. Pagination Handling:

   • Issue: Assuming servers() returns all results in one call.
   • Fix: Use lazy() for large datasets or toArray() to snapshot a page:

     foreach ($forge->servers($orgSlug)->lazy() as $server) { ... }
     

4. Resource Ownership:

   • Issue: Deleting a server or site without checking dependencies (e.g., databases, workers).
   • Fix: Fetch related resources first:

     $databases = $forge->databases($orgSlug, $serverId);
     if ($databases->isNotEmpty()) {
         $forge->deleteDatabase($orgSlug, $serverId, $database->id);
     }
     

5. API Token Security:

   • Issue: Hardcoding the API token in source files.
   • Fix: Use Laravel’s .env and config/forge.php:

     FORGE_API_TOKEN=your_token_here
     

Debugging Tips

1. Enable Debug Mode:

   $forge = new Forge(config('forge.api_token'), [
       'debug' => true, // Logs API requests/responses
   ]);
   

2. Check HTTP Status Codes:

   • Use try-catch to handle exceptions:

     try {
         $forge->createServer(...);
     } catch (\Laravel\Forge\Exceptions\ForgeException $e) {
         if ($e->response->status() === 400) {
             $this->error($e->response->body());
         }
     }
     

3. Inspect Raw Responses:

   • Access the underlying Guzzle client for debugging:

     $response = $forge->getClient()->get('/api/v2/organizations');
     $this->info($response->getBody());
     

Extension Points

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

   class CustomServer extends \Laravel\Forge\Resources\Server {
       public function isProduction() {
           return str_contains($this->name, 'prod');
       }
   }
   

   Override the SDK’s factory to use your class:

   $forge->setResourceFactory(function () {
       return new CustomServer();
   });
   

2. Webhook Validation: Validate Forge webhook payloads in your Laravel app:

   public function handleWebhook(Request $request) {
       $payload = $request->json()->all();
       $forge = app(Forge::class);
       $site = $forge->organizationSite($orgSlug, $payload['site_id']);
   
       if ($site->domain !== $payload['domain']) {
           abort(403, 'Invalid webhook');
       }
   }
   

3. Batch Operations: Use Laravel’s collect() to batch operations (e.g., update multiple sites):

   $sites = $forge->organizationSites($orgSlug);
   $sites->each(function ($site) {
       $forge->updateSiteEnvironment($orgSlug, $serverId, $site->id, [
           'APP_ENV' => 'production',
       ]);
   });
   

4. Testing: Mock the Forge SDK in tests:

   $forgeMock = Mockery::mock(Laravel\Forge\Forge::class);
   $forgeMock->shouldReceive('createSite')
       ->once()
       ->andReturn(new \Laravel\Forge\Resources\Site(['id' => 1, 'domain' => 'test.com']));
   $this->app->instance(Laravel\Forge\Forge::class, $forgeMock);