1 of 2

How do they work?

Interceptors are CFCs that extend the ColdBox Interceptor class (coldbox.system.Interceptor), implement a configuration method called configure(), and then contain methods for the events it will listen for. All interceptors are treated as singletons in your application, so make sure they are thread safe and var scoped.

/**
* My Interceptor
*/
component extends="coldbox.system.Interceptor"{

    function configure(){}

    function preProcess( event, interceptData, buffer, rc, prc ){}
}

Info You can also remove the inheritance from the CFC (preferred method) and WireBox will extend the coldbox.system.Interceptor for you using Virtual Inheritance.

You can use CommandBox to create interceptors as well:

coldbox create interceptor help

Registration

Interceptors can be registered in your Coldbox.cfc configuration file using the interceptors struct, or they can be registered manually via the system's interceptor service.

In ColdBox.cfc:

// Interceptors registration
interceptors = [
    {
        class   = "cfc.path", //by default this should be interceptors.yourcfcname  
        name    = "unique name/wirebox ID",
        properties = {
            // configuration
        }
    }
];

Registered manually:

controller.getInterceptorService().registerInterceptor( interceptorClass="cfc.path" );

The `configure()` Method

The interceptor has one important method that you can use for configuration called configure(). This method will be called right after the interceptor gets created and injected with your interceptor properties.

Info These properties are local to the interceptor only!

As you can see on the diagram, the interceptor class is part of the ColdBox framework super type family, and thus inheriting the functionality of the framework.

Conventions

By convention, any interceptor CFC must create a method with the same name as the event they want to listen to. This method has a return type of boolean and receives 3 arguments. So let's explore their rules.

boolean function {point}( event, interceptData, buffer, rc, prc );

Arguments

event which is the request context object
interceptData which is a structure of data that the broadcaster sends
buffer which is a request buffer object you can use to elegantly produce content that is outputted to the user's screen
rc reference to the request collection struct
prc reference to the private request collection struct

Return type

The intercepting method returns boolean or void. If boolean then it means something:

True means break the chain of execution, so no other interceptors in the chain will fire.
False or void continue execution

component extends="coldbox.system.Interceptor"{

    function configure(){}

    boolean function afterConfigurationLoad(event,interceptData,buffer){
        if( getProperty('interceptorCompleted') eq false){
            parseAndSet();    
            setProperty('interceptorCompleted',true);
        }

        return false;
    }
}

Also remember that all interceptors are created by WireBox, so you can use dependency injection, configuration binder's, and even AOP on interceptor objects. Here is a more complex sample:

HTTP Security Example:

/**
* Intercepts with HTTP Basic Authentication
*/
component {

    // Security Service
    property name="securityService" inject="id:SecurityService";

    void function configure(){
        if( !propertyExists("enabled") ){
            setProperty("enabled", true );
        } 
    }

    void function preProcess(event,struct interceptData, buffer){

        // verify turned on
        if( !getProperty("enabled") ){ return; }

        // Verify Incoming Headers to see if we are authorizing already or we are already Authorized
        if( !securityService.isLoggedIn() OR len( event.getHTTPHeader("Authorization","") ) ){

            // Verify incoming authorization
            var credentials = event.getHTTPBasicCredentials();
            if( securityService.authorize(credentials.username, credentials.password) ){
                // we are secured woot woot!
                return;
            };

            // Not secure!
            event.setHTTPHeader(name="WWW-Authenticate",value="basic realm=""Please enter your username and password for our Cool App!""");

            // secured content data and skip event execution
            event.renderData(data="<h1>Unathorized Access<p>Content Requires Authentication</p>",statusCode="401",statusText="Unauthorized")
                .noExecution();
        }    

    }    

}

Conventions

boolean function {point}( event, interceptData, buffer, rc, prc );

Arguments

event which is the request context object
interceptData which is a structure of data that the broadcaster sends
buffer which is a request buffer object you can use to elegantly produce content that is outputted to the user's screen
rc reference to the request collection struct
prc reference to the private request collection struct

Return type

The intercepting method returns boolean or void. If boolean then it means something:

True means break the chain of execution, so no other interceptors in the chain will fire.
False or void continue execution

component extends="coldbox.system.Interceptor"{

    function configure(){}

    boolean function afterConfigurationLoad(event,interceptData,buffer){
        if( getProperty('interceptorCompleted') eq false){
            parseAndSet();    
            setProperty('interceptorCompleted',true);
        }

        return false;
    }
}

Also remember that all interceptors are created by WireBox, so you can use dependency injection, configuration binder's, and even AOP on interceptor objects. Here is a more complex sample:

HTTP Security Example:

/**
* Intercepts with HTTP Basic Authentication
*/
component {

    // Security Service
    property name="securityService" inject="id:SecurityService";

    void function configure(){
        if( !propertyExists("enabled") ){
            setProperty("enabled", true );
        } 
    }

    void function preProcess(event,struct interceptData, buffer){

        // verify turned on
        if( !getProperty("enabled") ){ return; }

        // Verify Incoming Headers to see if we are authorizing already or we are already Authorized
        if( !securityService.isLoggedIn() OR len( event.getHTTPHeader("Authorization","") ) ){

            // Verify incoming authorization
            var credentials = event.getHTTPBasicCredentials();
            if( securityService.authorize(credentials.username, credentials.password) ){
                // we are secured woot woot!
                return;
            };

            // Not secure!
            event.setHTTPHeader(name="WWW-Authenticate",value="basic realm=""Please enter your username and password for our Cool App!""");

            // secured content data and skip event execution
            event.renderData(data="<h1>Unathorized Access<p>Content Requires Authentication</p>",statusCode="401",statusText="Unauthorized")
                .noExecution();
        }    

    }    

}

How do they work?

/**
* My Interceptor
*/
component extends="coldbox.system.Interceptor"{

    function configure(){}

    function preProcess( event, interceptData, buffer, rc, prc ){}
}

Info You can also remove the inheritance from the CFC (preferred method) and WireBox will extend the coldbox.system.Interceptor for you using Virtual Inheritance.

You can use CommandBox to create interceptors as well:

coldbox create interceptor help

Registration

Interceptors can be registered in your Coldbox.cfc configuration file using the interceptors struct, or they can be registered manually via the system's interceptor service.

In ColdBox.cfc:

// Interceptors registration
interceptors = [
    {
        class   = "cfc.path", //by default this should be interceptors.yourcfcname  
        name    = "unique name/wirebox ID",
        properties = {
            // configuration
        }
    }
];

Registered manually:

controller.getInterceptorService().registerInterceptor( interceptorClass="cfc.path" );

The `configure()` Method

Info These properties are local to the interceptor only!

As you can see on the diagram, the interceptor class is part of the ColdBox framework super type family, and thus inheriting the functionality of the framework.

How do they work?

Registration

The configure() Method

Conventions

Arguments

Return type

Conventions

Arguments

Return type

How do they work?

Registration

The configure() Method

The `configure()` Method

The `configure()` Method