Variables

$envless->variables->create()

Create one variable in an environment

php
/**
 * @param VariableInput $body
 * @return VariableResource
 */
public function create(
    string $project,
    string $environment,
    array $body,
    ?string $product = null,
    int|float|null $timeout = null,
): array

Creates a single variable in an environment and returns the stored row.

value must already be ciphertext from Envless::encryptValue(). The server holds no key and will not encrypt for you, so a plaintext value is refused with 400 variable.ciphertext_invalid and error.field naming the offender. defaultValue obeys the same rule whenever you send it, and plaintext that reaches it is permanent, since it is copied into every version snapshot taken afterwards and into every rollback made from one.

The ciphertext check runs before the project and environment are resolved, so a malformed value aimed at a project that does not exist returns 400 and not 404. A name already taken by a live variable is 409 variable.name_conflict, and hitting the 1000 variable ceiling is 409 plan.limit_reached rather than a 402.

name must match ^[A-Za-z_][A-Za-z0-9_]*$ and be 1 to 100 characters: letters, digits and underscores only, never starting with a digit. A name that fails either rule is a 400, not a silent fix. Lowercase is legal. Envless stores and returns the name with exactly the casing you send and never upper-cases it for you, but uniqueness inside the environment is judged without regard to case, so creating api_key in an environment that already holds API_KEY is 409 variable.name_conflict rather than a second variable.

Example

php
use Envless\Envless;

$envless = new Envless();

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

$variable = $envless->variables->create('api', 'production', [
    'name' => 'STRIPE_SECRET_KEY',
    'value' => $ciphertext,
    'required' => true,
]);

echo $variable['id'], PHP_EOL;

Parameters

ParameterTypeRequiredDescription
$projectstringYesProject slug the environment belongs to.
$environmentstringYesEnvironment slug to create the variable in.
$bodyVariableInputYesThe fields below, as one array.
$body['name']stringYesVariable name. Matches ^[A-Za-z_][A-Za-z0-9_]*$, 1 to 100 characters, unique among the live variables in the environment without regard to case.
$body['value']stringYesCiphertext from Envless::encryptValue(), 1 to 20000 characters and prefixed v1: or v2:.
$body['type']stringNoOne of the Envless\Constants\VariableType values, defaults to string.
$body['isSecret']boolNoMarks the variable as a secret, which the example feed reports as 'secret' => true. Stored, but not echoed in the response.
$body['visibility']stringNoOne of the Envless\Constants\VariableVisibilityLevels values, defaults to server.
$body['required']boolNoMarks the variable as required for the environment, defaults to false.
$body['defaultValue']string|nullNoCiphertext fallback encrypted with the same workspace key, or null.
$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 for the new variable, including the generated id you need for apply and the id routes.

Worth knowing

  • isSecret is accepted and stored but is not part of the response body.
  • createMany and apply run the same v1:/v2: prefix check, so plaintext is refused on every write route, not only this one.
  • Names are case reserved, not case normalised. Api_Key is stored as Api_Key, and no other casing of it can exist in the same environment.
  • A name is checked locally before anything is sent, so an unusable name never reaches the network.
  • A local refusal throws Envless\Exception\ApiException with errorCode set to request.body_invalid and field set to 'name', the same vocabulary the API uses, but with requestId left null because nothing was sent.

Required scopes

variables:write

Underlying endpoint

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

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

In TypeScript

envless.variables.create()

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