Through some simple configuration, Wheels allows you to unlock some powerful functionality to use your database tables' relationships in your code.
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 config()
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 config()
method within our comment model:
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:
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 hasMany()
method.
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 user
and 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:
And our user model would look like this:
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 the example above, a profile
is dependent on a user
. When you delete the user
, you would usually want to delete the profile
as well.
CFWheels makes this easy for you. When setting up your association, simply add the argument dependent
with one of the following values, and CFWheels will automatically deal with the dependency.
In your model .cfc file config() function::
You can create dependencies on hasOne()
and hasMany()
associations, but not belongsTo()
.
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:
Both the manager and employee are stored in the same employees
table and share the same Employee
model.
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 select
argument.
Here's an example of how to select both the name of the employee and their manager:
Know Your Joins
Because the default joinType
for belongsTo()
is inner
, employees without a manager assigned to them will not be returned in the findAll()
call above. To return all rows you can set jointype
to outer
instead.
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 employeeid
.
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' belongsTo()
calls.
Let's pretend that you have a relationship betweenauthor
and post
, but you didn't use the naming convention and instead called the column author_id
. (You just can't seem to let go of the underscores, can you?)
Your post's config()
method would then need to look like this:
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.
To join data from related tables in our findAll() calls, we simply need to use the include argument. Let's say that we wanted to include data about the author in our findAll() call for posts
.
Here's what that call would look like:
It's that simple. Wheels will then join the authors
table automatically so that you can use that data along with the data from posts
.
Note that if you switch the above statement around like this:
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:
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:
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 posts
and authors
tables, then you could use the select
argument like so:
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 postid=#post.id#
.
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 post
model.
Replace XXX
below with the name of the associated model (i.e. comments
in the case of the example that we're using here).
Methods Added by hasOne
The hasOne() association adds a few methods as well. Most of them are very similar to the ones added by hasMany().
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 author
model.
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 comment
model.
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 findAll()
.
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 1
.)
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.
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 customers
and publications
. A customer
can be subscribed to many publications
, and 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:
This assumes that there are foreign key columns in subscriptions
called customerid
and publicationid
.
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:
With the 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:
Now you can get a customer's publications directly by using code like this:
This functionality relies on having set up all the appropriate hasMany() and belongsTo() associations in all 3 models (like we have in our example in this chapter).
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.
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 publication
model).
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.
Method | Example | Description |
---|---|---|
Method | Example | Description |
---|---|---|
Method | Example | Description |
---|---|---|
XXX()
post.comments()
Returns all comments where the foreign key matches the post's primary key value. Similar to calling model("comment").findAll(where="postid=#post.id#")
.
addXXX()
post.addComment(comment)
Adds a comment to the post association by setting its foreign key to the post's primary key value. Similar to calling model("comment").updateByKey(key=comment.id, postid=post.id)
.
removeXXX()
post.removeComment(comment)
Removes a comment from the post association by setting its foreign key value to NULL
. Similar to calling model("comment").updateByKey(key=comment.id, postid="")
.
deleteXXX()
post.deleteComment(comment)
Deletes the associated comment from the database table. Similar to calling model("comment").deleteByKey(key=comment.id)
.
removeAllXXX()
post.removeAllComments()
Removes all comments from the post association by setting their foreign key values to NULL
. Similar to calling model("comment").updateAll(postid="", where="postid=#post.id#")
.
deleteAllXXX()
post.deleteAllComments()
Deletes the associated comments from the database table. Similar to calling model("comment").deleteAll(where="postid=#post.id#")
.
XXXCount()
post.commentCount()
Returns the number of associated comments. Similar to calling model("comment").count(where="postid=#post.id#")
.
newXXX()
post.newComment()
Creates a new comment object. Similar to calling model("comment").new(postid=post.id)
.
createXXX()
post.createComment()
Creates a new comment object and saves it to the database. Similar to calling model("comment").create(postid=post.id)
.
hasXXX()
post.hasComments()
Returns true if the post has any comments associated with it. Similar to calling model("comment").exists(where="postid=#post.id#")
.
findOneXXX()
post.findOneComment()
Returns one of the associated comments. Similar to calling model("comment").findOne(where="postid=#post.id#")
.
XXX()
author.profile()
Returns the profile where the foreign key matches the author's primary key value. Similar to calling model("profile").findOne(where="authorid=#author.id#").
setXXX()
author.setProfile(profile)
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).
removeXXX()
author.removeProfile()
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="").
deleteXXX()
author.deleteProfile()
Deletes the associated profile from the database table. Similar to calling model("profile").deleteOne(where="authorid=#author.id#")
newXXX()
author.newProfile()
Creates a new profile object. Similar to calling model("profile").new(authorid=author.id).
createXXX()
author.createProfile()
Creates a new profile object and saves it to the database. Similar to calling model("profile").create(authorid=author.id).
hasXXX()
author.hasProfile()
Returns true if the author has an associated profile. Similar to calling model("profile").exists(where="authorid=#author.id#").
XXX()
comment.post()
Returns the post where the primary key matches the comment's foreign key value. Similar to calling model("post").findByKey(comment.postid).
hasXXX()
comment.hasPost()
Returns true if the comment has a post associated with it. Similar to calling model("post").exists(comment.postid).