Eloquent relationships

11 min read

(For more resources related to this topic, see here.)

1 — Eloquent relationships

ActiveRecord is a design pattern that describes an object-oriented way of interacting with your database. For example, your database’s users table contains rows and each of these rows represents a single user of your site. Your User model is a class that extends the Eloquent Model class. When you query a record from your database, an instantiation of your User model class is created and populated with the information from the database.

A distinct advantage of ActiveRecord is that your data and the business logic that is related to the data are housed within the same object. For example, it’s typical to store the user’s password in your model as a hash, to prevent it from being stored as plaintext. It’s also typical to store the method, which creates this password hash within your User class.

Another powerful aspect of the ActiveRecord pattern is the ability to define relationships between models. Imagine that you’re building a blog site and your users are authors who must be able to post their writings. Using an ActiveRecord implementation, you are able to define the parameters of the relationship. The task of maintaining this relationship is then simplified dramatically. Simple code is the easy code to change. Difficult to understand code is the easy code to break.

As a PHP developer, you’re probably already familiar with the concept of database normalization. If you’re not, normalization is the process of designing databases so that there is little redundancy in the stored data. For example, you wouldn’t want to have both a users table which contains the user’s name and a table of blog posts which also contains the author’s name. Instead, your blog post record would refer to the user using their user ID. In this way we avoid synchronization problems and a lot of extra work!

There are a number of ways in which relationships can be established in normalized database schemas.

One-to-one relationship

When a relationship connects two records in a way that doesn’t allow for more records to be related, it is a one-to-one relationship. For example, a user record might have a one-to-one relationship with a passport record. In this example, a user record is not permitted to be linked to more than one passport record. Similarly, it is not permitted for a passport record to relate to more than one user record.

How would the database look? Your users table contains information about each user in your database. Your passports table contains passport numbers and a link to the user which owns the passport.

In this example, each user has no more than one passport and each passport must have an owner. The passports table contains its own id column which it uses as a primary key. It also contains the column user_id, which contains the ID of the user to whom the passport belongs. Last but not least, the passports table contains a column for the passport number.

First, let’s model this relationship in the User class:

class User extends Eloquent { public function passport() { return $this->has_one('Passport'); } }

We created a method named passport() that returns a relationship. It might seem strange to return relationships at first. But, you’ll soon come to love it for the flexibility it offers.

You’ll notice that we’re using the has_one() method and passing the name of the model as a parameter. In this case, a user has one passport. So, the parameter is the name of the passport model class. This is enough information for Eloquent to understand how to acquire the correct passport record for each user.

Now, let’s look at the Passport class:

class Passport extends Eloquent { public function users() { return $this->belongs_to('User'); } }

We’re defining the passport’s relationship differently. In the User class, we used the has_one() method. In the Passport class we used belongs_to().

It’s vital to identify the difference early so that understanding the rest of the relationships is more simple. When a database table contains a foreign key, it is said that it belongs to a record in another table. In this example, our passports table refers to records in the users table through the foreign key user_id. Consequently, we would say that a passport belongs to a user. Since this is a one-to-one relationship the user has one (has_one()) passport.

Let’s say that we want to view the passport number of the user with the id of 1.

$user = User::find(1); If(is_null($user)) { echo "No user found."; return; } If($user->passport) { echo "The user's passport number is " . $user->passport->number; } else { echo "This user has no passport."; }

In this example, we’re dutifully checking to make sure that our user object was returned as expected. This is a necessary step that should not be overlooked. Then, we check whether or not the user has a passport record associated with it. If a passport record for this user exists, the related object will be returned. If it doesn’t exist, $user->passport will return null. In the preceding example, we test for the existence of a record and return the appropriate response.

One-to-many relationships

One-to-many relationships are similar to one-to-one relationships. In this relationship type, one model has many of other relationships, which in turn belongs to the former. One example of a one-to-many relationship is a professional sports team’s relationship to its players. One team has many players. In this example, each player can only belong to one team. The database tables have the same structure.

Now, let’s look at the code which describes this relationship.

class Team extends Eloquent { public function players() { return $this->has_many('Player'); } } class Player extends Eloquent { public function team() { return $this->belongs_to('Team'); } }

This example is almost identical to the one-to-one example. The only difference is that the team’s players() relationship uses has_many() rather than has_one(). The has_one() relationship returns a model object. The has_many() relationship returns an array of model objects.

Let’s display all of the players on a specific team:

$team = Team::find(2); if(is_null($team)) { echo "The team could not be found."; } if(!$team->players) { echo "The team has no players."; } foreach($team->players as $player) { echo "$player->name is on team $team->name. "; }

Again, we test to make sure that our team could be found. Then, we test to make sure that the team has players. Once we know that for sure, we can loop through those players and echo their names. If we tried to loop through the players without first testing and if the team had players, we’d get an error.

Many-to-many relationships

The last relationship type that we’re going to cover is the many-to-many relationship. This relationship is different in that each record from each table could potentially be tied simultaneously to each record in another. We aren’t storing foreign keys in either of these tables. Instead, we have a third table that exists solely to store our foreign keys. Let’s take a look at the schema.

Here we have a students table and a courses table. A student can be enrolled in many courses and a course can contain many students. The connection between students and courses is stored in a pivot table.

A pivot table is a table that exists to connect two tables specifically for many-to-many relationships. Standard convention for naming a pivot table is to combine the names of both of the related tables, singularized, alphabetically ordered, and connected with an underscore. This gives us the table name course_student. This convention is not only used by Laravel and it’s a good idea to follow the naming conventions covered in this document as strictly as possible as they’re widely used in the web-development industry.

It’s important to notice that we’re not creating a model for the pivot table. Laravel allows us to manage these tables without needing to interact with a model. This is especially nice because it doesn’t make sense to model a pivot table with business logic. Only the students and courses are a part of our business. The connection between them is important, but only to the students and to the course. It’s not important for its own sake.

Let’s define these models, shall we?

class Student extends Eloquent { public function courses() { return $this->has_many_and_belongs_to('Course'); } } class Course extends Eloquent { public function students() { return $this->has_many_and_belongs_to('Student'); } }

We have two models, each with the same type of relationship to each other. has_many_and_ belongs_to is a long name. But, it’s a fairly simple concept. A course has many students. But, it also belongs to (belongs_to) student records and vice-versa. In this way, they are considered equal.

Let’s look at how we’ll interact with these models in practice:

$student = Student::find(1); if(is_null($student)) { echo "The student can't be found."; exit; } if(!$student->courses) { echo "The student $student->name is not enrolled in any courses."; exit; } foreach($student->courses as $course) { echo "The student $student->name is enrolled in the course $course->name."; }

Here you can see that we can loop through the courses much the same way we could with the one-to-many relationship. Any time a relationship includes the word many, you know that you’ll be receiving an array of models. Conversely, let’s pull a course and see which students are a part of it.

$course = Course::find(1); if(is_null($course)) { echo "The course can't be found."; exit; } if(!$course->students) { echo "The course $course->name seems to have no students enrolled."; exit; } foreach($course->students as $student) { echo "The student $student->name is enrolled in the course $course->name."; }

The relationship functions exactly the same way from the course side.

Now that we have established this relationship, we can do some fun things with it. Let’s look at how we’d enroll a new student into an existing course:

$course = Course::find(13); if(is_null($course)) { echo "The course can't be found."; exit; } $new_student_information = array( 'name' => 'Danielle' ); $course->students()->insert($new_student_information);

Here we’re adding a new student to our course by using the method insert(). This method is specific to this relationship type and creates a new student record. It also adds a record to the course_student table to link the course and the new student. Very handy!

But, hold on. What’s this new syntax?


Notice how we’re not using $course->students->insert(). Our reference to students is a method reference rather than a property reference. That’s because Eloquent handles methods that return relationship objects differently from other model methods.

When you access a property of a model that doesn’t exist, Eloquent will look to see if you have a function that matches that property’s name. For example, if we try to access the property $course->students, Eloquent won’t be able to find a member variable named $students. So it’ll look for a function named students(). We do have one of those. Eloquent will then receive the relationship object from that method, process it, and return the resulting student records.

If we access a relationship method as a method and not as a property, we directly receive the relationship object back. The relationship’s class extends the Query class. This means that you can operate on a relationship object in the same way that you can operate on a query object, except that it now has new methods that are specific to the relationship type. The specific implementation details aren’t important at this point. It’s just important to know that we’re calling the insert() method on the relationship object returned from $course->students().

Imagine that you have a user model and it has many relationships and belongs to a role model. Roles represent different permission groupings. Example roles might include customer, admin, super admin, and ultra admin.

It’s easy to imagine a user form for managing its roles. It would contain a number of checkboxes, one for each potential role. The name of the checkboxes is role_ids[] and each value represents the ID of a role in the roles table./p>

When that form is posted we’ll retrieve those values with the Input::get() method.

$role_ids = Input::get('role_ids');

$role_ids is now an array that contains the values 1, 2, 3, and 4.


The sync() method is specific to this relationship type and is also perfectly suited for our needs. We’re telling Eloquent to connect our current $user to the roles whose IDs exist within the $role_ids array.

Let’s look at what’s going on here in further detail. $user->roles() is returning a has_ many_and_belongs_to relationship object. We’re calling the sync() method on that object. Eloquent now looks at the $role_ids array and acknowledges it as the authoritative list of roles for this user. It then removes any records that shouldn’t exist in the role_user pivot table and adds records for any role that should exist in the pivot table.


In this article we discussed three types of Eloquent relationships—one-to-one relationship, one-to-many relationship, and many-to-many ralationship.

Resources for Article :

Further resources on this subject:


Please enter your comment!
Please enter your name here