php

/**
 * @param VersionCreate $body
 * @return VersionResource
 */
public function create(
    string $project,
    string $environment,
    array $body = [],
    ?string $product = null,
    int|float|null $timeout = null,
): array

Snapshots every live variable in the environment as it stands right now into a new immutable version, and emails the active members of the workspace apart from the publisher. This is the programmatic equivalent of publishing a version in the dashboard.

The ciphertext is copied verbatim. The server cannot decrypt or re-encrypt it, so the workspace key in force at this moment is the key needed to read the snapshot back later. That is exactly why rotating a passphrase has to rewrite version entries as well as live variables.

Take a version before any risky bulk change, and take one before a rollback, because $envless->versions->rollback() does not snapshot the current state for you. The body is optional and a missing or unparseable body is read as no note rather than an error.

Example

php

use Envless\Envless;

$envless = new Envless();

$version = $envless->versions->create('api', 'production', [
    'note' => 'before billing migration',
]);

echo "{$version['id']} {$version['label']}", PHP_EOL;
echo $version['variableCount'], PHP_EOL;

Parameters

Parameter	Type	Required	Description
`$project`	`string`	Yes	Project slug or project uniqueId.
`$environment`	`string`	Yes	Environment slug to snapshot.
`$body`	`VersionCreate`	No	The fields below, as one array.
`$body['note']`	`string`	No	Free text label for why the snapshot was taken, up to 200 characters.
`$product`	`string`	No	Product slug used to disambiguate a project slug shared across products.
`$timeout`	`int\|float`	No	Seconds 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

VersionResource for the new snapshot, carrying the server assigned label and the variableCount captured.

Worth knowing

label is assigned server side. Passing one has no effect.
A note over 200 characters and an environment already holding 1000 versions both fail with status 400 and the generic request.invalid code, so read message to tell them apart.
Publishing is on every plan, Free included. What Free lacks is the history: only the latest version can be read back or restored there, so a snapshot taken as a safety net before a bulk change is only usable as one from Dev upward.
A version is immutable and the SDK exposes no update or delete for one. The only way forward is another snapshot.

Required scopes

versions:write

Underlying endpoint

POST /projects/{slug}/environments/{environmentSlug}/versions

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

In TypeScript

envless.versions.create()

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

Example#

Parameters#

Returns#

Worth knowing#

Required scopes#

Underlying endpoint#