Variables in CFML; Transient Variable Scopes

Transient variable scopes exist for the current page request only and are private to the current request. No modification to a transient scoped variable can affect in any way another request. Unless otherwise noted all of the following scopes exist in all versions of ColdFusion .

Variables Scope

When not within a ColdFusion component or function any variable not specifically created in another scope automatically becomes a member of the variables scope. For example the variable "foo" created with a simple CFSET tag such as <cfset foo = 10> automatically becomes a member of the variables scope and can be accessed as variables.foo. As the variables scope is the lowest level "catch-all" scope most developers don't explicitly scope variables within it. Instead they rely on ColdFusion's automatic discovery.

The variables scope can be accessed as a structure only in ColdFusion MX or higher.

CGI Scope

The CGI scope contains variables and values passed to ColdFusion from the Web server (sometimes called "HTTP" or "environment" variables). These values are specific to the current page request and the number of variables may change depending on the Web server and version of the HTTP protocol being used. CGI variables are read-only (although a bug in some versions of ColdFusion does allow you to write to them).

Some common CGI variables are:

CGI.QUERY_STRING: The query string (if any) of the current request.
CGI.SERVER_PORT: The port (for example "80" or "443") of the current request.
CGI.SCRIPT_NAME: The name of the currently executing script.

The ColdFusion documentation contains a list of the most common CGI variables. Web servers may also return custom CGI variables so the variables accessible are dependent on the platform being used. The CGI scope can be accessed as a structure in ColdFusion 4.5 or higher.

URL Scope

The URL scope contains values passed to the current request on the URL (also known as the "command line" in some circles). The following URL:

http://www.mysite.com/index.cfm?foo=hello&fee=15&faa=goodbye

When called would result in the following variables being automatically created on the "index.cfm" page:

URL.foo
URL.fee
URL.faa

ColdFusion automatically decodes values passed on the URL (it converts the special characters used back into the actual characters). However when you place information on the URL (to pass to another template) you must use the URLEncodedFormat() function if the data contains non-alphanumeric characters (spaces, symbols, etc).

The URL scope may allow variable names that are not legal in CFML. For example the URL may contain the following: "index.cfm?1foo=hello". The variable name "1foo" is illegal in CFML but may be legal in other languages or environments. Because of this ColdFusion is lenient in this respect and will allow this variable to be passed to the URL scope but will not allow it to be created directly in CFML. Despite this we urge you to always follow CFML's variable naming rules whenever possible.

HTML forms that use the method "GET" will pass their information on the URL. The URL scope can be accessed as a structure in ColdFusion 4.5 or higher.

Form Scope

A template that receives a form submission of method "POST" (in other words it is the "ACTION" page of a form) places those values into the Form scope. (A form using the "GET" method will pass its information into the URL scope.) In general the name of each form field becomes the variable name within the Form scope. There are some oddities to note however:

When two form fields have the same name ColdFusion generally presents all values as a comma-delimited list. This behavior may be overridden by the browser however and some older browsers will only pass the last such field to the server. It is highly recommended that you make all field names unique within the form.
Form check boxes and radio buttons do not pass any value and are not created as variables unless they are checked. Select lists (drop down lists) may not pass a value. Most modern browser default select lists to the first option, however older browsers did not.
An input element of the type "submit" will not be created as a variable unless it is pressed and has a NAME attribute.
When using a button of type "image" two variables will be returned buttonName.x and buttonName.y (where "buttonName" is the name of the image button in question). These variables contain integer values and indicate the exact pixel position (x.y. coordinates) of the mouse click on the button.
Like the URL scope form fields passed to ColdFusion templates may feature names not legal in CFML. ColdFusion will allow these names to persist in the Form scope but will not allow them to be created directly.

The Form scope can be accessed as a structure in ColdFusion 4.5 or higher.

Request Scope

The request scope was introduced in ColdFusion 4.5 and can be thought of as a global scope for a request (a single call to a CFM page). Any variable added to the request scope is available to the current page and any CFML custom tags (no matter how deeply nested) it may call.

When introduced the Request scope replaced many uses previously filled by the Application scope (described later). Since it's a transient scope the Request scope, unlike the Application scope, doesn't require locking of any kind. It is best used to store application configuration values such as DSN names, application settings, email addresses, etc. The Request scope is also useful to store the results of recursive custom tag operations without having to explicitly pass the values between the custom tags.

A popular technique used to reduce the locking required when using persistent scopes is to copy the contents of those scopes (Application or Session) to the Request scope. The utility of this technique is debatable however as many reports indicate that using it is less performant than properly locking accesses.

The request scope can be accessed as a structure.