Differences From CFML

A quick guide on key differences and issues when migrating from CFML

Please note that our CFML Compatibility is still in progress. Please keep this page bookmarked as we progress to our stable release.

BoxLang is a new language with a dual parser to support the CFML ecosystem. It also has a compatibility module (bx-compat-cfml) that will allow the BoxLang runtime to behave like an Adobe or Lucee Server. We also recommend you read the Quick Syntax Style Guide to understand all the new features of BoxLang.

You can install the compatibility module using box install bx-compat-cfml or if you have a server.json you can add the following:

    "scripts":{
        "onServerInitialInstall":"install bx-compat-cfml"
    }

Even if you forget the server, when you start it up, it’ll get the compatibility module automatically.

File Types

BoxLang can parse and run all of the traditional CFML file types

• .cfc - Components

• .cfs - Scripts

• .cfm - Templates

Components are Classes

CFML Components (CFCs) are called classes in BoxLang, like any other language. You can also use the class declaration for them. You can continue to write components if you like, but if you use our .bx extensions, they are now classes.

class{

    property name=¨firstName¨

}

Tags are Components

Since BoxLang is not a tag-based language but a dynamic language offering a templating language. There are no concepts of tags but of BoxLang components that can be accessed via our templating language or script. In CFML the templating language uses a <cf prefix, in BoxLang we use a <bx: prefix.

<bx:if expression>

<bx:else>

</bx:if>

Default assignment scope

In CFML, the default assignment scope is always variables, but in BL it can differ based on the context. For Functions, it will be local. The BoxLang runtime will toggle this behavior based on the type of the compiled source code. So for .cfm or .cfc source files, the default assignment scope in functions will remain variables but for code compiled from .bx, .bxs or .bxm files, the default assignment scope in functions will be local.

CastAs operator

BoxLang has a new castAs binary operator that you can use instead of the javaCast() bif.

expression castAs type

No transpilation changes are needed since this is a BL-only feature.

Multiple catch types

BoxLang supports

catch( foo.com | brad | com.luis.majano e ) {}

No transpilation changes are needed since this is a BL-only feature.

Annotations

BoxLang will allow for proper annotations before UDF declarations, properties, and classes. The annotation's value can be a string, struct literal, or array literal. You can also use multi-spaced or indentation.

@foo
@bar( value )
@output( true )
function myFunc() {
}

No transpilation changes are needed since this is a BL-only feature.

Documentation Comments (Javadoc style)

BL will support documentation comments like CF, but will NOT allow them to actually influence the function’s behavior. When transpiling CFML to BL, any annotations set in a doc comment modifying the function or any arguments need to be moved to proper annotations in BL.

So the CFML

/**
* My function hint
*
* @output false
* @brad wood
* @name Luis
*
* @myService my hint here for the arg
* @myService.inject
*/
function foo( required any myService ) {}

would turn into this BoxLang

/**
* My function hint
*
* @myService my hint here for the arg
*/
@output( false)
@brad( wood ) // Strings can use quotes or no quotes
@name( “Luis” )
@myService.inject
function foo( required any myService ) {}

Function output defaults to false

The output of functions will be false in BL. The BoxLang runtime will toggle this behavior based on the type of the compiled source code. So for .cfm or .cfc source files, default value of the output annotation on classes and functions will remain true but for code compiled from .bx, .bxs or .bxm files, the default value of the output annotation on classes and functions will be false.

Accessors True

Accessors in BoxLang are automatically true for all classes by default. This is false for CFML. You can also disable as normal if needed.

@displayName( “user” )
class{

    Property name=“fullName”;
    
}

// Accessors are on by default
user = new User()
user.setFullName( “Luis” )
println( user.getFullName() )

Invoke Implicit Accessors True

We also default invoking of implicit accessors by default to true . You can also disable this at the class level or at the runtime level in the configuration. This is a syntactic sugar to make a delegated call to the accessor/mutator by making it look like if they are property access.

@displayName( “user” )
class{

    Property name=“fullName”;
    
}

// Accessors and invoke implicit are on by default
user = new User()
user.fullName = “Luis Majano”
println( user.fullName )

Import keyword

CFML has the import tag, but there doesn’t seem to be any special script version of it, ours looks like this:

import taglib="/relative/path/customTags" prefix="tags";

import package.Class as alias

Import Aliases

You can also import classes from any resolver and attach an alias to remove any ambiguity.

import java:org.apache.User as jUser;
import models.User;

var oUser = new jUser()
var testUser = new User()

Object Resolvers

Any import or new can be prefixed with an object resolvers prefix. A resolver adheres to our resolver interface to provide access into any type of object or filesystem. By default we ship with two resolvers:

1. java : Java classes

2. bx : BoxLang classes

This allows you to import or easily create classes from any source.

// Default resolver is bx : boxlang
import models.User;
// Same as
import bx:models.User;

// Java resolver
import java:java.util.ConcurrentHashMap;

// Custom Resolver
import cborm:entity

This will allow us to modularly provide object resolvers for any type of integrations. You will also be able to use the resolvers for extends and implements

class implements="java:java.util.List" {

}

class extends="java:ortus.boxlang.runtime.types.Struct"{

}

Auto-casting argument and return value types

In CF an argument or return value of Numeric will allow a String through untouched so long as that string can be cast to a number. In BoxLang, we are actively casting the value to a “real” number. In theory, this is seamless, but could affect if you are checking the underlying Java type or passing to a Java method. There is no transpilation that can undo this, unless we add some setting or runtime configuration to disable the “feature”.

GetCurrentTemplatePath() and relative includes

Both Adobe and Lucee do not agree with each other and are inconsistent even within themselves regarding

• The return value of the getCurrentTemplatePath() BIF

• The lookup of relative templates being included

• The lookup of relative CFC paths for object instantiation

Here is some documentation on their differences:

• Given a method that's originally part of a CFC

  • getCurrentTemplatePath() returns the original CFC (Adobe and Lucee agree here)

  • new RelativeCFC() find CFCs in the same folder as the original CFC (Adobe and Lucee agree here)

  • include "relativePath.cfm"; find CFCs in the same folder as the original CFC (Adobe and Lucee agree here)

• Given a UDF defined in a file in a different directory that's injected into another CFC

  • getCurrentTemplatePath()

    • returns the original birthplace of the UDF source in Lucee

    • returns the new CFC the UDF was injected into in Adobe

  • Relative CFC path resolution

    • finds the CFC relative to the original birthplace of the UDF source in Lucee

    • finds the CFC relative to the NEW CFC's path in Adobe

  • Relative cfinclude path resolution

    • finds the CFC relative to the original birthplace of the UDF source in Lucee

    • finds the CFC relative to the original birthplace of the UDF source in Adobe

• Given a UDF defined in a file in a different directory that's passed into a UDF in another CFC for invocation

  • getCurrentTemplatePath()

    • returns the new CFC the UDF was injected into in Lucee

    • returns the new CFC the UDF was injected into in Adobe

  • Relative CFC path resolution

    • finds the CFC relative to the original birthplace of the UDF source in Lucee

    • finds the CFC relative to the NEW CFC's path in Adobe

  • Relative cfinclude path resolution

    • finds the CFC relative to the original birthplace of the UDF source in Lucee

    • finds the CFC relative to the original birthplace of the UDF source in Adobe

In BoxLang, this is being simplified and made consistent across the board. In ALL cases the “current template path” and relative lookup directory will tie to the original source path on disk of the file that contains the currently executing code. So, whether it’s an include, a UDF, an injected UDF from another location, or a closure defined elsewhere - whatever original source file for the code in question is what determines the “current template path” and relative lookups.

BIF Renaming

Some bifs have been renamed in BoxLang.

CFML	BoxLang
asc	ascii
chr	char
deserializeJSON	jsonDeserialize
getComponentMetadata	getClassMetadata
serializeJSON	jsonSerialize

CreateObject Types

The component type for create object becomes class in BoxLang

createObject( ”class”, path )

JDBC Queries

Parameter SQL Types

Both Adobe ColdFusion and Lucee Server utilize a cfsqltype key on query parameters to denote the type of the value being used in a prepared statement or query:

queryExecute(
  "select quantity, item from cupboard where item_id = :itemID"
  { itemID : { value : arguments.itemID, cfsqltype : "cf_sql_numeric" } }
);

In BoxLang, you'll need to replace cfsqltype with just sqltype. In addition, we'd prefer to see all usage of the cf_sql_/CF_SQL prefixes stripped:

queryExecute(
  "select quantity, item from cupboard where item_id = :itemID"
  { itemID : { value : arguments.itemID, sqltype : "numeric" } }
);

Here's a full breakdown of the various syntaxes:

• sqltype:"numeric" - The preferred syntax.

• cfsqltype:"cf_sql_numeric" - will throw an error in BoxLang core. In CFML syntax files, is transpiled to sqltype:"cf_sql_numeric".

• sqltype:"cf_sql_numeric" - is silently treated as sqltype:"numeric".

BlockFactor Query Option

The blockfactor query option in Adobe CF and Lucee Server is used to set a custom batch size when selecting large numbers of rows:

queryExecute( "Select * FROM myBigTable", {}, { blockfactor : 100 } );

In BoxLang, this is renamed to fetchSize:

queryExecute( "Select * FROM myBigTable", {}, { fetchSize : 100 } );

You can use the blockfactor nomenclature by installing the bx-compat-cfml module.

Date and Time Handling

Legacy CFML engines use the java.util.Date class as a backing object for their date and time handling. BoxLang uses the java.time classes, more specifically the ZonedDateTime class as the backing date object. This offers greater precision and localization/internationalization capabilities than the Timezone-unaware java.util classes can provide. If interacting with Java classes which use java.util.Date, Boxlang will automatically coerce the runtime date object to the correct type. In some circumstances you may need to retrieve the object manually. You may do so with the toLegacyDate( myDate ) method which will return the legacy Date class.

Date Modification and Addition Operations

In BoxLang dates operation and comparison precision is to the millisecond level, compared to the legacy behavior of precision to the second. With the CFML compat module, date comparison functions will revert to using second-level precision.

In addition rounding behavior of date addition may be different than other CFML engines, but in a good way. The following code, when executed in non-BoxLang engines:

epochDate = parseDateTime( "1970-01-01T00:00:00.000Z" );
updatedDate = dateAdd( "s", 500/1000, epochDate );
result = dateTimeFormat( updatedDate, "yyyy-MM-dd'T'HH:mm:ss.SSSX", "UTC" );

will produce an incorrect rounding to the minute ( e.g. 1970-01-01T00:01:00.000Z ). In BoxLang, the addition of ½ second produces a correctly rounded result to the second of 1970-01-01T00:00:01.000Z