UserFrosting API

BelongsToManyThrough extends BelongsToMany Uses Unique

A BelongsToMany relationship that queries through an additional intermediate model.

Tags
author

Alex Weissman (https://alexanderweissman.com)

see
https://github.com/laravel/framework/blob/5.8/src/Illuminate/Database/Eloquent/Relations/BelongsToMany.php

Table of Contents

$intermediateRelation The relation through which we are joining. Relation
$tertiaryRelated The related tertiary model instance. Model
$tertiaryRelationName The name to use for the tertiary relation (e.g. 'roles_via', etc). string
$tertiaryKey The foreign key to the related tertiary model instance. string
$tertiaryCallback A callback to apply to the tertiary query. callable|null
$limit The limit to apply on the number of related models retrieved. int|null
$offset The offset to apply on the related models retrieved. int|null
__construct() Create a new belongs to many relationship instance. mixed
getParentKeyName() Use the intermediate relationship to determine the "parent" pivot key name. string
getExistenceCompareKey() Get the key for comparing against the parent key in "has" query. string
withVia() Add a "via" query to load the intermediate models through which the child models are related. self
addEagerConstraints() Set the constraints for an eager load of the relation. mixed
addWhereConstraints() Set the where clause for the relation query. self
match() Match the eagerly loaded results to their parents. array
unsetTertiaryPivots() Unset tertiary pivots on a collection or array of models. mixed
performJoin() Set the join clause for the relation query. self
aliasedPivotColumns() Get the pivot columns for the relation. array
skip() Alias to set the "offset" value of the query. self
offset() Set the "offset" value of the query. self
take() Alias to set the "limit" value of the query. self
limit() Set the "limit" value of the query. self
withLimit() Set the limit on the number of intermediate models to load. $this
withOffset() Set the offset when loading the intermediate models. $this
withTertiary() Add a query to load the nested tertiary models for this relationship. self
count() Return the count of child models for this relationship. int
getRelationExistenceCountQuery() Add the constraints for a relationship count query. Builder
match() Match the eagerly loaded results to their parents. array
get() Execute the query as a "select" statement, getting all requested models and matching up any tertiary models. Collection
getPaginatedQuery() If we are applying either a limit or offset, we'll first determine a limited/offset list of model ids to select from in the final query. Builder
getEager() Get the full join results for this query, overriding the default getEager() method. Collection
getModels() Get the hydrated models and eager load their relations, optionally condensing the set of models before performing the eager loads. Collection
condenseModels() Condense the raw join query results into a set of unique models. array
buildDictionary() Build dictionary of related models keyed by the top-level "parent" id. array
buildTertiaryDictionary() Build dictionary of tertiary models keyed by the corresponding related model keys. array
transferPivotsToTertiary() Transfer the pivot to the tertiary model. mixed
getTertiaryModels() Get the tertiary models for the relationship. Collection
matchTertiaryModels() Match a collection of child models into a collection of parent models using a dictionary. mixed
unsetTertiaryPivots() Unset tertiary pivots on a collection or array of models. mixed

Properties

$intermediateRelation

The relation through which we are joining.

protected Relation $intermediateRelation

$tertiaryRelated

The related tertiary model instance.

protected Model $tertiaryRelated = null

$tertiaryRelationName

The name to use for the tertiary relation (e.g. 'roles_via', etc).

protected string $tertiaryRelationName = null

$tertiaryKey

The foreign key to the related tertiary model instance.

protected string $tertiaryKey

$tertiaryCallback

A callback to apply to the tertiary query.

protected callable|null $tertiaryCallback = null

$limit

The limit to apply on the number of related models retrieved.

protected int|null $limit = null

$offset

The offset to apply on the related models retrieved.

protected int|null $offset = null

Methods

__construct()

Create a new belongs to many relationship instance.

public __construct( $query : Builder , $parent : Model , $intermediateRelation : Relation , $table : string , $foreignPivotKey : string , $relatedPivotKey : string , $parentKey : string , $relatedKey : string [, $relationName : string = null ] ) : mixed
Parameters
$query : Builder
$parent : Model
$intermediateRelation : Relation
$table : string
$foreignPivotKey : string
$relatedPivotKey : string
$parentKey : string
$relatedKey : string
$relationName : string = null
Return values
mixed

getParentKeyName()

Use the intermediate relationship to determine the "parent" pivot key name.

public getParentKeyName( ) : string

This is a crazy roundabout way to get the name of the intermediate relation's foreign key. It would be better if BelongsToMany had a simple accessor for its foreign key.

Return values
string

getExistenceCompareKey()

Get the key for comparing against the parent key in "has" query.

public getExistenceCompareKey( ) : string
Tags
see
BelongsToMany
Return values
string

withVia()

Add a "via" query to load the intermediate models through which the child models are related.

public withVia( [ $viaRelationName : string = null ] [, $viaCallback : callable = null ] ) : self
Parameters
$viaRelationName : string = null
$viaCallback : callable = null
Return values
self

addEagerConstraints()

Set the constraints for an eager load of the relation.

public addEagerConstraints( $models : array ) : mixed
Parameters
$models : array
Return values
mixed

addWhereConstraints()

Set the where clause for the relation query.

protected addWhereConstraints( ) : self
Return values
self

match()

Match the eagerly loaded results to their parents.

public match( $models : array , $results : Collection , $relation : string ) : array
Parameters
$models : array
$results : Collection
$relation : string
Return values
array

unsetTertiaryPivots()

Unset tertiary pivots on a collection or array of models.

protected unsetTertiaryPivots( $models : Collection ) : mixed
Parameters
$models : Collection
Return values
mixed

performJoin()

Set the join clause for the relation query.

protected performJoin( [ $query : Builder|null = null ] ) : self
Parameters
$query : Builder|null = null
Return values
self

aliasedPivotColumns()

Get the pivot columns for the relation.

protected aliasedPivotColumns( ) : array

"pivot_" is prefixed to each column for easy removal later.

Return values
array

skip()

Alias to set the "offset" value of the query.

public skip( $value : int ) : self
Parameters
$value : int
Return values
self

offset()

Set the "offset" value of the query.

public offset( $value : int ) : self
Parameters
$value : int
Tags
todo

Implement for 'unionOffset' as well? (By checking the value of $this->query->getQuery()->unions)

see
Builder
Return values
self

take()

Alias to set the "limit" value of the query.

public take( $value : int ) : self
Parameters
$value : int
Return values
self

limit()

Set the "limit" value of the query.

public limit( $value : int ) : self
Parameters
$value : int
Tags
todo

Implement for 'unionLimit' as well? (By checking the value of $this->query->getQuery()->unions)

see
Builder
Return values
self

withLimit()

Set the limit on the number of intermediate models to load.

public withLimit( $value : int ) : $this
Parameters
$value : int
Tags
deprecated

since 4.1.7

Return values
$this

withOffset()

Set the offset when loading the intermediate models.

public withOffset( $value : int ) : $this
Parameters
$value : int
Tags
deprecated

since 4.1.7

Return values
$this

withTertiary()

Add a query to load the nested tertiary models for this relationship.

public withTertiary( $tertiaryRelated : string [, $tertiaryRelationName : string = null ] [, $tertiaryKey : string = null ] [, $tertiaryCallback : callable = null ] ) : self
Parameters
$tertiaryRelated : string
$tertiaryRelationName : string = null
$tertiaryKey : string = null
$tertiaryCallback : callable = null
Return values
self

getRelationExistenceCountQuery()

Add the constraints for a relationship count query.

public getRelationExistenceCountQuery( $query : Builder , $parentQuery : Builder ) : Builder
Parameters
$query : Builder
$parentQuery : Builder
Tags
see
Relation
Return values
Builder

match()

Match the eagerly loaded results to their parents.

public match( $models : array , $results : Collection , $relation : string ) : array
Parameters
$models : array
$results : Collection
$relation : string
Return values
array

get()

Execute the query as a "select" statement, getting all requested models and matching up any tertiary models.

public get( [ $columns : array = ['*'] ] ) : Collection
Parameters
$columns : array = ['*']
Return values
Collection

getPaginatedQuery()

If we are applying either a limit or offset, we'll first determine a limited/offset list of model ids to select from in the final query.

public getPaginatedQuery( $query : Builder [, $limit : int = null ] [, $offset : int = null ] ) : Builder
Parameters
$query : Builder
$limit : int = null
$offset : int = null
Return values
Builder

getEager()

Get the full join results for this query, overriding the default getEager() method.

public getEager( ) : Collection

The default getEager() method would normally just call get() on this relationship. This is not what we want here though, because our get() method removes records before match has a chance to build out the substructures.

Return values
Collection

getModels()

Get the hydrated models and eager load their relations, optionally condensing the set of models before performing the eager loads.

public getModels( [ $columns : array = ['*'] ] [, $condenseModels : bool = true ] ) : Collection
Parameters
$columns : array = ['*']
$condenseModels : bool = true
Return values
Collection

condenseModels()

Condense the raw join query results into a set of unique models.

protected condenseModels( $models : array ) : array

Before doing this, we may optionally find any tertiary models that should be set as sub-relations on these models.

Parameters
$models : array
Return values
array

buildDictionary()

Build dictionary of related models keyed by the top-level "parent" id.

protected buildDictionary( $results : Collection [, $parentKey : string = null ] ) : array

If there is a tertiary query set as well, then also build a two-level dictionary that maps parent ids to arrays of related ids, which in turn map to arrays of tertiary models corresponding to each relationship.

Parameters
$results : Collection
$parentKey : string = null
Return values
array

buildTertiaryDictionary()

Build dictionary of tertiary models keyed by the corresponding related model keys.

protected buildTertiaryDictionary( $models : array ) : array
Parameters
$models : array
Return values
array

transferPivotsToTertiary()

Transfer the pivot to the tertiary model.

protected transferPivotsToTertiary( $model : Model , $tertiaryModel : Model ) : mixed
Parameters
$model : Model
$tertiaryModel : Model
Return values
mixed

getTertiaryModels()

Get the tertiary models for the relationship.

protected getTertiaryModels( $models : array ) : Collection
Parameters
$models : array
Return values
Collection

matchTertiaryModels()

Match a collection of child models into a collection of parent models using a dictionary.

protected matchTertiaryModels( $dictionary : array , $results : Collection ) : mixed
Parameters
$dictionary : array
$results : Collection
Return values
mixed

unsetTertiaryPivots()

Unset tertiary pivots on a collection or array of models.

protected unsetTertiaryPivots( $models : Collection ) : mixed
Parameters
$models : Collection
Return values
mixed

Search results