Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
A hasOne
relationship is a "one-to-one" relationship. For instance, a User
entity might have an UserProfile
entity attached to it.
The first value passed to hasOne
is a WireBox mapping to the related entity.
Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the UserProfile
entity is assumed to have a userId
foreign key. You can override this by passing a foreign key in as the second argument:
If your parent entity does not use id
as its primary key, or you wish to join the child entity to a different column, you may pass a third argument to the hasOne
method specifying your parent table's custom key.
The inverse of hasOne
is belongsTo
. It is important to choose the right relationship for your database structure. hasOne
assumes that the related model has the foreign key for the relationship.
HasOne
relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault
on the relationship object.
Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault
.
Returns a HasOne relationship between this entity and the entity defined by relationName
.
A hasMany
relationship is a one-to-many
relationship. For instance, a User
may have multiple Posts
.
The first value passed to hasMany
is a WireBox mapping to the related entity.
Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the Post
entity is assumed to have a userId
foreign key. You can override this by passing a foreign key in as the second argument:
If your parent entity does not use id
as its primary key, or you wish to join the child entity to a different column, you may pass a third argument to the hasMany
method specifying your parent table's custom key.
You can call the save
method on the relationship passing in an entity to relate.
This will add the User
entity's id as a foreign key in the Post
and save the Post
to the database.
Note: the
save
method is called on theposts
relationship, not thegetPosts
collection.
You can also add many entities in a hasMany
relationship by calling saveMany
. This method takes an array of key values or entities and will associate each of them with the base entity.
Use the create
method to create and save a related entity directly through the relationship.
This example will have the same effect as the previous example.
You can also influence the associated entities by calling "set" & relationshipName
and passing in an array of entities or key values.
After running this code, this user would only have two posts, the posts with ids 2
and 4
. Any other posts would now be disassociated with this user. Likely your database will be guarding against creating these orphan records. Admittedly, this method is not as likely to be used as the others, but it does exist if it solves your use case.
Returns a HasMany relationship between this entity and the entity defined by relationName
.
The inverse of hasMany
is .
There are two ways to add an entity to a hasMany
relationship. Both mirror the for entities.
Removing a hasMany
relationship is handled in two ways: either by using the dissociate
method on the side of the relationship or by deleting the side of the relationship.
Relationship Types
Name
Type
Required
Default
Description
relationName
string
true
The WireBox mapping for the related entity.
foreignKey
String | [String]
false
entityName() & keyNames()
The foreign key on the parent entity.
localKey
String | [String]
false
keyNames()
The local primary key on the parent entity.
relationMethodName
String
false
The method name called on the entity to produce this relationship.
The method name called to retrieve this relationship. Uses a stack backtrace to determine by default.
<b></b>
DO NOT PASS A VALUE HERE UNLESS YOU KNOW WHAT YOU ARE DOING.
Name | Type | Required | Default | Description |
relationName | string |
| The WireBox mapping for the related entity. |
foreignKey | String | [String] |
|
| The foreign key on the parent entity. |
localKey | String | [String] |
|
| The local primary key on the parent entity. |
relationMethodName | String |
| The method name called on the entity to produce this relationship. | The method name called to retrieve this relationship. Uses a stack backtrace to determine by default. <b></b> DO NOT PASS A VALUE HERE UNLESS YOU KNOW WHAT YOU ARE DOING. |
A belongsTo
relationship is a many-to-one
relationship. For instance, a Post
may belong to a User
.
The first value passed to belongsTo
is a WireBox mapping to the related entity.
Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the Post
entity is assumed to have a userId
foreign key. You can override this by passing a foreign key in as the second argument:
If your parent entity does not use id
as its primary key, or you wish to join the child entity to a different column, you may pass a third argument to the belongsTo
method specifying your parent table's custom key.
The inverse of belongsTo
is hasMany
or hasOne
.
To update a belongsTo
relationship, use the associate
method. associate
takes the entity to associate as the only argument.
associate
does not automatically save the entity. Make sure to call save
when you are ready to persist your changes to the database.
To remove a belongsTo
relationship, use the dissociate
method.
dissociate
does not automatically save the entity. Make sure to call save
when you are ready to persist your changes to the database.
You can also influence the associated entities by calling "set" & relationshipName
and passing in an entity or key value.
After executing this code, the post would be updated in the database to be associated with the user with an id of 1
.
BelongsTo
relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault
on the relationship object.
Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault
.
Returns a BelongsTo relationship between this entity and the entity defined by relationName
.
A hasManyThrough
relationship is either a one-to-many
or a many-to-many
relationship. It is used when you want to access related entities through one or more intermediate entities. The most common example for this is through a pivot table. For instance, a User
may have multiple Permissions
via a UserPermission
entity. This allows you to store additional data on the UserPermission
entity, like a createdDate
.
The only value needed for hasManyThrough
is an array of relationship function names to walk through to get to the related entity. The first relationship function name in the array must exist on the current entity. Each subsequent function name must exist on the related entity of the previous relationship result. For our previous example, userPermissions
must be a relationship function on User
. permission
must then be a relationship function on the related entity resulting from calling User.userPermissions()
. This returns a hasMany
relationship where the related entity is UserPermission
. So, UserPermission
must have a permission
relationship function. That is the end of the relationship function names array, so the related entity resulting from calling UserPermission.permission()
is our final entity which is Permission
.
Let's take a look at another example. HasManyThrough
relationships can go up and down the relationship chain. Here's an example of finding a User's teammates
The inverse of hasManyThrough
is either a belongsToThrough
or a hasManyThrough
relationship.
This approach can scale to as many related entities as you need. For instance, let's expand the previous example to include an Office that houses many Teams.
This next example can get a little gnarly - you can include other hasManyThrough
relationships in a hasManyThrough
relationship function names array. You can rewrite the officemates
relationship like so:
As you can see, this is a very powerful relationship type that can save you many unnecessary queries to get the data you need.
A belongsToMany
relationship is a many-to-many
relationship. For instance, a User
may have multiple Permissions
while a Permission
can belong to multiple Users
.
The first value passed to belongsToMany
is a WireBox mapping to the related entity.
belongsToMany
makes some assumptions about your table structure. To support a many-to-many
relationship, you need a pivot table. This is, at its simplest, a table with each of the foreign keys as columns.
As you can see, Quick uses a convention of combining the entity table names in alphabetical order with an underscore (_
) to create the new pivot table name. If you want to override this convention, you can do so by passing the desired table name as the second parameter or the table
parameter.
Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the User
entity is assumed to have a userId
foreign key and the Permission
entity a permissionId
foreign key. You can override this by passing a foreignKey
in as the third argument and a relatedKey
as the fourth argument:
Finally, if you are not joining on the primary keys of the current entity or the related entity, you can specify those keys using the last two parameters:
The inverse of belongsToMany
is also belongsToMany
. The foreignKey
and relatedKey
arguments are swapped on the inverse side of the relationship.
If you find yourself needing to interact with the pivot table (permissions_users
) in the example above, you can create an intermediate entity, like UserPermission
. You will still be able to access the end of the relationship chain using the hasManyThrough
relationship type.
Use the attach
method to relate two belongsToMany
entities together. attach
can take a single id, a single entity, or an array of ids or entities (even mixed and matched) to associate.
Use the detach
method to remove an existing entity from a belongsToMany
relationship. detatch
can also take a single id, a single entity, or an array of ids or entities (even mixed and matched) to remove.
Sometimes you just want the related entities to be a list you give it. For these situations, use the sync
method.
Now, no matter what relationships existed before, this Post
will only have three tags associated with it.
You can also influence the associated entities by calling "set" & relationshipName
and passing in an entity or key value.
This code calls sync
on the relationship. After executing this code, the post would be updated in the database to be associated with the tags passed in (4
, 12
, and 2
). Any tags that were previously associated with this post would no longer be and only the tags passed in would be associated now.
Returns a BelongsToMany relationship between this entity and the entity defined by relationName
.
A polymorphicBelongsTo
relationship is a many-to-one
relationship. This relationship is used when an entity can belong to multiple types of entities. The classic example for this type of relationship is Posts
, Videos
, and Comments
. For instance, a Comment
may belong to a Post
or a Video
.
The only value passed to polymorphicBelongsTo
is a prefix
for the polymorphic type. A common convention where is to add able
to the end of the entity name, though this is not automatically done. In our example, this prefix is commentable
. This tells quick to look for a commentable_type
and a commentable_id
column in our Comment
entity. It stores our entity's mapping as the _type
and our entity's primary key value as the _id
.
When retrieving a polymorphicBelongsTo
relationship the _id
is used to retrieve a _type
from the database.
The inverse of polymorphicBelongsTo
is also polymorphicHasMany
. It is important to choose the right relationship for your database structure. hasOne
assumes that the related model has the foreign key for the relationship.
Returns a polymorphicBelongsTo relationship between this entity and the entity defined by relationName
.
A hasOneThrough
relationship is either a many-to-one
or a one-to-one
relationship. It is used when you want to access a related entity through one or more intermediate entities. For instance, a Team
may have one latest Post
through a User
.
The only value needed for hasOneThrough
is an array of relationship function names to walk through to get to the related entity. The first relationship function name in the array must exist on the current entity. Each subsequent function name must exist on the related entity of the previous relationship result. For our previous example, members
must be a relationship function on Team
. posts
must then be a relationship function on the related entity resulting from calling Team.members()
. This returns a hasMany
relationship where the related entity is User
. So, User
must have a posts
relationship function. That is the end of the relationship function names array, so the related entity resulting from calling User.posts()
is our final entity which is Post
.
This approach can scale to as many related entities as you need. For instance, let's expand the previous example to include an Office that houses many Teams.
HasOneThrough
relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault
on the relationship object.
Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault
.
A belongsToThrough
relationship is the one
side of a many-to-one
relationship with an intermediate entity. It is used when you want to access a related, owning entity through one or more intermediate entities. For instance, a Post
may belong to a Team
via a User
.
The only value needed for belongsToThrough
is an array of relationship function names to walk through to get to the related entity. The first relationship function name in the array must exist on the current entity. Each subsequent function name must exist on the related entity of the previous relationship result. For our previous example, author
must be a relationship function on Post
. team
must then be a relationship function on the related entity resulting from calling Post.author()
. This returns a belongsTo
relationship where the related entity is User
. So, User
must have a team
relationship function. That is the end of the relationship function names array, so the related entity resulting from calling User.team()
is our final entity which is Team
.
This approach can scale to as many related entities as you need. For instance, let's expand the previous example to include an Office that houses many Teams.
HasOneThrough
relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault
on the relationship object.
Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault
.
A polymorphicHasMany
relationship is a one-to-many
relationship. This relationship is used when an entity can belong to multiple types of entities. The classic example for this type of relationship is Posts
, Videos
, and Comments
.
The first value passed to polymophicHasMany
is a WireBox mapping to the related entity.
The second value is a prefix
for the polymorphic type. A common convention where is to add able
to the end of the entity name, though this is not automatically done. In our example, this prefix is commentable
. This tells quick to look for a commentable_type
and a commentable_id
column in our Comment
entity. It stores our entity's mapping as the _type
and our entity's primary key value as the _id
.
The inverse of polymophicHasMany
is polymorphicBelongsTo
.
Returns a polymorphicHasMany relationship between this entity and the entity defined by relationName
.
Name
Type
Required
Default
Description
relationName
string
true
The WireBox mapping for the related entity.
foreignKey
String | [String]
false
entityName() & keyNames()
The foreign key on the parent entity.
localKey
String | [String]
false
keyNames()
The local primary key on the parent entity.
relationMethodName
String
false
The method name called on the entity to produce this relationship.
The method name called to retrieve this relationship. Uses a stack backtrace to determine by default.
DO NOT PASS A VALUE HERE UNLESS YOU KNOW WHAT YOU ARE DOING.
Name
Type
Required
Default
Description
relationships
array
true
An array of relationship function names. The relationships are resolved from left to right. Each relationship will be resolved from the previously resolved relationship, starting with the current entity.
relationMethodName
string
false
Current Method Name
The method name called to retrieve this relationship. Uses a stack backtrace to determine by default.
Name
Type
Required
Default
Description
relationName
string
true
The WireBox mapping for the related entity.
table
String
false
Table names in alphabetical order separated by an underscore.
The table name used as the pivot table for the relationship. A pivot table is a table that stores, at a minimum, the primary key values of each side of the relationship as foreign keys.
foreignPivotKey
String | [String]
false
keyNames()
The name of the column on the pivot table
that holds the value of the parentKey
of the parent
entity.
relatedPivotKey
String | [String]
false
The name of the column on the pivot table
that holds the value of the relatedKey
of the ralated
entity.
parentKey
String | [String]
false
The name of the column on the parent
entity that is stored in the foreignPivotKey
column on table
.
relatedKey
String | [String]
false
The name of the column on the related
entity that is stored in the relatedPivotKey
column on table
.
relationMethodName
String
false
The method name called on the entity to produce this relationship.
The method name called to retrieve this relationship. Uses a stack backtrace to determine by default.
<b></b>
DO NOT PASS A VALUE HERE UNLESS YOU KNOW WHAT YOU ARE DOING.
Name | Type | Required | Default | Description |
name | String |
|
| The name given to the polymorphic relationship. |
type | String |
|
| The column name that defines the type of the polymorphic relationship. |
id | String |
|
| The column name that defines the id of the polymorphic relationship. |
localKey | String | [String] |
|
| The column name on the |
relationMethodName | String |
| The method name called on the entity to produce this relationship. | The method name called to retrieve this relationship. Uses a stack backtrace to determine by default. DO NOT PASS A VALUE HERE UNLESS YOU KNOW WHAT YOU ARE DOING. |
Name | Type | Required | Default | Description |
relationships | array |
| An array of relationship function names. The relationships are resolved from left to right. Each relationship will be resolved from the previously resolved relationship, starting with the current entity. |
relationMethodName | string | false | Current Method Name | The method name called to retrieve this relationship. Uses a stack backtrace to determine by default. |
Name | Type | Required | Default | Description |
relationships | array |
| An array of relationship function names. The relationships are resolved from left to right. Each relationship will be resolved from the previously resolved relationship, starting with the current entity. |
relationMethodName | string | false | Current Method Name | The method name called to retrieve this relationship. Uses a stack backtrace to determine by default. |
Name | Type | Required | Default | Description |
relationName | String |
| The WireBox mapping for the related entity. |
name | String |
| The name given to the polymorphic relationship. |
type | String |
|
| The column name that defines the type of the polymorphic relationship. |
id | String |
|
| The column name that defines the id of the polymorphic relationship. |
localKey | String | [String] |
|
| The local primary key on the parent entity. |
relationMethodName | String |
| The method name called on the entity to produce this relationship. | The method name called to retrieve this relationship. Uses a stack backtrace to determine by default. DO NOT PASS A VALUE HERE UNLESS YOU KNOW WHAT YOU ARE DOING. |