Environment variables¶

Environment Variables for Applications on Hosting Solutions¶

Applications hosted on our platform can utilize environment variables to manage configuration and operational settings. Among these variables, the DXP_VARIABLES environment variable is central, providing access to all tokens configured for a specific environment.

`DXP_VARIABLES` Overview¶

The DXP_VARIABLES environment variable is a Base64-encoded, JSON-formatted string. It encapsulates all token definitions from the Token Management UI, excluding the enclosing square brackets. These tokens are dynamically replaced during deployment and reflect the values defined at various levels (global, project, or environment).

To use this variable, follow these steps:

Decode the Base64 string.
Parse the resulting JSON string.
Access the desired token values as key-value pairs in a dictionary or object.

Examples of Usage¶

Below are code snippets in popular programming languages and CLI to demonstrate how to decode and utilize DXP_VARIABLES:

PHP Example¶

// Decode and parse the DXP_VARIABLES
$DXP_VARIABLES = json_decode(base64_decode(getenv('DXP_VARIABLES')), true);
$database_name = $DXP_VARIABLES['database_name'];

Node.js Example¶

// Decode and parse the DXP_VARIABLES
const DXP_VARIABLES = JSON.parse(
Buffer.from(process.env.DXP_VARIABLES, 'base64').toString('utf-8')
);
const databaseName = DXP_VARIABLES.database_name;

CLI Example¶

# Decode and parse the DXP_VARIABLES
dxp_vars=$(echo $DXP_VARIABLES | base64 --decode)
database_name=$(echo $dxp_vars | jq -r .database_name)

Key Points¶

Dynamic Updates: The DXP_VARIABLES environment variable is regenerated during every deployment, ensuring it always reflects the latest token configurations.
Secure Access: Sensitive data stored as tokens is securely encrypted and decrypted only when accessed via the deployment process or environment variables.
Flexibility: This variable is compatible across multiple runtime environments, making it suitable for various frameworks and deployment strategies.

Simplify access with the DXP environment variable packages¶

For Composer-based projects, use these two packages to work with DXP_VARIABLES more conveniently:

dropsolid/dxp-env-var — expands DXP_VARIABLES into individual environment variables automatically, early in the request lifecycle. Once installed, every token is available as $_ENV['TOKEN_NAME'] or getenv('TOKEN_NAME'), without needing to decode DXP_VARIABLES yourself.
dropsolid/dxp-env-var-dumper — brings the same tokens to your local environment via a Drush command that dumps an environment's tokens into a local .env.json file.

Installing the packages¶

composer require dropsolid/dxp-env-var:^1.0
composer require --dev dropsolid/dxp-env-var-dumper:^1.0

Using a token¶

Once installed, replace any hardcoded secret or credential with a token reference:

$apiKey = $_ENV['MY_API_KEY'];

Create the token in the Token Management UI for your project (optionally overriding it per environment).
Deploy the environment — the token becomes available automatically.

Pulling tokens to your local environment¶

drush dxp:env-var:dump @project.env

This writes the environment's tokens into a local .env.json file.
Values can be overridden locally with a .env.local.json file — make sure this file is git-ignored.

Configuration¶

By default, the local dump file is written to the project root. You can change this in composer.json:

"extra": {
  "dxp-env-var": {
    "dump-directory": "./etc/env"
  }
}

For more detailed information about tokens and their usage, refer to the Token Management documentation.

← Previous Mailpit Next → Overview

Environment variables¶