Manage environment variables

Environment variables are a method for injecting information into a VIP Platform environment.

Environment variables are commonly used to:

• Provide sensitive values (such as API secrets) to an application without committing the values to a site’s GitHub repository or storing the values in a site’s database.
• Provide flags that can be used to vary behavior between environments. For example, an environment variable can be set to provide one value to a production environment and a different value to a develop environment.

Reserved names

Some environment variable names are reserved:

• To avoid conflicts, names reserved for WordPress constants (e.g., DB_NAME) cannot be used as environment variables.
• Names starting with VIP_ are reserved for use by VIP.

Managing environment variables with VIP-CLI

Each VIP Platform environment has its own discrete set of environment variables. For an environment variable to be available on all environments, it must be set on each environment separately.

set

Add or update an environment variable and assign it a value.

In this example, the new environment variable EXAMPLE_ENV_VAR is added:

vip @mytestsite.develop config envvar set EXAMPLE_ENV_VAR          

The value 1234567890 is assigned to the EXAMPLE_ENV_VAR variable at the next prompt:

For multiline input, use the --from-file option.

✔ Enter the value for EXAMPLE_ENV_VAR: · 1234567890

Confirm that the entered value is correct:

✔ Please confirm the input value above (y/N) · true

An environment variable and value that has been successfully added will return the output:

Successfully set environment variable "EXAMPLE_ENV_VAR"

--from-file

Accepted values: A relative or absolute path to a UTF-8-encoded text file

The --from-file option extracts a string from the file existing at the relative or absolute path in the passed value.

Use of the --from-file option is required for a string that has multiple lines created by newlines.

For example, to assign the multiline contents of a *.pem file as the value for the environment variable EXAMPLE_ENV_VAR:

vip @mytestsite.develop config envvar set EXAMPLE_ENV_VAR --from-file=/path/to/public.pem

delete

Remove an environment variable.

vip @mytestsite.develop config envvar delete EXAMPLE_ENV_VAR

get

Retrieve the value of an environment variable.

vip @mytestsite.develop config envvar get EXAMPLE_ENV_VAR

get-all

Retrieve the values of all environment variables.

vip @mytestsite.develop config envvar get-all

If values exist, they will be returned in this format:

┌─────────────────┬────────────┐
│ name            │ value      │
├─────────────────┼────────────┤
│ EXAMPLE_ENV_VAR │ 1234567890 │
└─────────────────┴────────────┘

list

List all environment variables.

vip @mytestsite.develop config envvar list

If values exist, they will be returned in this format:

┌─────────────────┐
│ name            │
├─────────────────┤
│ EXAMPLE_ENV_VAR │
└─────────────────┘

Help menu

View the full list of commands, options, and examples for vip config envvar:

vip config envvar --help

Accessing environment variables in an application

Environment variables are always provided as strings, even if their value resembles another data type (e.g., "true", "123", "[1, 2, 3]"). String values can be converted or deserialized by an application into the desired data type, but they should be validated thoroughly.

On the VIP Platform, environment variables are accessed differently depending on the application type.

Node.js

Environment variables are provided as actual environment variables and are accessed using process.env. For example:

const apiKey = process.env.EXAMPLE_ENV_VAR || null;

WordPress

Environment variables are accessed using the Environment::get_var() helper method or vip_get_env_var helper function. For example:

<?php
// Using class method
$api_key = Automattic\VIP\Environment::get_var( 'EXAMPLE_ENV_VAR', $default_value );
// Using helper function
$api_key = vip_get_env_var( 'EXAMPLE_ENV_VAR', $default_value );

Managing environment variables for a VIP Local Development Environment

VIP-CLI can only be used to manage environment variables on VIP Platform environments. On a VIP Local Development Environment, an environment variable must be manually added as a defined constant.

This method will only work as expected if:

• The --app-code option is set to a path to a git clone of an application’s wpcomvip GitHub repository on the local machine.
• The constant for the added environment variable includes the prefix: VIP_ENV_VAR_.

Definitions for constants can be added to any file loaded by WordPress, but it is recommended to create a file in the client-mu-plugins directory that is dedicated to defining constants for the local environment. After creating the file, add it to .gitignore (e.g., client-mu-plugins/*.local.php) to avoid committing sensitive values to source control.

In this example, a file named client-mu-plugins/vip-env-vars.local.php has been created and a definition for the environment variable MY_CUSTOM_VAR is added:

<?php
/**
 * Local environment variables
 */

define( 'VIP_ENV_VAR_MY_CUSTOM_VAR', 'my custom value' );

Once defined, the same methods for accessing environment variables in a VIP Platform environment can be used on the local environment:

$my_value = vip_get_env_var( 'MY_CUSTOM_VAR', $default_value );