Using periods in variable references

Last updated on Jun 9, 2023 | Also applies to ColdFusion

ColdFusion uses the period (.) to separate elements of a complex variable such as a structure, query, XML document object, or external object, as in MyStruct.KeyName. A period also separates a variable scope identifier from the variable name, as in Variables.myVariable or CGI.HTTP_COOKIE.
With the exception of Cookie and Client scope variables, which must always be simple variable types, you cannot normally include periods in simple variable names. However, ColdFusion makes some exceptions that accommodate legacy and third-party code that does not conform to this requirement.
For more information, see About scopes, Using Arrays and Structures, and Using XML and WDDX.

Understanding variables and periods

The following descriptions use a sample variable named MyVar.a.b to explain how ColdFusion uses periods when getting and setting the variable value.

Getting a variable

ColdFusion can correctly get variable values even if the variable name includes a period. For example, the following set of steps shows how ColdFusion gets MyVar.a.b, as in <cfset Var2 = myVar.a.b> or IsDefined(myVar.a.b):

Looks for myVar in an internal table of names (the symbol table).
If myVar is the name of a complex object, including a scope, ColdFusion looks for an element named "a" in the object. If myVar is not the name of a complex object, checks whether myVar.a is the name of a complex object and skips step 3.
If myVar is the name of a complex object, checks whether a is a complex object.
If a or myVar.a is the name of a complex object, checks whether b is the name of a simple variable, and returns the value of b.If myVar is a complex object but a is not a complex object, checks whether a.b is the name of a simple variable and returns its value.If myVar.a is not a complex object, checks whether myVar.a.b is the name of a simple variable and returns its value.
This way, ColdFusion correctly resolves the variable name and can get its value.
You can also use array notation to get a simple variable with a name that includes periods. In this form of array notation, you use the scope name (or the complex variable that contains the simple variable) as the "array" name. You place the simple variable name, in single- or double-quotation marks, inside the brackets.
Using array notation is more efficient than using plain dot notation because ColdFusion does not have to analyze and look up all the possible key combinations. For example, both of the following lines write the value of myVar.a.b, but the second line is more efficient than the first:

<cfscript>
    variables.myVar.a.b = "apple";
    writeDump( variables[ "myVar.a.b" ] );
</cfscript>

Setting a variable

ColdFusion cannot be as flexible when it sets a variable value as when it gets a variable, because it must determine the type of variable to create or set. Therefore, the rules for variable names that you set are stricter. Also, the rules vary depending on whether the first part of the variable name is the Cookie or Client scope identifier.
For example, assume that you have the following code:

<cfset myVar.a.b = "This is a test">

If a variable myVar does not exist, it does the following:

Creates a structure named myVar.
Creates a structure named a in the structure myVar.
Creates a key named b in myVar.a.
Gives it the value "This is a test".
If either myVar or myVar.a exist and neither one is a structure, ColdFusion generates an error.
In other words, ColdFusion uses the same rules as for getting a variable to resolve the variable name until it finds a name that does not exist yet. It then creates any structures that are needed to create a key named b inside a structure, and assigns the value to the key.
However, if the name before the first period is either Cookie or Client, ColdFusion uses a different rule. It treats all the text (including any periods) that follow the scope name as the name of a simple variable, because Cookie and Client scope variables must be simple. If you have the following code, you see that ColdFusion creates a single, simple Client scope variable named myVar.a.b:

<cfdump var=#Client.myVar.a.b#>

Creating variables with periods

Avoid creating the names of variables (except for dot notation in structures) that include periods. However, ColdFusion provides mechanisms for handling cases where you must do so, for example, to maintain compatibility with names of variables in external data sources or to integrate your application with existing code that uses periods in variable names. The following sections describe how to create simple variable names that include periods.

Using brackets to create variables with periods

You can create a variable name that includes periods by using associative array structure notation, as described in Structure notation in the About arrays. To do so, you must do the following:

Reference the variable as part of a structure. You can always do this, because ColdFusion considers all scopes to be structures. For more information on scopes, see About scopes.
Place the variable name that must include a period inside brackets and single- or double-quotation marks.
The following example shows this technique:

<cfscript>
Request["Another.Variable.With.Periods"] = "Test variable";
writeOutput("My.Variable.With.Periods is: #My.Variable.With.Periods#
Request.Another.Variable.With.Periods is:
#Request.Another.Variable.With.Periods#");
</cfscript>

Creating Client and Cookie variables with periods

To create a Client or Cookie variable with a name that includes one or more periods, simply assign the variable a value. For example, the following line creates a Cookie named User.Preferences.CreditCard:

<cfset Cookie.User.Preferences.CreditCard="Discover">

Using the safe navigation operator

The 2016 release of ColdFusion introduces safe navigation operator (?.) to access members of a struct or values of an object.

Instead of ".", use the safe operator to make sure that an exception is not thrown when a variable is not defined.

In ColdFusion (2016 release), you can use safe navigation as follows:

writeOutput( myvar ?.firstlevel?.nextlevel?.udf()?.trim());

When you use the hook operator ("?") in conjunction with the period operator ("."), you have the safe navigation operator ("?.").

If you use a variable that is undefined or a java null, then instead of throwing an error, the safe navigation operator returns undefined for that particular access, otherwise it behaves
exactly the same as the period (“.”) operator.

For example, if you do not define the variable myvar, then myvar?.firstlevel returns undefined, otherwise it returns the value of “myvar.firstlevel”.

You can use safe navigation with function calls, struct access, or both.

If you use the safe navigation operator on function calls, it returns undefined if:

the function throws an error or
the function does not exist

Otherwise it behaves exactly the same as the period (“.”) operator.

The safe navigation operator handles undefined variables, null variables, errors in function calls, and so on. Use the operator to skip runtime errors.

Get help faster and easier

New user?