Versions

$envless->versions->rollback()

Restore an environment to a snapshot

php
/** @return RolledBackVersionResource */
public function rollback(string $id, int|float|null $timeout = null): array

Restores an environment to a snapshot in one transaction, behind the same per environment advisory lock that $envless->variables->apply() takes. The environment is derived from the version, which is why there is no project or environment argument here.

It rewrites the live environment, it does not create a new version. Variables in the snapshot but missing live are re-created, variables in both are overwritten whenever value, type, visibility, required or defaultValue differs, and live variables absent from the snapshot are soft-deleted. Ids are not preserved, so a re-created variable comes back with a new id and any cache of variable ids has to be rebuilt afterwards.

Rollback does not snapshot the current state first, so call $envless->versions->create() before it if you might want to come back. The restored ciphertext is copied verbatim too: if the workspace passphrase was rotated without re-encrypting version entries, this call succeeds and writes values that no longer decrypt, with no warning.

Example

php
use Envless\Envless;

$envless = new Envless();

$backup = $envless->versions->create('api', 'production', [
    'note' => 'pre rollback',
]);

$id = '0191f0c4-6d2a-7c31-9a4b-8f2e1d5c7a90';
$result = $envless->versions->rollback($id);

echo "{$backup['label']} {$result['versionLabel']}", PHP_EOL;
echo "{$result['added']} {$result['updated']} {$result['removed']}", PHP_EOL;

Parameters

ParameterTypeRequiredDescription
$idstringYesVersion uniqueId to restore, which must belong to the workspace behind the key.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. Overrides the client's timeout for this call, and 0 turns the limit off.

Returns

RolledBackVersionResource with the restored versionLabel plus added, updated and removed counts.

Worth knowing

  • Requires both versions:write and variables:write.
  • Rollback needs Dev or above. On the Free plan, which keeps only the latest published version, every call fails with status 402 and code plan.upgrade_required (error.resource version). Nothing is deleted on a downgrade, so the same id restores once the plan is back.
  • The three counts describe what changed live, not the size of the snapshot. All zero means the environment already matched the version.
  • The restored variables are new rows, so re-read the environment before trusting any variable id you held before the call.

Required scopes

versions:write and variables:write

Underlying endpoint

POST /versions/{id}/rollback

Request and response schema, every error code, and a live playground.

In TypeScript

envless.versions.rollback()

The same method in @goenvless/sdk, with the same request, retries and errors.