Weave Code
Forge Sdk Laravel Package
laravel/forge-sdk
Laravel Forge SDK for PHP. Manage Forge API v2 resources with an expressive interface: organizations, servers, sites, recipes, and more. Supports paginated results via CursorPaginator. Requires an organization slug for all endpoints.
The official Laravel Forge PHP SDK.
Frequently asked questions about Forge Sdk
- How do I install the Laravel Forge SDK in my Laravel project?
- Run `composer require laravel/forge-sdk` in your project directory. The package integrates natively with Laravel’s service container, so no additional setup is required beyond configuring your API token.
- What Laravel versions does the Forge SDK support?
- The SDK is designed for Laravel 8.x and later. It leverages Laravel’s service container, events, and exception handling, so it works best with modern Laravel applications. Check the package’s `composer.json` for exact version requirements.
- How do I handle API authentication and token management?
- Store your Forge API token securely using Laravel’s environment variables (`.env`) or a secrets manager like Laravel Vault. The SDK expects the token during initialization (`new Forge($apiToken)`). Rotate tokens via environment updates or a dedicated secrets service.
- Can I manage multiple Forge organizations with this SDK?
- Yes, fetch organizations via `$forge->organizations()` and use their `slug` to scope all API calls. You can dynamically switch contexts in your application logic, but ensure your token has access to all required organizations.
- How does the SDK handle async operations like server provisioning?
- The SDK includes built-in waiting mechanisms for async operations (e.g., `$forge->waitForServer($organizationSlug, $serverId)`). Configure timeouts via the `waitFor` method’s parameters, and dispatch long-running tasks to Laravel queues for background processing.
- What’s the best way to test my application’s Forge SDK integration?
- Mock the Forge API using Laravel’s HTTP testing helpers or a library like VCR for recording responses. Avoid hitting production/staging environments in tests; instead, use a dedicated test organization or API stubs to isolate dependencies.
- How do I handle rate limiting or API throttling in production?
- The SDK doesn’t include built-in rate limiting, but you can implement it at the application level using Laravel’s `throttle` middleware or a queue system to space out requests. Monitor Forge’s API response headers for rate limit details.
- Are there alternatives to the Forge SDK for Laravel?
- Forge’s SDK is the official choice, but you could use Laravel’s HTTP client (`Http::macro`) to interact with Forge’s API directly. However, this requires manual handling of pagination, errors, and async operations, which the SDK abstracts away.
- How do I upgrade from Forge SDK v3.x (API v1) to v4.0 (API v2)?
- Review the [upgrade guide](UPGRADE-4.0.md) for breaking changes, especially the requirement to include an organization `slug` in all endpoints. Update your code to use the new fluent methods (e.g., `$forge->servers($slug)` instead of `$forge->servers()`).
- Can I use the Forge SDK outside of Laravel (e.g., in a standalone PHP script)?
- Yes, but you’ll need to manually set up dependencies like a PSR-11 container for dependency injection and handle exceptions without Laravel’s built-in logging. The SDK is optimized for Laravel’s ecosystem, so non-Laravel use cases may require extra configuration.
Weaver
How can I help you explore Laravel packages today?