Environment variables are a method for injecting information into WordPress and Node.js environments.
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
productionenvironment and a different value to a
- 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.
- An environment variable’s key is limited to 255 bytes.
- An environment variable’s value is limited to 4096 bytes.
- The overall limit of all keys and values of an environment’s environment variables is 16384 bytes.
- New or updated environment variables will not be available until the application’s next code deployment.
Some environment variable names are reserved:
- The prefixes
IS_VIP_are reserved and cannot be used for environment variable naming.
- To avoid conflicts, names reserved for WordPress constants (e.g.,
DB_NAME) cannot be used as environment variables.
- VIP-CLI is installed and has been updated to the most current version.
- Environment variables can only be managed with VIP-CLI
- Environment variables can only be edited by users with an Org admin role or an App admin role for that application. Users with lower capabilities will only have the ability to
listthe names of environment variables that have been defined.
Manage environment variables with VIP-CLI
Manage environment variables with the subcommands of the VIP-CLI command:
vip config envvar [options] [command]
Add or update a value
To add or update an environment variable and assign it a value:
vip config envvar set [options]
New or updated environment variables will not be available until the application’s next code deployment.
In this example, the new environment variable
EXAMPLE_ENV_VAR is added:
vip @wpvip.production config envvar set EXAMPLE_ENV_VAR
At the next prompt in the command line, the value
1234567890 is assigned to the
EXAMPLE_ENV_VAR variable :
For multiline input, use the --from-file option. ✔ Enter the value for EXAMPLE_ENV_VAR: · 1234567890
The user confirms that the entered value is correct:
✔ Please confirm the input value above (y/N) · true
Successfully added environment variables and values will return output similar to this message:
Successfully set environment variable "EXAMPLE_ENV_VAR"
Accepted values: A relative or absolute path to a UTF-8-encoded text file
--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
vip @mytestsite.develop config envvar set EXAMPLE_ENV_VAR --from-file=/path/to/public.pem
Accessing environment variables in an application
Environment variables are always provided as strings, even if their value resembles another data type (e.g.,
"[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.
Environment variables are provided as actual environment variables and are accessed using
process.env. For example:
const apiKey = process.env.EXAMPLE_ENV_VAR || null;
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 );
Both the the
Environment::get_var() helper method and the
vip_get_env_var helper function are available for use in
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 using a different method.
This method will only work for the VIP Local Development Environment as expected if:
--app-codeoption 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:
Though definitions for constants can be added to any file loaded by WordPress, it is strongly 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
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 );
Last updated: October 30, 2023