Associations in Wheels allow you to define the relationships between your database tables. After configuring these relationships, doing pesky table joins becomes a trivial task. And like all other ORM functions in Wheels, this is done without writing a single line of SQL.
In order to set up associations, you only need to remember 3 simple methods. Considering that the human brain only reliably remembers up to 7 items, we've left you with a lot of extra space. You're welcome. :)
The association methods should always be called in the
init() method of a model that relates to another model within your application.
If your database table contains a field that is a foreign key to another table, then this is where to use the belongsTo() function.
If we had a comments table that contains a foreign key to the posts table called
postid, then we would have this
init() method within our comment model:
<cfcomponent extends="Model"> <cffunction name="init"> <cfset belongsTo("post")> </cffunction> </cfcomponent>
On the other side of the relationship are the "has" functions. As you may have astutely guessed, these functions should be used according to the nature of the model relationship.
At this time, you need to be a little eccentric and talk to yourself. Your association should make sense in plain English language.
So let's consider the
post / comment relationship mentioned above for
belongsTo(). If we were to talk to ourselves, we would say, "A post has many comments." And that's how you should construct your post model:
<cfcomponent extends="Model"> <cffunction name="init"> <cfset hasMany("comments")> </cffunction> </cfcomponent>
You may be a little concerned because our model is called
comment and not
comments. No need to worry: Wheels understands the need for the plural in conjunction with the
And don't worry about those pesky words in the English language that aren't pluralized by just adding an "s" to the end. Wheels is smart enough to know that words like "deer" and "children" are the plurals of "deer" and "child," respectively.
The hasOne() association is not used as often as the hasMany() association, but it has its use cases. The most common use case is when you have a large table that you have broken down into two or more smaller tables (a.k.a. denormalization) for performance reasons or otherwise.
Let's consider an association between
profile. A lot of websites allow you to enter required info such as name and email but also allow you to add optional information such as age, salary, and so on. These can of course be stored in the same table. But given the fact that so much information is optional, it would make sense to have the required info in a
users table and the optional info in a
profiles table. This gives us a
hasOne() relationship between these two models: "A user has one profile."
In this case, our
profile model would look like this:
<cfcomponent extends="Model"> <cffunction name="init"> <cfset belongsTo("user")> </cffunction> </cfcomponent>
And our user model would look like this:
<cfcomponent extends="Model"> <cffunction name="init"> <cfset hasOne("profile")> </cffunction> </cfcomponent>
As you can see, you do not pluralize "profile" in this case because there is only one profile.
By the way, as you can see above, the association goes both ways, i.e. a
user hasOne() profile, and a
profile belongsTo() a
user. Generally speaking, all associations should be set up this way. This will give you the fullest API to work with in terms of the methods and arguments that Wheels makes available for you.
However, this is not a definite requirement. Wheels associations are completely independent of one another, so it's perfectly OK to setup a hasMany() association without specifying the related belongsTo() association.
A dependency is when an associated model relies on the existence of its parent. In example above, a
profile is dependent on a
user. When you delete the
user, you would usually want to delete the
profile as well.
Wheels makes this easy for you. When setting up your association, simply add the argument
dependent with one of the following values, and Wheels will automatically deal with the dependency.
<!--- Instantiates the `profile` model and calls its `delete()` method ---> <cfset hasOne(name="profile", dependent="delete")> <!--- Quickly deletes the `profile` without instantiating it ---> <cfset hasOne(name="profile", dependent="deleteAll")> <!--- Sets the `userId` of the profile to `NULL` ---> <cfset hasOne(name="profile", dependent="nullify")>
You can create dependencies on
hasMany() associations, but not
It's possible for a model to be associated to itself. Take a look at the below setup where an employee belongs to a manager for example:
// In Employee.cfc belongsTo(name="manager", modelName="employee", foreignKey="managerId");
Both the manager and employee are stored in the same
employees table and share the same
When you use this association in your code, the
employees table will be joined to itself using the
managerid column. CFWheels will handle the aliasing of the (otherwise duplicated) table names. It does this by using the pluralized version of the name you gave the association (in other words "managers" in this case).
This is important to remember because if you, for example, want to select the manager's name, you will have to do so manually (CFWheels won't do this for you, like it does with normal associations) using the
Here's an example of how to select both the name of the employee and their manager:
model("employee").findAll(include="manager", select="employees.name, managers.name AS managerName")
Know Your Joins
Because the default
inner, employees without a manager assigned to them will not be returned in the
findAll() call above. To return all rows you can set
Like everything else in Wheels, we strongly recommend a default naming convention for foreign key columns in your database tables.
In this case, the convention is to use the singular name of the related table with
id appended to the end. So to link up our table to the
employees table, the foreign key column should be named
Wheels offers a way to configure your models to break this naming convention, however. This is done by using the
foreignKey argument in your models'
Let's pretend that you have a relationship between
post, but you didn't use the naming convention and instead called the column
post_id. (You just can't seem to let go of the underscores, can you?)
init() method would then need to look like this:
<cfcomponent extends="Model"> <cffunction name="init"> <cfset belongsTo(name="author", foreignKey="post_id")> </cffunction> </cfcomponent>
You can keep your underscores if it's your preference or if it's required of your application.
Now that we have our associations set up, let's use them to get some data into our applications.
There are a couple ways to join data via associations, which we'll go over now.
Here's what that call would look like:
<cfset posts = model("post").findAll(include="author")>
It's that simple. Wheels will then join the
authors table automatically so that you can use that data along with the data from
Note that if you switch the above statement around like this:
<cfset authors = model("author").findAll(include="posts")>
Then you would need to specify "post" in its plural form, "posts." If you're thinking about when to use the singular form and when to use the plural form, just use the one that seems most natural.
If you look at the two examples above, you'll see that in example #1, you're asking for all posts including each post's author (hence the singular "author"). In example #2, you're asking for all authors and all of the posts written by each author (hence the plural "posts").
You're not limited to specifying just one association in the
include argument. You can for example return data for
authors, posts, and
bios in one call like this:
<cfset authorsPostsAndComments = model("author").findAll(include="posts,bio")>
To include several tables, simply delimit the names of the models with a comma. All models should contain related associations, or else you'll get a mountain of repeated data back.
When you need to include tables more than one step away in a chain of joins, you will need to start using parenthesis. Look at the following example:
<cfset commentsPostsAndAuthors = model("comment").findAll(include="post(author)")>
The use of parentheses above tells Wheels to look for an association named
author on the
post model instead of on the
comment model. (Looking at the
comment model is the default behavior when not using parenthesis.)
There is a minor caveat to this approach. If you have a column in both associated tables with the same name, Wheels will pick just one to represent that column.
In order to include both columns, you can override this behavior with the
select argument in the finder functions.
For example, if we had a column named
name in both your
authors tables, then you could use the
select argument like so:
<cfset post = model("post").findAll( select="posts.name, authors.id, authors.post_id, authors.name AS authorname", include="author" ) >
You would need to hard-code all column names that you need in that case, which does remove some of the simplicity. There are always trade-offs!
A cool feature of Wheels is the ability to use dynamic shortcut methods to work with the models you have set up associations for. By dynamic, we mean that the name of the method depends on what name you have given the association when you set it up. By shortcut, we mean that the method usually delegates the actual processing to another Wheels method but gives you, the developer, an easier way to achieve the task (and makes your code more readable in the process).
As usual, this will make more sense when put into the context of an example. So let's do that right now.
Let's say that you tell Wheels through a hasMany() call that a
post has many
comments. What happens then is that Wheels will enrich the post model by adding a bunch of useful methods related to this association.
If you wanted to get all
comments that have been submitted for a
post, you can now call
post.comments(). In the background, Wheels will delegate this to a findAll() call with the
where argument set to
Here are all the methods that are added for the three possible association types.
Methods Added by hasMany
Given that you have told Wheels that a
post has many
comments through a hasMany() call, here are the methods that will be made available to you on the
XXX below with the name of the associated model (i.e.
comments in the case of the example that we're using here).
Returns all comments where the foreign key matches the post's primary key value. Similar to calling
Adds a comment to the post association by setting its foreign key to the post's primary key value. Similar to calling
Removes a comment from the post association by setting its foreign key value to
NULL. Similar to calling
Deletes the associated comment from the database table. Similar to calling
Removes all comments from the post association by setting their foreign key values to
NULL. Similar to calling
Deletes the associated comments from the database table. Similar to calling
Returns the number of associated comments. Similar to calling
Creates a new comment object. Similar to calling
Creates a new comment object and saves it to the database. Similar to calling
Returns true if the post has any comments associated with it. Similar to calling
Returns one of the associated comments. Similar to calling
Methods Added by hasOne
Given that you have told Wheels that an
author has one
profile through a hasOne() call, here are the methods that will be made available to you on the
Returns the profile where the foreign key matches the author's primary key value. Similar to calling model("profile").findOne(where="authorid=#author.id#").
Sets the profile to be associated with the author by setting its foreign key to the author's primary key value. You can pass in either a profile object or the primary key value of a profile object to this method. Similar to calling model("profile").updateByKey(key=profile.id, authorid=author.id).
Removes the profile from the author association by setting its foreign key to NULL. Similar to calling model("profile").updateOne(where="authorid=#author.id#", authorid="").
Deletes the associated profile from the database table. Similar to calling model("profile").deleteOne(where="authorid=#author.id#")
Creates a new profile object. Similar to calling model("profile").new(authorid=author.id).
Creates a new profile object and saves it to the database. Similar to calling model("profile").create(authorid=author.id).
Returns true if the author has an associated profile. Similar to calling model("profile").exists(where="authorid=#author.id#").
Methods Added by belongsTo
The belongsTo() association adds a couple of methods to your model as well.
Given that you have told Wheels that a
comment belongs to a
post through a belongsTo() call, here are the methods that will be made available to you on the
Returns the post where the primary key matches the comment's foreign key value. Similar to calling model("post").findByKey(comment.postid).
Returns true if the comment has a post associated with it. Similar to calling model("post").exists(comment.postid).
One general rule for all of the methods above is that you can always supply any argument that is accepted by the method that the processing is delegated to. This means that you can, for example, call
post.comments(order="createdAt DESC"), and the
order argument will be passed along to
Another rule is that whenever a method accepts an object as its first argument, you also have the option of supplying the primary key value instead. This means that
author.setProfile(profile) will perform the same task as
author.setProfile(1). (Of course, we're assuming that the
profile object in this example has a primary key value of
You may be concerned that using a dynamic finder adds yet another database call to your application.
If it makes you feel any better, all calls in your Wheels request that generate the same SQL queries will be cached for that request. No need to worry about the performance implications of making multiple calls to the same
author.posts() call in the scenario above, for example.
You can also pass arguments to dynamic shortcut methods where applicable. For example, with the
XXX() method, perhaps we'd want to limit a
post's comment listing to just ones created today. We can pass a
where argument similar to what is passed to the
findAll() function that powers
XXX() behind the scenes.
<cfset today = DateFormat(Now(), "yyyy-mm-dd")> <cfset comments = post.comments(where="createdAt >= '#today# 00:00:00'")>
We can use the same 3 association functions to set up many-to-many table relationships in our models. It follows the same logic as the descriptions mentioned earlier in this chapter, so let's jump right into an example.
Let's say that we wanted to set up a relationship between
customer can be subscribed to many
publications can be subscribed to by many
customers. In our database, this relationship is linked together by a third table called
subscriptions (sometimes called a bridge entity by ERD snobs).
Here are the representative models:
<!--- Customer.cfc ---> <cfcomponent extends="Model"> <cffunction name="init"> <cfset hasMany("subscriptions")> </cffunction> </cfcomponent>
<!--- Publication.cfc ---> <cfcomponent extends="Model"> <cffunction name="init"> <cfset hasMany("subscriptions")> </cffunction> </cfcomponent>
<!--- Subscription.cfc ---> <cfcomponent extends="Model"> <cffunction name="init"> <cfset belongsTo("customer")> <cfset belongsTo("publication")> </cffunction> </cfcomponent>
This assumes that there are foreign key columns in
At this point, it's still fairly easy to get data from the many-to-many association that we have set up above.
We can include the related tables from the
subscription bridge entity to get the same effect:
<cfset data = model("subscription").findAll(include="customer,publication")>
shortcut argument to hasMany(), you can have Wheels create a dynamic method that lets you bypass the join model and instead reference the model on the other end of the many-to-many relationship directly.
For our example above, you can alter the hasMany() call on the
customer model to look like this instead:
<cfset hasMany(name="subscriptions", shortcut="publications")>
Now you can get a customer's publications directly by using code like this:
<cfset cust = model("customer").findByKey(params.key)> <cfset pubs = cust.publications()>
It also relies on the association names being consistent, but if you have customized your association names, you can specify exactly which associations the shortcut method should use with the
through argument accepts a list of 2 association names. The first argument is the name of the belongsTo() association (set in the
subscription model in this case), and the second argument is the hasMany() association going back the other way (set in the
Sound complicated? That's another reason to stick to the conventions whenever possible: it keeps things simple.
As you just read, Wheels offers a ton of functionality to make your life easier in working with relational databases. Be sure to give some of these techniques a try in your next Wheels application, and you'll be amazed at how little code that you'll need to write to interact with your database.