Variables

$envless->variables->update()

Patch one variable by name

php
/**
 * @param VariablePatch $patch
 * @return VariableResource
 */
public function update(
    string $project,
    string $environment,
    string $name,
    array $patch,
    ?string $product = null,
    int|float|null $timeout = null,
): array

Patches one variable addressed by its current name. Every field is optional and anything you omit keeps its stored value.

value and defaultValue must be ciphertext when present, otherwise the call fails with 400 variable.ciphertext_invalid and error.field naming which one. Send 'defaultValue' => null to clear it and omit it to leave it alone, the two are not interchangeable.

Passing name renames the variable, which changes the address every later call must use. The new name must match ^[A-Za-z_][A-Za-z0-9_]*$ and be 1 to 100 characters, is stored with exactly the casing you send, and the rename is refused with 409 variable.name_conflict when another live variable already holds that name, compared without regard to case. Prefer updateById inside a long running sync loop, since an id cannot go stale under a rename.

Example

php
use Envless\Envless;

$envless = new Envless();

$passphrase = (string) getenv('ENVLESS_PASSPHRASE');
$workspaceId = $envless->me->get()['workspaceId'];
$ciphertext = Envless::encryptValue(
    'sk_live_rotated',
    $passphrase,
    $workspaceId,
);

$variable = $envless->variables->update(
    'api',
    'production',
    'STRIPE_SECRET_KEY',
    ['value' => $ciphertext],
);

echo $variable['updatedAt'], PHP_EOL;

Parameters

ParameterTypeRequiredDescription
$projectstringYesProject slug the environment belongs to.
$environmentstringYesEnvironment slug the variable lives in.
$namestringYesCurrent variable name, matched without regard to case.
$patchVariablePatchYesThe fields below, as one array.
$patch['name']stringNoNew name, matching ^[A-Za-z_][A-Za-z0-9_]*$ and 1 to 100 characters, which renames the variable and changes how you address it.
$patch['value']stringNoReplacement ciphertext from Envless::encryptValue(), prefixed v1: or v2:.
$patch['type']stringNoOne of the Envless\Constants\VariableType values.
$patch['isSecret']boolNoMarks or unmarks the variable as a secret, which the example feed reports as secret. Stored, but not echoed in the response.
$patch['visibility']stringNoOne of the Envless\Constants\VariableVisibilityLevels values.
$patch['required']boolNoToggles whether the variable is required for the environment.
$patch['defaultValue']string|nullNoReplacement ciphertext fallback, or null to clear it.
$productstringNoProduct slug, needed when the project slug is not unique in the workspace.
$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

VariableResource reflecting the row after the patch, with a fresh updatedAt.

Worth knowing

  • A rename does not start a new audit trail. History is keyed to the variable id, so events survive the new name.
  • The returned updatedAt is the value a later apply baseline must carry, down to the millisecond.
  • A rename is checked locally before anything is sent. The new name must be 1 to 100 characters of letters, numbers and underscores, and it must not start with a number. Case is kept exactly as you type it, and a local refusal throws Envless\Exception\ApiException carrying request.body_invalid.

Required scopes

variables:write

Underlying endpoint

PATCH /projects/{slug}/environments/{environmentSlug}/variables/{name}

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

In TypeScript

envless.variables.update()

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