laravel / forge-sdk

The official Laravel Forge PHP SDK.

Laravel Forge SDK

Introduction

The Laravel Forge SDK provides an expressive interface for interacting with Forge's API and managing Laravel Forge servers.

Official Documentation

Installation

To install the SDK in your project you need to require the package via composer:

composer require laravel/forge-sdk

Upgrading

When upgrading to a new major version of Forge SDK, it's important that you carefully review the upgrade guide.

Basic Usage

You can create an instance of the SDK like so:

$forge = new Laravel\Forge\Forge(TOKEN_HERE);

Using the Forge instance you may perform multiple actions as well as retrieve the different resources Forge's API provides:

$servers = $forge->servers();

This will give you an array of servers that you have access to, where each server is represented by an instance of Laravel\Forge\Resources\Server, this instance has multiple public properties like $name, $id, $size, $region, and others.

You may also retrieve a single server using:

$server = $forge->server(SERVER_ID_HERE);

On multiple actions supported by this SDK you may need to pass some parameters, for example when creating a new server:

$server = $forge->createServer([
    "provider"=> ServerProviders::DIGITAL_OCEAN,
    "credential_id"=> 1,
    "name"=> "test-via-api",
    "type"=> ServerTypes::APP,
    "size"=> "01",
    "database"=> "test123",
    "database_type" => InstallableServices::POSTGRES,
    "php_version"=> InstallableServices::PHP_71,
    "region"=> "ams2"
]);

These parameters will be used in the POST request sent to Forge servers, you can find more information about the parameters needed for each action on Forge's official API documentation.

Notice that this request for example will only start the server creation process, your server might need a few minutes before it completes provisioning, you'll need to check the server's $isReady property to know if it's ready or not yet.

Some SDK methods however wait for the action to complete on Forge's end, we do this by periodically contacting Forge servers and checking if our action has completed, for example:

$forge->createSite(SERVER_ID, [SITE_PARAMETERS]);

This method will ping Forge servers every 5 seconds and see if the newly created Site's status is installed and only return when it's so, in case the waiting exceeded 30 seconds a Laravel\Forge\Exceptions\TimeoutException will be thrown.

You can easily stop this behaviour by setting the $wait argument to false:

$forge->createSite(SERVER_ID, [SITE_PARAMETERS], false);

You can also set the desired timeout value:

$forge->setTimeout(120)->createSite(SERVER_ID, [SITE_PARAMETERS]);

Authenticated User

$forge->user();

Managing Servers

$forge->servers();
$forge->server($serverId);
$forge->createServer(array $data);
$forge->updateServer($serverId, array $data);
$forge->deleteServer($serverId);
$forge->rebootServer($serverId);

// Server access
$forge->revokeAccessToServer($serverId);
$forge->reconnectToServer($serverId);
$forge->reactivateToServer($serverId);

On a Server instance you may also call:

$server->update(array $data);
$server->delete();
$server->reboot();
$server->revokeAccess();
$server->reconnect();
$server->reactivate();
$server->rebootMysql();
$server->stopMysql();
$server->rebootPostgres();
$server->stopPostgres();
$server->rebootNginx();
$server->stopNginx();
$server->installBlackfire(array $data);
$server->removeBlackfire();
$server->installPapertrail(array $data);
$server->removePapertrail();
$server->enableOPCache();
$server->disableOPCache();
$server->phpVersions();
$server->installPHP($version);
$server->updatePHP($version);

Server SSH Keys

$forge->keys($serverId);
$forge->sshKey($serverId, $keyId);
$forge->createSSHKey($serverId, array $data, $wait = true);
$forge->deleteSSHKey($serverId, $keyId);

On a SSHKey instance you may also call:

$sshKey->delete();

Server Scheduled Jobs

$forge->jobs($serverId);
$forge->job($serverId, $jobId);
$forge->createJob($serverId, array $data, $wait = true);
$forge->deleteJob($serverId, $jobId);

On a Job instance you may also call:

$job->delete();

Server Events

$forge->events();
$forge->events($serverId);

Managing Services

// MySQL
$forge->rebootMysql($serverId);
$forge->stopMysql($serverId);

// Postgres
$forge->rebootPostgres($serverId);
$forge->stopPostgres($serverId);

// Nginx
$forge->rebootNginx($serverId);
$forge->stopNginx($serverId);
$forge->siteNginxFile($serverId, $siteId);
$forge->updateSiteNginxFile($serverId, $siteId, $content);

// Blackfire
$forge->installBlackfire($serverId, array $data);
$forge->removeBlackfire($serverId);

// Papertrail
$forge->installPapertrail($serverId, array $data);
$forge->removePapertrail($serverId);

// OPCache
$forge->enableOPCache($serverId);
$forge->disableOPCache($serverId);

Server Daemons

$forge->daemons($serverId);
$forge->daemon($serverId, $daemonId);
$forge->createDaemon($serverId, array $data, $wait = true);
$forge->restartDaemon($serverId, $daemonId, $wait = true);
$forge->deleteDaemon($serverId, $daemonId);

On a Daemon instance you may also call:

$daemon->restart($wait = true);
$daemon->delete();

Server Firewall Rules

$forge->firewallRules($serverId);
$forge->firewallRule($serverId, $ruleId);
$forge->createFirewallRule($serverId, array $data, $wait = true);
$forge->deleteFirewallRule($serverId, $ruleId);

On a FirewallRule instance you may also call:

$rule->delete();

Managing Sites

$forge->sites($serverId);
$forge->site($serverId, $siteId);
$forge->createSite($serverId, array $data, $wait = true);
$forge->updateSite($serverId, $siteId, array $data);
$forge->refreshSiteToken($serverId, $siteId);
$forge->deleteSite($serverId, $siteId);

// Add Site Aliases
$forge->addSiteAliases($serverId, $siteId, array $aliases);

// Environment File
$forge->siteEnvironmentFile($serverId, $siteId);
$forge->updateSiteEnvironmentFile($serverId, $siteId, $content);

// Site Repositories and Deployments
$forge->installGitRepositoryOnSite($serverId, $siteId, array $data, $wait = false);
$forge->updateSiteGitRepository($serverId, $siteId, array $data);
$forge->destroySiteGitRepository($serverId, $siteId, $wait = false);
$forge->siteDeploymentScript($serverId, $siteId);
$forge->updateSiteDeploymentScript($serverId, $siteId, $content);
$forge->enableQuickDeploy($serverId, $siteId);
$forge->disableQuickDeploy($serverId, $siteId);
$forge->deploySite($serverId, $siteId, $wait = false);
$forge->resetDeploymentState($serverId, $siteId);
$forge->siteDeploymentLog($serverId, $siteId);
$forge->deploymentHistory($serverId, $siteId);
$forge->deploymentHistoryDeployment($serverId, $siteId, $deploymentId);
$forge->deploymentHistoryOutput($serverId, $siteId, $deploymentId);

// PHP Version
$forge->changeSitePHPVersion($serverId, $siteId, $version);

// Installing Wordpress
$forge->installWordPress($serverId, $siteId, array $data);
$forge->removeWordPress($serverId, $siteId);

// Installing phpMyAdmin
$forge->installPhpMyAdmin($serverId, $siteId, array $data);
$forge->removePhpMyAdmin($serverId, $siteId);

// Updating Node balancing Configuration
$forge->updateNodeBalancingConfiguration($serverId, $siteId, array $data);

On a Site instance you may also call:

$site->refreshToken();
$site->delete();
$site->installGitRepository(array $data, $wait = false);
$site->updateGitRepository(array $data);
$site->destroyGitRepository($wait = false);
$site->getDeploymentScript();
$site->updateDeploymentScript($content);
$site->enableQuickDeploy();
$site->disableQuickDeploy();
$site->deploySite($wait = false);
$site->resetDeploymentState();
$site->siteDeploymentLog();
$site->getDeploymentHistory();
$site->getDeploymentHistoryDeployment($deploymentId);
$site->getDeploymentHistoryOutput($deploymentId);
$site->installWordPress($data);
$site->removeWordPress();
$site->installPhpMyAdmin($data);
$site->removePhpMyAdmin();
$site->changePHPVersion($version);
$site->siteLog();

Site Workers

$forge->workers($serverId, $siteId);
$forge->worker($serverId, $siteId, $workerId);
$forge->createWorker($serverId, $siteId, array $data, $wait = true);
$forge->deleteWorker($serverId, $siteId, $workerId);
$forge->restartWorker($serverId, $siteId, $workerId, $wait = true);

On a Worker instance you may also call:

$worker->delete();
$worker->restart($wait = true);

Security Rules

$forge->securityRules($serverId, $siteId);
$forge->securityRule($serverId, $siteId, $ruleId);
$forge->createSecurityRule($serverId, $siteId, array $data);
$forge->deleteSecurityRule($serverId, $siteId, $ruleId);

On a SecurityRule instance you may also call:

$securityRule->delete();

Site Webhooks

$forge->webhooks($serverId, $siteId);
$forge->webhook($serverId, $siteId, $webhookId);
$forge->createWebhook($serverId, $siteId, array $data);
$forge->deleteWebhook($serverId, $siteId, $webhookId);

On a Webhook instance you may also call:

$webhook->delete();

Site Commands

$forge->executeSiteCommand($serverId, $siteId, array $data);
$forge->listCommandHistory($serverId, $siteId);
$forge->getSiteCommand($serverId, $siteId, $commandId);

Site SSL Certificates

$forge->certificates($serverId, $siteId);
$forge->certificate($serverId, $siteId, $certificateId);
$forge->createCertificate($serverId, $siteId, array $data, $wait = true);
$forge->deleteCertificate($serverId, $siteId, $certificateId);
$forge->getCertificateSigningRequest($serverId, $siteId, $certificateId);
$forge->installCertificate($serverId, $siteId, $certificateId, array $data, $wait = true);
$forge->activateCertificate($serverId, $siteId, $certificateId, $wait = true);
$forge->obtainLetsEncryptCertificate($serverId, $siteId, $data, $wait = true);

On a Certificate instance you may also call:

$certificate->delete();
$certificate->getSigningRequest();
$certificate->install($wait = true);
$certificate->activate($wait = true);

Nginx Templates

$forge->nginxTemplates($serverId);
$forge->nginxDefaultTemplate($serverId);
$forge->nginxTemplate($serverId, $templateId);
$forge->createNginxTemplate($serverId, array $data);
$forge->updateNginxTemplate($serverId, $templateId, array $data);
$forge->deleteNginxTemplate($serverId, $templateId);

On a NginxTemplate instance you may also call:

$nginxTemplate->update(array $data);
$nginxTemplate->delete();

Managing Databases

$forge->databases($serverId);
$forge->database($serverId, $databaseId);
$forge->createDatabase($serverId, array $data, $wait = true);
$forge->updateDatabase($serverId, $databaseId, array $data);
$forge->deleteDatabase($serverId, $databaseId);
$forge->syncDatabases($serverId);

// Users
$forge->databaseUsers($serverId);
$forge->databaseUser($serverId, $userId);
$forge->createDatabaseUser($serverId, array $data, $wait = true);
$forge->updateDatabaseUser($serverId, $userId, array $data);
$forge->deleteDatabaseUser($serverId, $userId);

On a Database instance you may also call:

$database->update(array $data);
$database->delete();

On a DatabaseUser instance you may also call:

$databaseUser->update(array $data);
$databaseUser->delete();

Managing Recipes

$forge->recipes();
$forge->recipe($recipeId);
$forge->createRecipe(array $data);
$forge->updateRecipe($recipeId, array $data);
$forge->deleteRecipe($recipeId);
$forge->runRecipe($recipeId, array $data);

On a Recipe instance you may also call:

$recipe->update(array $data);
$recipe->delete();
$recipe->run(array $data);

Managing Backups

$forge->backupConfigurations($serverId);
$forge->createBackupConfiguration($serverId, array $data);
$forge->updateBackupConfiguration($serverId, $backupConfigurationId, array $data);
$forge->backupConfiguration($serverId, $backupConfigurationId);
$forge->deleteBackupConfiguration($serverId, $backupConfigurationId);
$forge->restoreBackup($serverId, $backupConfigurationId, $backupId);
$forge->deleteBackup($serverId, $backupConfigurationId, $backupId);

On a BackupConfiguration instance you may also call:

$extendedConfig = $backupConfig->get(); // Load the databases also
$backupConfig->update(array $data);
$backupConfig->delete();
$backupConfig->restoreBackup($backupId);
$backupConfig->deleteBackup($backupId);

On a Backup instance you may also call:

$backupConfig->delete();
$backupConfig->restore();

Managing Redirects

$forge->redirectRules($serverId, $siteId);
$forge->redirectRule($serverId, $siteId, $ruleId);
$forge->createRedirectRule($serverId, $siteId, array $data, $wait = true);
$forge->deleteRedirectRule($serverId, $siteId, $ruleId);

On a RedirectRule instance you may also call:

$redirectRule->delete();

Contributing

Thank you for considering contributing to Forge SDK! You can read the contribution guide here.

Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the Code of Conduct.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

Laravel Forge SDK is open-sourced software licensed under the MIT license.

forge-sdk's Issues

SSL certificate problem

Heya 🙂

I know the lib is still in beta / not even 1.0.0, but I figured I'd give it a shot and I'm immediately encountering the infamous Guzzle error:

[GuzzleHttp\Exception\RequestException]
  cURL error 60: SSL certificate problem: unable to get local issuer certificate (see http://curl.haxx.se/libcu
  rl/c/libcurl-errors.html)

Can this be resolved in the scope of this package or should something be done on my end to make it work?

Thanks!

Clear site aliases

• Forge SDK Version: 3.8.0
• Laravel Version: 8.47.0
• PHP Version: 8.0
• Database Driver & Version: MySQL 8.0

Description:

When a site has only one alias and update that site with empty aliases array that last alias is not removed.

Steps To Reproduce:

• Create a site.
• Add one alias.
• Update site with empty aliases array.

Support for new feature commands

Server ubuntuVersion property does not return a version below 20.04

• Forge SDK Version: 3.13.3
• Laravel Version: 10.3.3
• PHP Version: 8.2
• Database Driver & Version: N/A

Description:

Retrieving the Ubuntu version from the server using the undeclared ubuntuVersion property does not return a version below 20.04. We have many servers and are developing a tool to tell us which ones are EOL to streamline the migration process.

This may have more to do with the Forge platform itself than the SDK, but I believe if this could be fixed in Forge's core it could make a great addition to the Forge SDK.

[SUGGESTION] CLI options

Would be nice to have command line calls so we could include some forge-commands in an automated docker/ci setup for example.

There are a couple of options available like: https://github.com/svenluijten/forge-cli
But I think this is useful enough to be included in the API.

API Request works perfect from Localhost, but not from Forge

• Forge SDK Version: 3.8.0
• Laravel Version: 8.53.0
• PHP Version: 8.0
• Database Driver & Version:mysql

I send a api request from localhost to forge. It works create, your package create the site, ssl, gitrepo..All works!!
But this works only on localhost. If i make this from a real site on forge, i get only 1 error:
"502 Bad Gateway Nginx". This error is not a part from the api documentation. I dont know, why it works from localhost, but not from forge :(

Thanks for help :)

Steps To Reproduce:

Undefined array key "provision_command"

• Forge SDK Version: 3.13
• Laravel Version: 9.19
• PHP Version: 8.1.9

Description:

PHP Warning: Undefined array key "provision_command" in /Users/richardhedges/Sites/hubv2/vendor/laravel/forge-sdk/src/Actions/ManagesServers.php on line 49

Steps To Reproduce:

Run the createServer method, as in the example in the docs.

Add Webhook Management

Add webhook management to the package.

Update FPM Pool configuration

The FPM Pool can be updated from the forge web interface, and this option must be available in the SDK.

Optional $apiKey constructor for main Forge class

The $apiKey in the Forge class constructor should be optional along with having a setApiKey method.

I am working with multiple Forge tokens, so I need to be able to change the api key dynamically.

Let me know if you'll accept a PR for this.

How to get list of Forge Webhooks

There are options in the forge API to make a get request and get a list of webhooks on a website, but its not in your SDK, is there a particular reason for this? Would be useful if it were implemented for sure

https://forge.laravel.com/api-documentation#webhooks

Blackfire inconsistencies

I noticed there's no way to remove Blackfire from the server as it stands, but the API documentation does mention it.

When I wanted to add the function and send in a PR (#4), I noticed some little inconsistencies in the Forge docs or this package. The installBlackfire() method makes a POST request to /servers/$serverId/blackfire/install, while the docs say that you have to post to blackfire/install and pass the server ID in the request payload.

Expose API endpoints for managing PHP versions

The following API endpoints seem to require a valid CSRF token:

• PUT /servers/{id}/php/cli
• PUT /servers/{id}/php/default
• DELETE /servers/{id}/php

Could they be made available for programmatic use, i.e. without CSRF tokens?

ErrorException : Illegal string offset 'site'

ErrorException  : Illegal string offset 'site'

  at /Users/christiangiupponi/Dev/Projects/ZerounoToolbox/vendor/themsaid/forge-sdk/src/Actions/ManagesSites.php:48
    44|      * @return Site
    45|      */
    46|     public function createSite($serverId, array $data, $wait = true)
    47|     {
  > 48|         $site = $this->post("servers/$serverId/sites", $data)['site'];
    49| 
    50|         if ($wait) {
    51|             return $this->retry($this->getTimeout(), function () use ($serverId, $site) {
    52|                 $site = $this->site($serverId, $site['id']);
  Exception trace:

  1   Illuminate\Foundation\Bootstrap\HandleExceptions::handleError("Illegal string offset 'site'", "/Users/christiangiupponi/Dev/Projects/ZerounoToolbox/vendor/themsaid/forge-sdk/src/Actions/ManagesSites.ph
p", [])
      /Users/christiangiupponi/Dev/Projects/ZerounoToolbox/vendor/themsaid/forge-sdk/src/Actions/ManagesSites.php:48

  2   Themsaid\Forge\Forge::createSite(["prova-completa.example.com", "/public", "php"])
      /Users/christiangiupponi/Dev/Projects/ZerounoToolbox/app/Commands/SetUpStaging.php:203

  Please use the argument -v to see more details.

Some functions use a hard coded timeout of 30

Forge SDK Version

3.13.3

Laravel Version

9.52.4

PHP Version

8.1.17

Database Driver & Version

No response

Description

Activating a new certificate on a Forge server could take longer than the default timeout of 30 seconds which leads to a timeout error. To avoid this i have increased the timeout by using the Forge::setTimeout() function. However, when calling the ManagesCertificates::activateCertificate() function the timeout still occurs after 30 seconds. Looking into its code shows, that a timeout of 30 is passed to the retry() function as hard coded value. This applies to ManagesCertificates::installCertificate(), ManagesDaemons::restartDaemon() and ManagesWorkers::restartWorker() as well. All other calls to retry() use $this->getTimeout() to determine the timeout which is the expected bahaviour.

Steps To Reproduce

1. Create a new certificate with obtainLetsEncryptCertificate()
2. Increase timeout to e.g. 2 minutes using setTimeout(300)
3. Activate the new certificate with activateCertificate()
4. Wait for timeout error after 30 seconds

Cant set notifications for site deployments

• Forge SDK Version: 3.3.1
• Laravel Version: 8.5.9
• PHP Version: 7.4

Description:

Can't add use enableHipchatNotifications method and no methods/properties for other webhooks like Discord and Teams.
When using the HipChat method there is a The resource you are looking for could not be found. response.

Steps To Reproduce:

(new Forge('apiKey'))->enableHipchatNotifications('serverId', 'siteId', ["webhook_url": "webhook.com"])

I might be setting the data incorrectly but there is also no explination on usage.

Update createSite return

I'll check this out and see if a PR is needed, but at first look it feel like the return inside the $wait conditional needs to be a Site object and not just return $site

   public function createSite($serverId, array $data, $wait = true)
    {
        $site = $this->post("servers/$serverId/sites", $data)['site'];
        if ($wait) {
            return $this->retry($this->getTimeout(), function () use ($serverId, $site) {
                $site = $this->site($serverId, $site['id']);
                return $site->status == 'installed' ? $site : null;
            });
        }
        return new Site($site + ['server_id' => $serverId], $this);
    }

Managing Create Database User

• Forge SDK Version: 3.13.1
• Laravel Version: ^8.83
• PHP Version: v8.0.16
• Database Driver & Version: mysql Ver 8.0.23 for Linux on x86_64 (MySQL Community Server - GPL)

Description:

i try to use this sdk and passing data like in documentation but i got validation errors

( new Forge(token was passing))->createDatabaseUser(123,  ['name' => 'name', 'password' => 'password, "databases" =>[123]])

errors

production.ERROR: The given data failed to pass validation. {"exception":"[object] (Laravel\\Forge\\Exceptions\\ValidationException(code: 0): The given data failed to pass validation. at /vendor/laravel/forge-sdk/src/MakesHttpRequests.php:104)

in docs like this

[⊖](https://forge.laravel.com/api-documentation#){
    "name": "forge",
    "password": "dolores",
    "databases": [⊖](https://forge.laravel.com/api-documentation#)[
        1
    ]
}

i really appreciate your help thanks

Undefined index: provision_command

 Undefined index: provision_command in /Actions/ManagesServers.php on line 45

I'm getting this error with createServer()

https://github.com/themsaid/forge-sdk/blob/2.0/src/Actions/ManagesServers.php#L38

rate limiting (too many attempts)

I've written a script that basically exports everything from the forge api and stores it in a local database and with 10 servers and 160 sites I am running into the 429 Too Many Attempts error.

However in the api docs I am unable to see anything about a rate limit, and also I don't have experience with setting a rate limit locally so I don't hammer the api.

Any chance you could introduce this? Or at least provide some directions on how I could easily achieve this (the proper way) so I can run my "populate" script in the future and not fear of running into the "Too many attempts" limit?

Many thanks

Call to a member function request() on null

• Forge SDK Version: #.#.#
• Laravel Version: 9.21.3
• PHP Version: 8.1.5
• Database Driver & Version: Server version: 10.5.9-MariaDB Homebrew

Description:

When trying to find a server (or anything else) i've this error (on my local):

Steps To Reproduce:

Don't know, i can't reproduce it in production.

Do you have any idea to solve this ?

Thanks for your help !

restart php

Hello,
Is there a reason why it is not possible to restart the php-fpm service from this sdk?

Backup Configurations Update

According to docs there's no way to update the databases selected in an existing Backup Configuration? There's an option in the web gui to do this, at least with Provider set as Custom (S3 Compatible). You can edit and include additional databases.

This would be great to have for automated provisioning scripts.

CreateSite api isolation=true goes on 502 error

• Forge SDK Version: "laravel/forge-sdk": "^3.9"
• Laravel Version: "laravel/framework": "^8.0",
• PHP Version: 7.4
• Database Driver & Version:N.A

Description:

Using CreateSite method and isolation = true
website goes on 502 error.

Steps To Reproduce:

Create Site

$siteParams = [
"domain" => $siteSlug .".socialdrinks.it",
"project_type" => "php",
"directory" => "/public",
"isolated" => true,
"php_version" => "php74"
];

$forge = new Laravel\Forge\Forge($token,$guzzleClient);
$forge->createSite($serverId, $siteParams,false);

Site is created but the website response is 502 bad gateway.

regards.
.g

\Themsaid\Forge\Forge class not found, on production

Unable to create the database on a live server.

`namespace App\Jobs;
use Themsaid\Forge\Forge;

        $forge = new \Themsaid\Forge\Forge(config('app.forge_access_token'));
        $databaseCreated = $forge->createMysqlDatabase(
            config('app.forge_server_id'), array('name' => 'test_1234'), $wait = true
        );

Error: Class 'Themsaid\Forge\Forge' not found in /home/forge/website.com/app/Jobs/CreateDatabase.php:47`

The given data failed to pass validation.

I keep getting this error when attempting to create a new server on forge using the code below

The given data failed to pass validation.

$this->forge->createServer([
    'provider' => 'aws',
    'credential_id' => 1,
    'name' => 'fancy-mist',
    'size' => '1GB',
    'php_version' => 'php72',
    'region' => 'London',
]);

I can use the following code on the same setup successfully and I don't get this error.

$this->forge->servers();

Not sure why this is happening, if there is any more info you need please ask and i'll provide it.

shouldn't $forge->runRecipe($recipeId); include a way to pass server ids?

Just wondering how you can run a recipe on a specific server or set of servers

in the api docs the payload is described as

⊖{
    "servers": ⊖[
        1,
        2
    ]
}

but according to your docs the runRecipe() only accepts a recipeId?

Having issue running some methods on forge API

Hi,
I managed to run following methods:

$forge->createSite($server_id,$site_data, true);
$forge->installGitRepositoryOnSite($server_id, $site_id, $repository_data);
$forge->updateSiteDeploymentScript($server_id, $site_id, $content);

But following commands doesn't take any effects. Is there any specific needs to run the following commands:

$forge->updateSiteEnvironmentFile($server_id, $site_id, $content);
$forge->deploySite($server_id,$site_id);

Installing certificates inconsistent with API docs

Installing an SSL certificate accepts a payload (as documented here), but the SDK doesn't seem to do so. I'm unsure whether or not this is an issue with Forge's documentation or an issue on this SDK, I'll let you decide that 😉

Thanks in advance.

create site then update site configurations - 502 error

Hello,

When I make a new site and in the same request edit the new site nginx file I get 502 error :(

I hope you can help me with that

Thanks

Error using createBackupConfiguration

I'm using the SDK to create a database backup configuration, and it returns no data because of an error. However, the configuration backup is created on Forge Panel.

[2020-06-19 17:59:28] local.ERROR: array_map(): Expected parameter 2 to be an array, null given {"exception":"[object] (ErrorException(code: 0): array_map(): Expected parameter 2 to be an array, null given at /Sites/vendor/themsaid/forge-sdk/src/Resources/Resource.php:80)
[stacktrace]
#0 [internal function]: Illuminate\\Foundation\\Bootstrap\\HandleExceptions->handleError(2, 'array_map(): Ex...', '/Sites...', 80, Array)
#1 /Sites/vendor/themsaid/forge-sdk/src/Resources/Resource.php(80): array_map(Object(Closure), NULL)
#2 /Sites/vendor/themsaid/forge-sdk/src/Resources/BackupConfiguration.php(92): Themsaid\\Forge\\Resources\\Resource->transformCollection(NULL, 'Themsaid\\\\Forge\\\\...', Array)
#3 /Sites/vendor/themsaid/forge-sdk/src/Actions/ManagesBackups.php(51): Themsaid\\Forge\\Resources\\BackupConfiguration->__construct(Array, Object(Themsaid\\Forge\\Forge))
#4 /Sites/app/Jobs/Master/Domains/Database/SetupForgeBackup.php(91): Themsaid\\Forge\\Forge->createBackupConfiguration('(reserved)', Array)
#5 [internal function]: App\\Jobs\\Master\\Domains\\Database\\SetupForgeBackup->handle()

Any idea?

Add site to load balancer failing

• Forge SDK Version: 3.1.0
• Laravel Version: 8.3
• PHP Version: 7.4
• Database Driver & Version:

Description:

Updated to 3.1.0 and am now receiving "The given data failed to pass validation." when using updateNodeBalancingConfiguration()

Was working previously under version 2.2

Steps To Reproduce:

$server_data = [
		    'servers' => [
			    'id' => $server_id
		    ],
		    'method' => 'least_conn'
	    ];

	    $forge->updateNodeBalancingConfiguration(config('settings.forge_lb_id'), $site_id, $server_data);

Specify collation on database creation

Hi,
in docs I can't found a way to create a database using api with specific collation.
There is a way to do this ?
if not maybe can be improved.
regards.

Deployment output call returns the same log for every deployment on a server/site

• Forge SDK Version: 3.13.3
• Laravel Version: does not apply
• PHP Version: 8.2
• Database Driver & Version: does not apply

Description:

When requesting the log for a deployment (giving server id, site id and deployment id). I always get the same deployment log.

I see that you are calling the right api endpoint for this, but i guess it might be more of an issue with Forge itself. The Forge UI works great but the same info using the API is wrong, all the time.

Steps To Reproduce:

Request 2 different logs of 2 different deployments.

The server provider was unable to create your server (Digital Ocean provider.)

The server provider was unable to create your server

When creating a new server on Digital Ocean.

Seems like Forge overrides environment configuration after site has been installed

• Forge SDK Version: 3.3.0
• Laravel Version: 8.14.0
• PHP Version: 8.0.1
• Database Driver & Version: mysql Ver 8.0.21 for macos10.15 on x86_64

Description:

I’m automatically creating a site (createSite()), installing git (installGitRepository()), creating a database (createDatabase()) and setting all the environment variables (updateSiteEnvironmentFile()). I perform the API requests in this order as well, but I check if the site status, git status and database status is correct before going to the next step. When coming to the last step I retrieve the default content of the environment file using siteEnvironmentFile(). Then, I change the variables which need to change. At last, I update the env file using updateSiteEnvironmentFile().

Now if I go to the site on Forge and check the Environment tab, I see the original/default content of the env file. It seems/feels like Forge updates the env file one more time with the default content right after everything is installed. A few things which come to mind: maybe I’m updating the .env file too fast or maybe the .env file is not created yet? But this is a wild guess. If I execute the exact same code after (let’s say) 30 seconds, it does work. That’s why I think Forge updates/overrides it.

The code for updating the env file:

protected function updateEnvFile(Site $site)
{
    $env = ForgeManager::api()->siteEnvironmentFile($site->serverId, $site->id);

    dump($env); // First line outputs: APP_NAME={{app_name}}\n

    $attributes = collect([
        'APP_NAME' => $this->catalog->id,
        'APP_ENV' => 'production',
        'APP_DEBUG' => 'true',
        'APP_URL' => "https://{$site->name}",
        'DB_DATABASE' => data_get($this->attributes, 'database.name'),
        'DB_USERNAME' => data_get($this->attributes, 'database.user'),
        'DB_PASSWORD' => data_get($this->attributes, 'database.password'),
    ]);

    foreach ($attributes as $key => $value) {
        $env = preg_replace("/^{$key}=(.*)\n/m", "$key=$value\n", $env);
    }

    ForgeManager::api()->updateSiteEnvironmentFile($site->serverId, $site->id, $env);

    dump($env); // First line outputs: APP_NAME=38\n
}

So if you check what the dump outputs on the last line, it seems like the content which is sent to the API is correct.

Steps To Reproduce:

1. Create a fresh site via the Forge API
2. Almost Immediately update the env file after the site has been installed
3. Check the env file content on Forge

retry method in MakesHttpRequests is sending boolean values to TimeoutException

• Forge SDK Version: 3.13.0
• Laravel Version: 7.30.6
• PHP Version: 7.3.33
• Database Driver & Version: MySQL 5.7

Description:

When retry method is used (Like in installCertificate, activateCertificate, etc) callback sent a boolean as result

This boolean is being sent to TimeoutException constructor (MakesHttpRequests->retry method) which causes a fatal error, becasue TimeoutException expects null or array values, not booleans.

This was reported and handled partially in #109, but not fixed for all the cases.

Steps To Reproduce:

Just replace any retry callback to return false and wait the timeout :)

installCertificate: The given data failed to pass validation.

Hi there,

I get this error when calling $forge->installCertificate

but not much information is shown about the error: The given data failed to pass validation. {"exception":"[object] (Themsaid\Forge\Exceptions\ValidationException(code: 0): The given data failed to pass validation. at /vendor/themsaid/forge-sdk/src/MakesHttpRequests.php:90)

Error doesn't specify why it failed validation.

I believe there is a similar ticket but this is for a different api method.

UPDATE1: 0 => "The certificate field is required."
But I'm definitely passing the certificate id.

UPDATE2: I might be using the sdk wrong. What I want to do is: I already have a certificate installed for my a site and want to install it for other sites. Is there a specific API workflow I should follow? The official api docs says: "certificate": "certificate content", but I have no idea what "certificate content" means or where to get it from?

installGitRepository function should have the $wait parameter

Would you accept a PR on adding this?

Right now I have to manually ensure that the $site->repositoryStatus !== 'installing'

Create custom VPS via API

Hello,

I used laravel/forge-sdk 3.3, for this pretty simple creation script:

$forge = new Laravel\Forge\Forge($API_TOKEN);

$server = $forge->createServer([
"provider"=> "custom",
"name"=> "xxx",
"ip_address"=> "x.x.x.x",
"private_ip_address"=> "x.x.x.x",
"php_version"=> "php74"
]);
?>

As Response I simply get this:

PHP Fatal error: Uncaught Laravel\Forge\Exceptions\ValidationException: The given data failed to pass validation. in /home/technik/forge-api/vendor/laravel/forge-sdk/src/MakesHttpRequests.php:98
Stack trace:
#0 /home/technik/forge-api/vendor/laravel/forge-sdk/src/MakesHttpRequests.php(76): Laravel\Forge\Forge->handleRequestError()
#1 /home/technik/forge-api/vendor/laravel/forge-sdk/src/MakesHttpRequests.php(34): Laravel\Forge\Forge->request()
#2 /home/technik/forge-api/vendor/laravel/forge-sdk/src/Actions/ManagesServers.php(44): Laravel\Forge\Forge->post()
#3 /home/technik/forge-api/create-server.php(10): Laravel\Forge\Forge->createServer()
#4 {main}
thrown in /home/technik/forge-api/vendor/laravel/forge-sdk/src/MakesHttpRequests.php on line 98

Actually I wanted to create type node_balancer, but I have no clue which fields are required and which are optional. I have only two types of devices, load balancers or web servers. Can someone give me an hint in the right direction?

Best Regards

Matthias

CacheRemember Issue

Hi,

i want to store data in cache to avoid hit everytime to the server API

    public function index(Forge $forge)
    {
        $servers = Cache::rememberForever('servers', function () use ($forge) {
            return $forge->servers();
        });
    }

I'm getting this error

Exception: Serialization of 'Closure' is not allowed

any solution you have?

regards

Reboot Server not found

I cannot seem to find a way to reboot a server using this SDK.

Http Client error in forge, not in local

• Forge SDK Version: #.#.#
• Laravel Version: 8.66.0
• PHP Version: 7.4.23
• Database Driver & Version:
• "guzzlehttp/guzzle": "^7.0.1"

Description:

Making a call to a wordpress api, I receive an error wich I didn't received in local development:
Handled error
Illuminate\Http\Client\ConnectionException: cURL error 35: error:14094458:SSL routines:ssl3_read_bytes:tlsv1 unrecognized name

It is a simple call with Http Client to an open wordpress API:
https://ilindy.com/wp-json/wp/v2/tags?per_page=100&page=1

This call is inside a Job, and I have installed Laravel Horizon.

Steps To Reproduce:

Exclude "archived" servers?

$forge->servers(); includes "archived" servers.

Perhaps that's because GET /api/v1/servers doesn't indicate whether a server is archived vs active?

Create helpers to hold available options.

It is just a personal idea (and preference) to hold all the relevant options inside classes, this gives, at least for me somehow a consistency layer on the right way of passing options as strings to the API.

Given the example on a request for creating a server:

I will like to add classes under the namespace Themsaid\Forge\Helpers to hold constants of valid options to pass to the API, as follows:

<?php

namespace Themsaid\Forge\Helpers;

class ProvisionableServers
{
    const VULTR = 'vultr'

    const DIGITAL_OCEAN = 'ocean2'
}

That way when the users are creating a request, they can Reference the helper class instead of typing the option by themselves and having the risk of making a mistake. Also this turns options into a versionable element that can reflect adittions and changes to the API signature in the future.

<?php

// Import autoload and so on ...

$server = $forge->createServer([
    "provider"=> ProvisionableServers::DIGITAL_OCEAN,
    "credential_id"=> 1,
    "name"=> "test-via-api",
    "size"=> ServerSize::512MB,
    "database"=> "test123",
    "php_version"=> InstallableServices::PHP_71,
    "region"=> AvailableRegions::DIGITAL_OCEAN_AMS2,
]);

I will be able to crate a PR and also modify the sdk docs if you think this is something you will like to have it here 😄

Start and stop commands

Is it possible to stop a server without rebooting? And starting it later using a different call? Eg. for scaling extra servers using an API?

Unsupported operand types when installing a git repo without waiting

• Forge SDK Version: 3.3.0
• Laravel Version: 8.14.0
• PHP Version: 7.4.11
• Database Driver & Version: mysql version 8.0.21

Description:

When executing the installGitRepositoryOnSite() method and setting the $wait parameter to false the following error is thrown: Unsupported operand types. Thrown in: src/Actions/ManagesSites.php line 188.

The problem is that POST /api/v1/servers/{serverId}/sites/{siteId}/git returns an empty response, causing the $site variable to be "". Then, on line 188 a new Site resource is being created using the union operator: $site + ['server_id' => $serverId]. We can't add an array to a string using the union operator. Also, should it be possible to have a site resource with only the server_id attribute?

I can make a fix, but I'm not sure what the expected behaviour should be. Make another API call to get the site resource? Something like:

$this->post("servers/$serverId/sites/$siteId/git", $data);

if ($wait) {
    return $this->retry($this->getTimeout(), function () use ($serverId, $siteId) {
        $site = $this->site($serverId, $siteId);

        return $site->repositoryStatus === 'installed' ? $site : null;
    });
}

$site = $this->get("servers/$serverId/sites/$siteId");;

return new Site($site + ['server_id' => $serverId], $this);

Steps To Reproduce:

Call the following method:

$forge->installGitRepositoryOnSite(1, 1, false);

Running code after site deployment

I have a deployment script that creates a database with a couple of tables and I was hoping I could run some php code after the deployment to populate those tables. Is there a way to sync to forge's deployment?

TimeoutException::__construct(): Argument #1 ($output) must be of type array, null given

• Forge SDK Version: 3.4.0
• Laravel Version: 8.32.1
• PHP Version: 8.0.2
• Database Driver & Version: MySQL 8.0

Description:

When running $site->deploySite() it throws this exception:

  TypeError 

  Laravel\Forge\Exceptions\TimeoutException::__construct(): Argument #1 ($output) must be of type array, null given, called in vendor/laravel/forge-sdk/src/MakesHttpRequests.php on line 138

  at vendor/laravel/forge-sdk/src/Exceptions/TimeoutException.php:22
     18▕      *
     19▕      * @param  array  $output
     20▕      * @return void
     21▕      */
  ➜  22▕     public function __construct(array $output)
     23▕     {
     24▕         parent::__construct('Script timed out while waiting for the process to complete.');
     25▕ 
     26▕         $this->output = $output;

Steps To Reproduce:

$forge = new Forge('api_key');
$server = $forge->servers()[0];
$site = $forge->sites($server->id)[0];
$site->deploySite();

PHP Reboot

Hi,

it seems that forge have updated their API with regards to restarting PHP. You now need to include the Version of PHP that you want to restart (as forge servers can now handle multiple versions of PHP on the same server).

If you do not provide the PHP version then you get a validation error when trying the API request.

Can you please update the SDK so that it supports this.

Thanks :)