PHP 8.3: Fallback value support for PHP INI Environment Variable syntax

PHP Supports substituting PHP INI values with Environment variables with PHP's string interpolation syntax. If the specified Environment variable is not available, the INI parser uses an empty string. In PHP 8.3, this syntax is extended to support declaring a fallback value if the Environment variable is not set.

session.name = ${SESSION_NAME}
sendmail_from = "${MAIL_FROM_USER}@${MAIL_FROM_DOMAIN}"

ini_get('session.name');
ini_get('sendmail_from');

All of the PHP versions support the syntax above to use Environment variables in PHP INI files. In this instance, the session.name INI value will be set to the SESSION_NAME Environment variable if set, or an empty string otherwise. The sendmail_from value uses string interpolation, and PHP substitutes the available Environment variables along with the @ character in the middle.

PHP does not emit any warnings at startup or parse time when the Environment variables are not present, and always substitutes it with an empty string.

---

PHP 8.3 extends the support for INI Environment variable substitution with support for declaring a fallback value.

In PHP 8.3 and later, it is possible to optionally declare a fallback value with the :- symbol, followed by the fallback value. The same INI values declared in the snippet above can now be set with fallback values:

session.name = ${SESSION_NAME:-Foo}
sendmail_from = "${MAIL_FROM_USER:-info}@${MAIL_FROM_DOMAIN:-example.com}"

ini_get('session.name');
ini_get('sendmail_from');

PHP 8.3 parses these values with support for fallback values specified after the :- symbol.

For example, the session.name value will be the value of the SESSION_NAME Environment variable if it is set, but it now uses Foo value otherwise.

sendmail_from value will also fall back to info@example.com if both MAIL_FROM_USER and MAIL_FROM_DOMAIN Environment variables are not set. If either of them are available, the Environment variable will be used.

Supported Functions

The fallback value syntax is supported in all PHP functions that return, set, and parse INI values. This includes:

• ini_get()
• ini_get_all()
• ini_set()
• get_cfg_var()
• parse_ini_string()
• parse_ini_file()

Recursive Replacements

Environment variable fallback syntax also supports an Environment variable as the fallback value, which can in turn support other fallback variables as well.

session.name = ${SESSION_NAME:-${APP_NAME:-Login}}

In this declaration, PHP uses SESSION_NAME Environment variable if it's available. Otherwise, PHP tries to use APP_NAME if it's available. Finally, it uses Login as the fallback.

PHP Constants as Fallback Values

For PHP INI values that support changing them at run-time, the INI syntax also supports using PHP constants as the fallback value:

define('APP_NAME', "MyApp");
parse_ini_string('name = ${SESSION_NAME:-APP_NAME}');

[
    "name" => "MyApp",
]

Type Coercion

PHP tries to coerce the fallback values following the same rules for standard string literal configuration values as well.

true_true = true
true_fallabck = ${FOOBAR:-true}

All of the values above are coerced to "1" when parsed.

---

false_false = false
false_fallabck = ${FOOBAR:-false}

All of the values above are coerced to "" (not "0") when parsed.

---

null constants and non-existing Environment variables are replaced with an empty string ("")

Security Considerations

Even prior to this change, parsing user-provided and arbitrary INI values must be validated to not contain Environment values that should not be disclosed to the user.

With the new change, the syntax gains support for PHP constants as well, which also must be carefully considered.

Security considerations when parsing user-provided INI strings and files

By default, parse_ini_file and parse_ini_string functions process environment variables and PHP constants. When parsing INI values, always use the INI_SCANNER_RAW flag to make sure the PHP's environment variable and constant substitution is disabled.

---

Backward Compatibility Impact

The new syntax cannot be back-ported to old PHP versions. However, a user-land INI parser might be able to mimic this behavior by correctly interpolating the values with the ${FOO:-BAR} syntax.

Attempting to parse INI strings and files that use this new syntax will not throw any exceptions or emit errors. They will be silently substituted with an empty string as if the environment variable with the name FOO:-BAR does not exist.

---

Implementation