Laravel Forge SDK

In v4.0, mutation endpoints that return 202 Accepted with no body now return void in the SDK. Because these actions are asynchronous, you cannot rely on the return value to confirm the change. To inspect the resulting state, you must issue a follow-up GET request once the action is expected to have completed.

Affected methods include: updateSite, installPhpVersion, createRecipeRun, createBackup, createBackupConfiguration, updateBackupConfiguration, updateBackgroundProcess, updateDatabaseUser, updateComposerCredential, updateNpmCredential, and others.

// Perform the mutation
$forge->updateSite($organizationSlug, $serverId, $siteId, ['aliases' => ['foo.com']]);

// Fetch the resource to verify the change
$site = $forge->site($organizationSlug, $serverId, $siteId);

In v4.0, all list methods that previously returned arrays now return a CursorPaginator instance.

While CursorPaginator implements Countable, ArrayAccess, and IteratorAggregate (meaning foreach, count(), and $result[0] still work), it is not a plain array. Functions like array_map() or array_filter() will fail when used directly on the paginator.

To use the underlying array, call $paginator->items(). Alternatively, you can iterate over pages using $paginator->lazy() or $paginator->lazyPages().

// v3.x
$servers = $forge->servers(); // returns array

// v4.0
$servers = $forge->servers($organizationSlug); // returns CursorPaginator

// To get the array back:
$serverArray = $servers->items();

// To iterate:
foreach ($servers as $server) { ... }

Collection methods like servers(), sites(), and recipes() return a Laravel\Forge\CursorPaginator. You can interact with these results in three ways:

1. Direct Iteration: Use foreach to iterate the current page (note that this hides pagination details).
2. Lazy Iteration: Use the ->lazy() method to walk every page across the entire collection, fetching the next cursor on demand.
3. Array Snapshot: Use ->toArray() to convert the current page into a plain array.

// Iterate the current page
foreach ($forge->servers($organizationSlug) as $server) {
    echo $server->name;
}

// Lazily iterate across all pages
foreach ($forge->servers($organizationSlug)->lazy() as $server) {
    echo $server->name;
}

// Snapshot the current page as a plain array
$page = $forge->servers($organizationSlug)->toArray();

The Resource base class in v4.0 no longer uses #[\\[AllowDynamicProperties]. This means you can no longer access fields from the API response as dynamic properties if they are not explicitly declared in the class. To access undeclared fields, use the $attributes array.

// v3.x — dynamic property access worked
$server->someUndeclaredField;

// v4.0 — use the attributes array
$server->attributes['some_undeclared_field'];

To install the SDK in your project, use Composer to require the package.

composer require laravel/forge-sdk

Some methods (like createSite) wait for the action to complete on Forge by periodically checking the resource status. By default, this waits up to 30 seconds.

• Disable waiting: Pass false as the final argument to the method.
• Customize timeout: Use the setTimeout(int $seconds) method on the Forge instance before calling the action.
• Error handling: If the operation exceeds the timeout, a Laravel\Forge\Exceptions\TimeoutException is thrown.

// This will wait until the site is fully installed (max 30 seconds)
$site = $forge->createSite($organizationSlug, $serverId, [
    'domain' => 'example.com',
    'type' => 'php',
]);

// Don't wait
$site = $forge->createSite($organizationSlug, $serverId, $data, false);

// Wait up to 2 minutes
$site = $forge->setTimeout(120)->createSite($organizationSlug, $serverId, $data);

In v4.0, service actions (like restarting Nginx, MySQL, etc.) follow a unified pattern using perform[Service]Action methods.

$forge->performNginxAction($organizationSlug, $serverId, ['action' => 'restart']);
$forge->performMySQLAction($organizationSlug, $serverId, ['action' => 'restart']);
$forge->performPostgresAction($organizationSlug, $serverId, ['action' => 'restart']);
$forge->performRedisAction($organizationSlug, $serverId, ['action' => 'restart']);
$forge->performPHPAction($organizationSlug, $serverId, ['action' => 'restart']);
$forge->performSupervisorAction($organizationSlug, $serverId, ['action' => 'restart']);

When upgrading from version 2.x to 3.0, you must perform the following steps to ensure compatibility:

1. Update Package Name: Change the dependency in your composer.json from the old package name to laravel/forge-sdk.
2. Update Namespaces: Replace all instances of the ThemSaid\ namespace with Laravel\.
3. Verify PHP Version: Ensure your environment is running at least PHP 7.2.
4. Refactor Method Calls: Update deprecated or removed methods as specified in the breaking changes section.