Using ImgIX For On-Demand Image Processing At Web Scale In ColdFusion Applications

component
	output = false
	hint = "I provide methods for creating signed web proxy URLs for the ImgIX API."
	{

	/**
	* I generate signed web proxy URLs for a source represented by the source domain
	* and secret token.
	*
	* @newDomain I am the source domain (including the protocol) for the web proxy.
	* @newToken I am the secret token associated with the source.
	* @output false
	*/
	public any function init(
		required string newDomain,
		required string newToken
		) {

		// Store the properties for all subsequent URLs.
		domain = newDomain;
		token = newToken;

		return( this );

	}


	// ---
	// PUBLIC METHODS.
	// ---


	/**
	* I build the ImgIX web proxy URL based on the given target URL and API commands.
	*
	* @targetUrl I am the URL that ImgIX will request as the "origin" URL.
	* @commands I am a struct OR a string of key-value API commands.
	*/
	public string function getWebProxyUrl(
		required string targetUrl,
		required any commands
		) {

		var encodedTargetUrl = urlEncodeComponent( targetUrl );

		var normalizedCommands = normalizeCommands( commands );

		var stringToSign = "#token#/#encodedTargetUrl#?#normalizedCommands#";

		var signature = lcase( hash( stringToSign ) );

		return( domain & "/" & encodedTargetUrl & "?" & normalizedCommands & "&s=" & signature );

	}


	// ---
	// PRIVATE METHODS.
	// ---


	/**
	* I normalize the ImgIX API commands as a string. If the input is a string, it is
	* simply returned. If it is a struct, it is flattened into an amphersand delimited list.
	*
	* @commands I am a string or struct of name-value pairs.
	* @output false
	*/
	private string function normalizeCommands( required any commands ) {

		if ( isSimpleValue( commands ) ) {

			return( commands );

		}

		if ( ! isStruct( commands ) ) {

			throw(
				type = "ImgIX.InvalidArgument",
				message = "The commands must either be a string or a struct."
			);

		}

		var pairs = [];

		for ( var command in commands ) {

			var name = lcase( command );
			var value = urlEncodeComponent( commands[ command ] );

			arrayAppend( pairs, "#name#=#value#" );

		}

		return( arrayToList( pairs, "&" ) );

	}


	/**
	* I encode the given URL for use as the "path" portion of the ImgIX web proxy url.
	*
	* @targetUrl I am the full URL (including protocol, excluding ImgIX commands).
	* @output false
	*/
	private string function urlEncodeComponent( required string targetUrl ) {

		targetUrl = urlEncodedFormat( targetUrl, "utf-8" );

		// At this point, we have a key that has been encoded too aggressively by
		// ColdFusion. Now, we have to go through and un-escape the characters that
		// will mess up the signature.

		// The following are "unreserved" characters in the RFC 3986 spec for Uniform
		// Resource Identifiers (URIs) - http://tools.ietf.org/html/rfc3986#section-2.3
		targetUrl = replace( targetUrl, "%2E", ".", "all" );
		targetUrl = replace( targetUrl, "%2D", "-", "all" );
		targetUrl = replace( targetUrl, "%5F", "_", "all" );
		targetUrl = replace( targetUrl, "%7E", "~", "all" );

		// Technically, the "/" characters can be encoded and will work. However, I just
		// don't like the way the URL looks with nothing but escaped path markers. This
		// one is just for personal preference.
		targetUrl = replace( targetUrl, "%2F", "/", "all" );

		// This one isn't necessary; but, I think it makes for a more attractive URL.
		targetUrl = replace( targetUrl, "%20", "+", "all" );

		return( targetUrl );

	}

}

<cfscript>

	// This reads in a JSON configuration file that contains my secure token (so that I
	// don't have to have the credentials in the repository). This file contains a hash:
	// --
	// { "domain": "http://my_source_domain", "token": "my_source_token" }
	// --
	config = deserializeJson( fileRead( expandPath( "./config.json" ) ) );

	// Create an instance of our ImgIX Web Proxy component.
	imgIx = new lib.ImgIXWebProxy( config.domain, config.token );

	// This is the remote URL that we'll be piping through the ImgIX image processing.
	remoteUrl = "http://www.bennadel.com/images/header/kitt_hodsden_2.jpg";


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //


	// Show the original with some text indicating the original nature of it.
	proxyUrl = imgIx.getWebProxyUrl(
		remoteUrl,
		{
			txt = "( Original Photo )",
			txtsize = 62,
			txtclr = "FFFFFF",
			txtalign = "middle,center",
			txtfont = "Futura Condensed Medium",
			txtshad = 15
		}
	);

	writeOutput( "<img src='#proxyUrl#' /><br /><br />" );


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //


	// Add some mono-chromatic coloring.
	proxyUrl = imgIx.getWebProxyUrl(
		remoteUrl,
		{
			mono = "FF33CC"
		}
	);

	writeOutput( "<img src='#proxyUrl#' /><br /><br />" );


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //


	// Add some pixelation (16px) and fix to a max-width of 300px.
	proxyUrl = imgIx.getWebProxyUrl(
		remoteUrl,
		{
			px = 16,
			w = 300
		}
	);

	writeOutput( "<img src='#proxyUrl#' /><br /><br />" );


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //


	// Flip the image and add some "half-tone" (what ever that is). Notice that this
	// time, I'm using a string of commands instead of a hash. I htink we can all agree
	// that the struct-form is much more readable.
	proxyUrl = imgIx.getWebProxyUrl(
		remoteUrl,
		"flip=h&htn=4"
	);

	writeOutput( "<img src='#proxyUrl#' /><br /><br />" );

</cfscript>