Use variables

Get a list of all variables defined on a given environment in the Console or use the CLI:

platform var

You get output similar to the following:

Variables on the project Example (abcdef123456), environment main:
+------+---------+-------+---------+
| Name | Level   | Value | Enabled |
+------+---------+-------+---------+
| foo  | project | bar   | true    |
+------+---------+-------+---------+

Access variables in a shell

Project and environment variables with the prefix env: are available as Unix environment variables in all caps. Access these variables and Platform.sh-provided variables directly like this:

echo $FOO
bar
echo $PLATFORM_APPLICATION_NAME
Sample Project

Other project and environment variables are listed together in the PLATFORM_VARIABLES variable as a base64-encoded JSON object. Access them like this:

echo $PLATFORM_VARIABLES | base64 --decode
{"theanswer": "42"}

You can also get the value for a single variable within the array, such as with this command, which uses the jq processor:

echo $PLATFORM_VARIABLES | base64 --decode | jq '.theanswer'
"42"

Variable availability depends on the type and configuration. Variables available during builds can be accessed in build hooks and those available at runtime can be accessed in deploy hooks.

Access variables in your app

To access environment variables in your app, you can use the Platform.sh Config Reader for the given language:

• PHP
• Python
• Node.js
• Go
• Java
• Ruby
• Elixir

Alternatively, use a built-in method for the given language.

<?php

// A simple variable.
$projectId = getenv('PLATFORM_PROJECT');

// An encoded JSON object.
$variables = json_decode(base64_decode(getenv('PLATFORM_VARIABLES')), TRUE);

import os
import json
import base64

# A simple variable.
project_id = os.getenv('PLATFORM_PROJECT')

# An encoded JSON object.
variables = json.loads(base64.b64decode(os.getenv('PLATFORM_VARIABLES')).decode('utf-8'))

const { env } = process;

// Utility to assist in decoding a packed JSON variable.
function read_base64_json(varName) {
  try {
    return JSON.parse(Buffer.from(env[varName], "base64").toString());
  } catch (err) {
    throw new Error(`no ${varName} environment variable`);
  }
};

// A simple variable.
const projectId = env.PLATFORM_PROJECT;

// An encoded JSON object.
const variables = read_base64_json('PLATFORM_VARIABLES');

# A simple variable.
project_id = ENV["PLATFORM_PROJECT"] || nil

# An encoded JSON object.
variables = JSON.parse(Base64.decode64(ENV["PLATFORM_VARIABLES"]))

import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.IOException;
import java.util.Base64;
import java.util.Map;

import static java.lang.System.getenv;
import static java.util.Base64.getDecoder;

public class App {

    public static void main(String[] args) throws IOException {
        // A simple variable.
        final String project = getenv("PLATFORM_PROJECT");
        // An encoded JSON object.
        ObjectMapper mapper = new ObjectMapper();
        final Map<String, Object> variables = mapper.readValue(
                String.valueOf(getDecoder().decode(getenv("PLATFORM_VARIABLES"))), Map.class);
    }
}

Access complex values

Variables can have nested structures. The following example shows nested structures in an app configuration:

variables:
  env:
    BASIC: "a string"
    INGREDIENTS:
      - 'peanut butter'
      - 'jelly'
    QUANTITIES:
      "milk": "1 liter"
      "cookies": "1 kg"
  stuff:
    STEPS: ['one', 'two', 'three']
    COLORS:
      red: '#FF0000'
      green: '#00FF00'
      blue: '#0000FF'

You can access these nested variables as follows:

echo $BASIC
a string
echo $INGREDIENTS
["peanut butter", "jelly"]
echo $QUANTITIES
{"cookies": "1 kg", "milk": "1 liter"}
echo "$PLATFORM_VARIABLES" | base64 --decode | jq '."stuff:STEPS"'
[
  "one",
  "two",
  "three"
]
echo "$PLATFORM_VARIABLES" | base64 --decode | jq '."stuff:COLORS"'
{
  "blue": "#0000FF",
  "green": "#00FF00",
  "red": "#FF0000"
}

<?php
var_dump($_ENV['BASIC']);
// string(8) "a string"

var_dump($_ENV['INGREDIENTS']);
// string(26) "["peanut butter", "jelly"]"

var_dump($_ENV['QUANTITIES']);
// string(38) "{"milk": "1 liter", "cookies": "1 kg"}"

$variables = json_decode(base64_decode($_ENV['PLATFORM_VARIABLES']), TRUE);

print_r($variables['stuff:STEPS']);
/*
array(3) {
  [0]=>
  string(2) "one"
  [1]=>
  string(4) "two"
  [2]=>
  string(5) "three"
}
*/

print_r($variables['stuff:COLORS']);
/*
array(3) {
  ["red"]=>
  string(7) "#FF0000"
  ["green"]=>
  string(7) "#00FF00"
  ["blue"]=>
  string(7) "#0000FF"
}
*/

import os
import json
import base64

print os.getenv('BASIC')
# a string

print os.getenv('INGREDIENTS')
# ["peanut butter", "jelly"]

print os.getenv('QUANTITIES')
# {"milk": "1 liter", "cookies": "1 kg"}

variables = json.loads(base64.b64decode(os.getenv('PLATFORM_VARIABLES')).decode('utf-8'))

print variables['stuff:STEPS']
# [u'one', u'two', u'three']
print variables['stuff:COLORS']
# {u'blue': u'#0000FF', u'green': u'#00FF00', u'red': u'#FF0000'}

scriptconst { BASIC, INGREDIENTS, QUANTITIES, PLATFORM_VARIABLES } = process.env;

const { "stuff:STEPS": stuffSteps, "stuff:COLORS": stuffColors } = JSON.parse(
  Buffer.from(PLATFORM_VARIABLES, "base64").toString()
);

console.log(BASIC);
// "a string"
console.log(INGREDIENTS);
// ["peanut butter", "jelly"]
console.log(QUANTITIES);
// {"cookies": "1 kg", "milk": "1 liter"}
console.log(stuffSteps);
// [ 'one', 'two', 'three' ]
console.log(stuffColors);
// { blue: '#0000FF', green: '#00FF00', red: '#FF0000' }

Use provided variables

Platform.sh also provides a series of variables to inform your app about its runtime configuration. They’re mostly prefixed with PLATFORM_ to differentiate them from user-provided values. You can’t set or update them directly.

The most important of these variables is the relationship information in PLATFORM_RELATIONSHIPS, which tells the app how to connect to databases and other services defined in .platform/services.yaml.

The following table presents all available variables and whether they’re available at build time (during build hooks) and at runtime.

Variables on Dedicated Gen 2 environments

Dedicated Gen 2 instances also have the following variables available:

Distinguish Dedicated Gen 2 environment types

While both production and staging Dedicated Gen 2 environments have enterprise for the PLATFORM_MODE variable, you can distinguish them by environment type. Make sure that the environment type is set correctly via the CLI or Console. Then run different code based on the type:

if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ] ; then
    echo "This is live on production"
else if [ "$PLATFORM_ENVIRONMENT_TYPE" = staging ] ; then
    echo "This is on staging"
else
    echo "We're on development"
fi

PLATFORM_APPLICATION

The PLATFORM_APPLICATION variable is available both at build time and in the runtime environment. But the specific attributes it contains differ in each case.

Each environment’s build is associated with a configuration ID that identifies it uniquely so builds can be reused. The ID is a product of your app code and some of its configuration for Platform.sh. Not every attribute your app configuration is relevant to the build. Only those attributes that are relevant to builds are accessible at build time from PLATFORM_APPLICATION.

Attributes that are not available in PLATFORM_APPLICATION during builds:

• Everything under access
• Everything under relationship
• Everything under firewall
• hooks.deploy and hooks.post_deploy
• Everything under crons
• Everything under web, except web.mounts
• Everything under workers, except workers.mounts

These attributes aren’t visible during build because they aren’t included as a part of the configuration component of the build slug. So modifying these values in your app configuration doesn’t trigger an app rebuild, only a redeploy. For more information, read about how builds work.

Use variables in static files

Some apps require configuration values to be specified in a static, non-executable file (such as a .ini, .xml, or .yaml file) and don’t support reading from environment variables.

To populate these files with variables you set yourself, make sure the variables are set to be visible at build time.

The files can’t be populated with Platform.sh-provided variables not available at build time (such as PLATFORM_RELATIONSHIPS). You also can’t write to them in a deploy hook as the file system is read only.

One workaround is to create a symbolic link to a writable location and then write to it in a deploy hook. The following example shows the process, though you have to modify it to fit your needs.

1. Create a mount that isn’t accessible to the web in your app configuration:

   .platform.app.yaml

   mounts:
     /config:
       source: local
       source_path: config

2. Create a symbolic link from the config file the application wants to a location in that mount:

   # From the application root...
   
   ln -s config/db.yaml db.yaml

   This example assumes the app wants a db.yaml file in its root for configuration.

3. Commit the symbolic link and an empty config directory to Git.

4. Configure a script to read from environment variables and write to config/db.yaml. Create a file with a shell script similar to this:

   export-config.sh

   #!/bin/bash
   
   # Ensure the file is empty.
   cat '' > config/db.yaml
   
   # Map the database information from the PLATFORM_RELATIONSHIPS variable into the YAML file.
   # Use this process to use whatever variable names your app needs.
   
   printf "host: %s\n" $(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".database[0].host") >> config/db.yaml
   printf "user: %s\n" $(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".database[0].username") >> config/db.yaml

5. Call the script from the deploy hook your app configuration:

   .platform.app.yaml

   hooks:
     deploy: |
       bash export-config.sh    

Now, when your app starts and attempts to parse db.yaml, the symbolic link redirects it to config/db.yaml. Your script writes to that file on each deploy with updated information. Your app reads the exported values and proceeds as expected.