Null Handling in CFML

edit

Null Support

CFML supports two null handling modes: partial (default) and full. This recipe explains the differences.

Video: https://www.youtube.com/watch?v=GSlWfLR8Frs

Enabling NULL Support

Via Lucee Server Admin > Language/compiler > Null support.

Or per application via Application.cfc / <cfapplication>:

this.nullSupport = true;

Or toggle dynamically:

application action="update" nullsupport="true";

Function Return Values

<cfscript>
    function test() {
    }
    dump( test() );

    t = test();
    dump(t);

    dump( isNull( t ) );
    dump( isNull( notexisting ) );
</cfscript>

A function with no return value returns null. With partial support, referencing t throws "the key [T] does not exist". With full support, t is accessible and isNull(t) returns true.

In both modes, isNull(notexisting) safely returns true for undefined variables.

Query Column Values

query datasource="test" name="qry" {
    echo("select '' as empty, null as _null");
}
dump( qry );
dump( qry._null );

Partial support: qry._null outputs empty string. Full support: outputs Empty: null and isNull(qry._null) returns true.

NullValue() and the null Keyword

With partial support, use NullValue() to explicitly return null:

var possibleVariable = functionThatMayOrMayNotReturnNull();
return possibleVariable ?: NullValue();

With full support, use the null keyword directly:

t = null;
dump( t );

StructKeyExists Behaviour

Key behavioural difference: how StructKeyExists() handles null values.

Partial support - null keys are effectively removed:

s = { foo: nullValue() };
dump( structKeyExists( s, "foo" ) ); // false
dump( s.keyExists( "foo" ) );        // false
dump( structCount( s ) );            // 0 - the key doesn't exist

Full support - keys set to null still exist:

s = { foo: null };
dump( structKeyExists( s, "foo" ) ); // true
dump( s.keyExists( "foo" ) );        // true
dump( structCount( s ) );            // 1 - the key exists
dump( isNull( s.foo ) );             // true - but the value is null

This distinguishes "key exists with null value" from "key doesn't exist" - important for APIs and database results.

JSON Serialization

Partial support - null values removed before serialization:

s = { name: "John", middleName: nullValue() };
dump( serializeJSON( s ) ); // {"name":"John"} - middleName is missing

Full support - null values serialized as JSON null:

s = { name: "John", middleName: null };
dump( serializeJSON( s ) ); // {"name":"John","middleName":null}

Critical for APIs that expect explicit null values rather than missing keys.

See also