Working with Mark Mazelin over the better part of a year, we’ve created a developer-friendly set of components with a simple API. We’ve made it easy to create new gateways on top of our core and most importantly, we’ve battle-tested this code processing over $1 Million USD using these components.

Whether you are an OO nut or a spaghetti coder, our simple interface makes processing credit cards and e-checks (EFTs) easy like:

<cfset config = {path = "bogus.gateway", username = "user", password = "foo" } />
<cfset core = createObject("component", "cfpayment.api.core").init(config) />
<cfset gateway = core.getGateway() />

<cfset cc = core.createCreditCard() />
<cfset cc.setFirstName("Joe").setLastName("Blow").setAddress("888 Nowhere Lane").setPostalCode("94103") />
<cfset money = core.createMoney(5000) />< !-- $50.00 in cents -->

<cfset response = gateway.purchase(money, creditcard) />

<cfdump var="#response.getParsedResult()#" />

I’ve put more than five years of e-commerce experience into the design and reliability of this library and Mark has helped me make it better every step of the way.

I’ll be at cf.Objective() in Minneapolis through Sunday so please don’t hesitate to come find me and talk shop.

If you find bounce signatures not included in the XML, please post them to the forums on RIAforge for future inclusion.

Grab it via subversion from riaforge.

I have a really long draft in Wordpress that I’ve been waiting for the time to turn into a series on REST. With lots of contributions from Kevin Miller (who donated a series of data transformation functions to this release of PowerNap), it should be a helpful nuts and bolts series for anyone who wants to get started with REST services but hasn’t had the chance to look into it.

In the mean time, download 0.9 and join the CF REST Google group.

I’ve already received a report of someone building their own gateway (Authorize.net) based on cfpayment so there’s nothing to stop you from doing the same for your project!

Also, we added in the ability to chain together set commands on the model objects to allow something like the following:

cc.setFirstName("John").setLastName("Doe").setAccount("5454545454545454").setYear("10").setMonth("09")

We’re aiming for an early January 1.0 after we each put our gateways into production for a few weeks to be sure we’ve ironed out any potential issues.

Download the latest and give it a shot. Questions? Feedback? Hit me up here…

/test.cfm?id=foo&id=bar&id=snafu

or form with set of checkboxes:

<input type="checkbox" name="id" value="1000" /> 1000<br />
<input type="checkbox" name="id" value="1001" /> 1001<br />
<input type="checkbox" name="id" value="1002" /> 1002<br />

can be transformed using request.getParameterValues() into arrays because we pass multiple values for the same variable in the request. PHP also has auto-conversion into arrays. ColdFusion has no such thingy see update below*.

In working with my Javascript contractor this morning on some AJAX routines, I took a few minutes to try and emulate the behavior to support receiving data from Ext JS components. I came up with the following UDF which works with both GET and POST:

<cffunction name="getVarAsArray">
	<cfargument name="field" type="string" required="true" />

	<cfset var arr = arrayNew(1) />
	<cfset var data = "" />

	<cfif CGI.request_method EQ "GET">
		<cfset data = CGI.query_string />
	<cfelse>
		<cfset data = toString(getHTTPRequestData().content) />
	</cfif>

	<cfloop list="#data#" delimiters="&" index="item">
		<cfif listFirst(item, "=") EQ arguments.field>
			<cfset arrayAppend(arr, listLast(item, "=")) />
		</cfif>
	</cfloop>

	<cfreturn arr />
</cffunction>

If you were to run the first request described above and run getVarAsArray(”id”), you would get the following array back:

I don’t think getVarAsArray is a very catchy name nor incredibly descriptive of what it does. Can someone suggest a better name?

Barney is a Smarty Pants *UPDATE*

I knew, since ColdFusion MX is based on Java, that there must be a way to get at the Java getParameterValues() but I didn’t have the patience to track it down and I’m not a big user of getPageContext(). As Barney explains in his comment below, you can get at it with this simple line of code eliminating the need for the above UDF:

array = getPageContext().getRequest().getParameterValues('id')

The one difference is that this approach will throw an error if the variable ID doesn’t exist whereas my UDF will return an empty array. It’s easy enough to fix by wrapping with a structKeyExists() to check for the variable first. In most cases you’ll be expecting a specific variable so it shouldn’t be a problem.

Thanks to Barney for teaching me something new - cheers!

I’ve had this post in my drafts queue for a long time but this thread about escaping SQL reserved keywords on the Transfer group prompted me to finish my thoughts:

Most applications have a User table, if those users are organized then there may be a Group table, and if there’s any kind of e-commerce going on then it might have an Order table. How would you name these so as not to use reserved words?

I learned Hungarian Notation from a Sybase database admin named Rick when I first started webdeving back in 1994. He worked at Prudential and I had never touched a database so when we started doing some more serious work, he told me about the Hungarian Notation they used at Prudential for naming columns:

vchCompanyName = company name, varchar
intEmployeeCount = employee count, integer

This seems innocuous enough. Since I didn’t control the database but needed to code against it, I accepted this as Gospel. It was my first interaction with a real database, one that ran on scary Sun Ultra 5 servers at some colo facility on the East Coast, so who was I to disagree? Honestly I was more concerned with getting things done than arguing over a field name. But now I have more time to argue.

Arguments against Hungarian Notation

Convention over configuration is all the rage today. Ruby on Rails programmers claim this to be part of the secret sauce that empowers them to quickly build new services like Basecamp, Blinksale and Twitter. Since many opponents of HN argue that a compiler is your sanity check, it’s especially relevant for untyped languages like PHP and ColdFusion that don’t have such a fallback. HN subtly communicates information to the developer but it can also be programmatically leveraged as I will demonstrate later.

Another common argument against HN is that the editing environment can give you on-demand details of data types or flag incompatible operations based on introspection. Most of the developers I know have migrated to Eclipse + CFEclipse for ColdFusion. While for Java or C the IDE can give you a wealth of information about the code, that support is not available to untyped or dynamically generated languages like ColdFusion which don’t declare variable types.

Perhaps my favorite argument is that HN is not portable since two companies may not implement it in exactly the same way; therefore having no standard is preferable. But this makes no sense! There are changes anytime we switch companies or projects! We also need to learn where the bathrooms are located and the names of our new co-workers; are these critics really suggesting that developers are unable to adapt?

Lastly I have read that using HN locks the code into a particular data type making data model changes more difficult down the road. This might have been true before the advent of search and replace but with today’s IDEs, you can trigger a very accurate system-wide replacement with Regular Expressions in seconds. With the exception of some very large or distributed projects, I simply can’t believe this to be the case any longer. In fact, I would argue that Hungarian Notation makes these kinds of system-wide changes easier because the field and variable names have more specific and unique names making a RegExp more precise (this is the same reason why I never name an iterator variable “i” or “j” - I always use “ii” or “jj” so you can search and/or replace it).

The old arguments against Hungarian Notation just simply don’t make sense in today’s web development environment. Thus, I present to you my top reasons to love Hungarian Notation!

Four Reasons to love Hungarian Notation

1. With no variable typing, IDE introspection or language compiler to fall back upon for PHP, ColdFusion and other web languages, HN subtly communicates valuable information to the developer that helps prevent and identify mistakes.
2. The greatest cost of software is actually the maintenance, assuming you’re not some pump-n-dump consultant who rides from one gig to the next. Hungarian Notation significantly improves maintainability because a developer can return to code six months or six years later and have an immediate handle on what is going on in the code without knowing the intricacies of the data model. These prefixes act like hints, continually reminding us of where we are and what we’re dealing with. It’s built-in documentation that you never have to sit down to write!
3. Prefixes can allow you to catch special situations. I use Transfer ORM against PostgreSQL. One of the great things about postgres are the extensive data types it supports which include things like GIS “points” and UUIDs and timestamp-differential “Intervals”. Problem is, Transfer would throw errors when I accessed an interval column but Hungarian Notation came to the rescue. Since I prefix all interval columns with “inv”, I modified TransferSelecter.cfc starting with:

   default:
   	null = null & "text";

   to handle this special case:

   default:
   if (left(arguments.column, 3) EQ "inv")
   {
   	null = null & "interval";
   }
   else
   {
   	null = null & "text";
   }

   Not the ideal fix but the prefix saved my bacon with a minimal amount of work when I was in the middle of writing my application.

4. No collision with reserved words in SQL or any other language. Consider an e-commerce site: it would surely have an “Order” table and perhaps a “Group” table, both of which are reserved keywords in SQL. You can work around that by making them plural or giving them a more descriptive name like “SiteOrders” but consistently prefixed names like tblLookupOrder will never conflict with reserved words.

Ghidinelli (Hungarian) Notation

There are many interpretations of Hungarian Notation out there but I will share the prefixes and naming conventions I use to paint a picture of a system I have used alone and in teams for over a decade. I don’t claim this to be the way, but rather a way.

My first personal rule is that all prefixes should be three characters. There are two reasons for this - with three characters you will surely have enough combinations to adequately abbreviate the object you are trying to describe. Secondly, it allows you to programmatically check the prefix since it will always be three characters long (see the Transfer example above). Beyond that, I use a combination of what I learned back in 1994 and what sounded good to me as time went by:

Table Naming

• tblLookup* - a normalized lookup table to hold an idea. ex: tblLookupUser, tblLookupOrder.
• tblMap* - a mapping table between typically two lookup tables to describe a relationship. ex: tblMapUserOrders or I have seen others use tblMapUsersToOrders.
• vue* - a view prefix, usually using the same Lookup and Map pieces. ex: vueLookupAttendee.

Column Naming

• boo - boolean
• int - integer
• snt - small integer (int[2])
• tnt - tiny integer (int[1])
• chr - character
• uid - character(35) used for storage of UUIDs which I use as primary keys in many instances.
• vch - varying character
• txt - text or unlimited varying character (depending on platform)
• inv - interval
• num - numeric
• dec - decimal
• mny - money, which may actually be decimal but better describes it as currency
• xml - XML storage for databases that support it like PostgreSQL, Oracle…
• dte - date
• dtm - datetime/timestamp
• rad - radians (may be represented as decimal)
• net - IP address

Application Variable Naming

• arr - array
• str - struct (in coldfusion, object in javascript, etc)
• obj - an instance of a coldfusion component
• int - integer/numeric
• qry - query

I’ve become less strict about the variable naming rules in the past years mostly because with CFCs, I keep my methods short enough to be clear. I may be more strict in using them in the view layer where non-programmers or other users might need to do some work since we can share a key of “what is what”.

Conclusion

At the end of the day, Hungarian Notation does not cost the developer anything but may add value in a variety of circumstances, specifically consistency, maintainability and flexibility. There may be components of these conventions that people don’t like, but they clearly do solve the items laid out above.

These are guidelines I generally use but freely break as needed. I tend to be very strict in the data layer and less strict in the display layer. I’ve been writing my current application now for five years and I can’t imagine wading into some of my old code without these hints - it would take at least twice as long to make simple changes. This is the key reason why I continue to use Hungarian Notation!

<cfset config = {path = "braintree.braintree", username = "demo", password = "demo" } />
<cfset cfpayment = createObject("component", "cfpayment.api.core").init(config) />
<cfset gateway = cfpayment.getGateway() />
// create a money object to hold the amount in cents
<cfset money = cfpayment.createMoney(5000, "USD") />
// create an account to charge
<cfset account = cfpayment.createCreditCard() />
<cfset account.setAccount(4111111111111111) />
<cfset account.setMonth(10) />
<cfset account.setYear(10) />
<cfset account.setFirstName("John") />
<cfset account.setLastName("Doe") />
// authorize the card
<cfset response = gw.authorize(money = money, account = creditcard) />
// flag the authorization for settlement into your bank account
<cfset response = gw.capture(money = money, transactionid = response.getTransactionID()) />
// changed my mind, let's void it
<cfset response = gw.void(transactionid = response.getTransactionID()) />

Heard of PCI DSS? You can mitigate or avoid it altogether by using a remote storage system like Braintree’s Secure Vault:

// create a token
<cfset token = cfpayment.createToken(createUUID()) />
<cfset options = { store = token.getID() } />
// authorize and put the data into the vault
<cfset response = gw.authorize(money = money, account = account, options = options) />
// come back later and use that token to charge the card
<cfset response = gw.purchase(money = money, account = token) />
// changed my mind, delete it from the vault
<cfset response = gw.unstore(account = token) />

Don’t use Braintree? That’s OK, as of today, you could just as easily initialize the Core API to use iTransact or Skipjack without any change in your consumer code.

We’re working to add more payment gateways. The best source of these will come from people who have written integrations already or need to write one and want to benefit from the infrastructure of a community-supported and planned API that gives them flexibility in choosing their gateways and merchant accounts over the long road.

The goal is to let developers plug in payment processing without having to understand the intricacies of each gateway. Instead, we’ll provide a clean outward facing API for each payment gateway. Mark Mazelin has already been a great help in putting together some samples and documentation and we’re knocking ideas back and forth. We’ll be leveraging a lot of the thinking and work done by the ActiveMerchant project since they did a great job. Hopefully we’ll be collaborating with the cfCommerce team who is building an open source commerce platform for ColdFusion.

We should have support for five or six gateways in our first release which will be soon because both Mark and I need this in the short-term. If you have working code for a payment gateway, PLEASE contribute it. We’ll attribute it to you and you’ll be famous! If you’re interested in developing it yourself, even better! Please contact me and let me know. More to come…

--------------------- IMAP Begin ------------------------

--------------- IMAP End -----------------

Only about 50x the amount of these entries. The reason? The Logwatch script for IMAP that ships with RHEL/CentOS is totally broken. Everything comes back as one blob of “Unmatched Entries”. Not high on my priority list, I was forced to restore sanity to my life by hacking out a fixed version. This doesn’t do everything, but set detail level to 5 (Med) and you’ll get the basics in nice, tabular output:

--------------------- Courier IMAP Begin ------------------------

[IMAPd] Login stats:
====================
User | Logins
-------------------------- | -----
xxxxxxxxxxxxxxxxxxx | 104
xxxxxxxxxxxxxxx | 59
xxxxxxxxxxxxxxxxxx | 44
---------------------------------
207

You can see some of the stats are logged separately yet. Note that the conf file has a DNS lookup option to turn on/off reverse lookups in the logs. You can get the script and configuration file from my software page now.