Class EagerLoader

Exposes the methods for storing the associations that should be eager loaded for a table once a query is provided and delegates the job of creating the required joins and decorating the results so that those associations can be part of the result set.

Namespace: Cake\ORM
Location: ORM/EagerLoader.php

Properties summary

  • $_aliasList protected
    array
    Contains a list of the association names that are to be eagerly loaded
  • $_autoFields protected
    boolean

    Controls whether or not fields from associated tables will be eagerly loaded. When set to false, no fields will be loaded from associations.

  • $_containOptions protected
    array

    List of options accepted by associations in contain() index by key for faster access

  • $_containments protected
    array

    Nested array describing the association to be fetched and the options to apply for each of them, if any

  • $_joinsMap protected
    array

    A map of table aliases pointing to the association objects they represent for the query.

  • $_loadExternal protected
    Cake\ORM\EagerLoadable[]
    A list of associations that should be loaded with a separate query
  • $_matching protected
    Another EagerLoader instance that will be used for 'matching' associations.
  • $_normalized protected
    Cake\ORM\EagerLoadable[]|Cake\ORM\EagerLoadable|null

    Contains a nested array with the compiled containments tree This is a normalized version of the user provided containments array.

Method Summary

  • __clone() public
    Clone hook implementation
  • An internal method to build a map which is used for the return value of the associationsMap() method.

  • _collectKeys() protected

    Helper function used to return the keys from the query records that will be used to eagerly load associations.

  • _correctStrategy() protected

    Changes the association fetching strategy if required because of duplicate under the same direct associations chain

  • _fixStrategies() protected

    Iterates over the joinable aliases list and corrects the fetching strategies in order to avoid aliases collision in the generated queries.

  • _groupKeys() protected

    Helper function used to iterate a statement and extract the columns defined in $collectKeys

  • Auxiliary function responsible for fully normalizing deep associations defined using contain()

  • _reformatContain() protected

    Formats the containments array so that associations are always set as keys in the array. This function merges the original associations array with the new associations provided

  • _resolveJoins() protected

    Helper function used to compile a list of all associations that can be joined in the query.

  • Registers a table alias, typically loaded as a join in a query, as belonging to an association. This helps hydrators know what to do with the columns coming from such joined table.

  • Returns an array having as keys a dotted path of associations that participate in this eager loader. The values of the array will contain the following keys

  • Modifies the passed query to apply joins or any other transformation required in order to eager load the associations described in the contain array. This method will not modify the query for loading external associations, i.e. those that cannot be loaded without executing a separate query.

  • Returns an array with the associations that can be fetched using a single query, the array keys are the association aliases and the values will contain an array with Cake\ORM\EagerLoadable objects.

  • autoFields() public
    Sets/Gets whether or not contained associations will load fields automatically.
  • Remove any existing non-matching based containments.
  • contain() public

    Sets the list of associations that should be eagerly loaded along for a specific table using when a query is provided. The list of associated tables passed to this method must have been previously set as associations using the Table API.

  • Sets whether or not contained associations will load fields automatically.
  • Returns an array with the associations that need to be fetched using a separate query, each array value will contain a Cake\ORM\EagerLoadable object.

  • getMatching() public
    Returns the current tree of associations to be matched.
  • Gets whether or not contained associations will load fields automatically.
  • Decorates the passed statement object in order to inject data from associations that cannot be joined directly.

  • matching() public

    Adds a new association to the list that will be used to filter the results of any given query based on the results of finding records for that association. You can pass a dot separated path of associations to this method as its first parameter, this will translate in setting all those associations with the matching option.

  • normalized() public

    Returns the fully normalized array of associations that should be eagerly loaded for a table. The normalized array will restructure the original array by sorting all associations under one key and special options under another.

  • setMatching() public

    Adds a new association to the list that will be used to filter the results of any given query based on the results of finding records for that association. You can pass a dot separated path of associations to this method as its first parameter, this will translate in setting all those associations with the matching option.

Method Detail

__clone()source public

__clone( )

Clone hook implementation

Clone the _matching eager loader as well.

_buildAssociationsMap()source protected

_buildAssociationsMap( array $map , array $level , boolean $matching false )

An internal method to build a map which is used for the return value of the associationsMap() method.

Parameters

array $map
An initial array for the map.
array $level
An array of EagerLoadable instances.
boolean $matching optional false
Whether or not it is an association loaded through matching().

Returns

array

_collectKeys()source protected

_collectKeys( array $external , Cake\ORM\Query $query , Cake\Database\Statement\BufferedStatement $statement )

Helper function used to return the keys from the query records that will be used to eagerly load associations.

Parameters

array $external
the list of external associations to be loaded
Cake\ORM\Query $query
The query from which the results where generated
Cake\Database\Statement\BufferedStatement $statement
The statement to work on

Returns

array

_correctStrategy()source protected

_correctStrategy( Cake\ORM\EagerLoadable $loadable )

Changes the association fetching strategy if required because of duplicate under the same direct associations chain

Parameters

Cake\ORM\EagerLoadable $loadable
The association config

_fixStrategies()source protected

_fixStrategies( )

Iterates over the joinable aliases list and corrects the fetching strategies in order to avoid aliases collision in the generated queries.

This function operates on the array references that were generated by the _normalizeContain() function.

_groupKeys()source protected

_groupKeys( Cake\Database\Statement\BufferedStatement $statement , array $collectKeys )

Helper function used to iterate a statement and extract the columns defined in $collectKeys

Parameters

Cake\Database\Statement\BufferedStatement $statement
The statement to read from.
array $collectKeys
The keys to collect

Returns

array

_normalizeContain()source protected

_normalizeContain( Cake\ORM\Table $parent , string $alias , array $options , array $paths )

Auxiliary function responsible for fully normalizing deep associations defined using contain()

Parameters

Cake\ORM\Table $parent
owning side of the association
string $alias
name of the association to be loaded
array $options
list of extra options to use for this association
array $paths

An array with two values, the first one is a list of dot separated strings representing associations that lead to this $alias in the chain of associations to be loaded. The second value is the path to follow in entities' properties to fetch a record of the corresponding association.

Returns

Cake\ORM\EagerLoadable
Object with normalized associations

Throws

InvalidArgumentException
When containments refer to associations that do not exist.

_reformatContain()source protected

_reformatContain( array $associations , array $original )

Formats the containments array so that associations are always set as keys in the array. This function merges the original associations array with the new associations provided

Parameters

array $associations
user provided containments array
array $original

The original containments array to merge with the new one

Returns

array

_resolveJoins()source protected

_resolveJoins( array $associations , array $matching [] )

Helper function used to compile a list of all associations that can be joined in the query.

Parameters

array $associations
list of associations from which to obtain joins.
array $matching optional []
list of associations that should be forcibly joined.

Returns

array

addToJoinsMap()source public

addToJoinsMap( string $alias , Cake\ORM\Association $assoc , boolean $asMatching false , string $targetProperty null )

Registers a table alias, typically loaded as a join in a query, as belonging to an association. This helps hydrators know what to do with the columns coming from such joined table.

Parameters

string $alias
The table alias as it appears in the query.
Cake\ORM\Association $assoc

The association object the alias represents; will be normalized

boolean $asMatching optional false

Whether or not this join results should be treated as a 'matching' association.

string $targetProperty optional null

The property name where the results of the join should be nested at. If not passed, the default property for the association will be used.

associationsMap()source public

associationsMap( Cake\ORM\Table $table )

Returns an array having as keys a dotted path of associations that participate in this eager loader. The values of the array will contain the following keys

  • alias: The association alias
  • instance: The association instance
  • canBeJoined: Whether or not the association will be loaded using a JOIN
  • entityClass: The entity that should be used for hydrating the results
  • nestKey: A dotted path that can be used to correctly insert the data into the results.
  • matching: Whether or not it is an association loaded through matching().

Parameters

Cake\ORM\Table $table

The table containing the association that will be normalized

Returns

array

attachAssociations()source public

attachAssociations( Cake\ORM\Query $query , Cake\ORM\Table $repository , boolean $includeFields )

Modifies the passed query to apply joins or any other transformation required in order to eager load the associations described in the contain array. This method will not modify the query for loading external associations, i.e. those that cannot be loaded without executing a separate query.

Parameters

Cake\ORM\Query $query
The query to be modified
Cake\ORM\Table $repository
The repository containing the associations
boolean $includeFields

whether to append all fields from the associations to the passed query. This can be overridden according to the settings defined per association in the containments array

attachableAssociations()source public

attachableAssociations( Cake\ORM\Table $repository )

Returns an array with the associations that can be fetched using a single query, the array keys are the association aliases and the values will contain an array with Cake\ORM\EagerLoadable objects.

Parameters

Cake\ORM\Table $repository

The table containing the associations to be attached

Returns

array

autoFields()source public

autoFields( boolean|null $enable null )

Sets/Gets whether or not contained associations will load fields automatically.

Deprecated

3.4.0 Use enableAutoFields()/isAutoFieldsEnabled() instead.

Parameters

boolean|null $enable optional null
The value to set.

Returns

boolean
The current value.

clearContain()source public

clearContain( )

Remove any existing non-matching based containments.

This will reset/clear out any contained associations that were not added via matching().

contain()source public

contain( array|string $associations [] , callable $queryBuilder null )

Sets the list of associations that should be eagerly loaded along for a specific table using when a query is provided. The list of associated tables passed to this method must have been previously set as associations using the Table API.

Associations can be arbitrarily nested using dot notation or nested arrays, this allows this object to calculate joins or any additional queries that must be executed to bring the required associated data.

Accepted options per passed association:

  • foreignKey: Used to set a different field to match both tables, if set to false no join conditions will be generated automatically
  • fields: An array with the fields that should be fetched from the association
  • queryBuilder: Equivalent to passing a callable instead of an options array
  • matching: Whether to inform the association class that it should filter the main query by the results fetched by that class.
  • joinType: For joinable associations, the SQL join type to use.
  • strategy: The loading strategy to use (join, select, subquery)

Parameters

array|string $associations optional []

list of table aliases to be queried. When this method is called multiple times it will merge previous list with the new one.

callable $queryBuilder optional null
The query builder callable

Returns

array
Containments.

Throws

InvalidArgumentException
When using $queryBuilder with an array of $associations

enableAutoFields()source public

enableAutoFields( boolean $enable true )

Sets whether or not contained associations will load fields automatically.

Parameters

boolean $enable optional true
The value to set.

Returns


$this

externalAssociations()source public

externalAssociations( Cake\ORM\Table $repository )

Returns an array with the associations that need to be fetched using a separate query, each array value will contain a Cake\ORM\EagerLoadable object.

Parameters

Cake\ORM\Table $repository

The table containing the associations to be loaded

Returns

Cake\ORM\EagerLoadable[]

getMatching()source public

getMatching( )

Returns the current tree of associations to be matched.

Returns

array
The resulting containments array

isAutoFieldsEnabled()source public

isAutoFieldsEnabled( )

Gets whether or not contained associations will load fields automatically.

Returns

boolean
The current value.

loadExternal()source public

loadExternal( Cake\ORM\Query $query , Cake\Database\StatementInterface $statement )

Decorates the passed statement object in order to inject data from associations that cannot be joined directly.

Parameters

Cake\ORM\Query $query

The query for which to eager load external associations

Cake\Database\StatementInterface $statement
The statement created after executing the $query

Returns

Cake\Database\StatementInterface
statement modified statement with extra loaders

matching()source public

matching( string|null $assoc null , callable $builder null , array $options [] )

Adds a new association to the list that will be used to filter the results of any given query based on the results of finding records for that association. You can pass a dot separated path of associations to this method as its first parameter, this will translate in setting all those associations with the matching option.

If called with no arguments it will return the current tree of associations to be matched.

Deprecated

3.4.0 Use setMatching()/getMatching() instead.

Parameters

string|null $assoc optional null
A single association or a dot separated path of associations.
callable $builder optional null

the callback function to be used for setting extra options to the filtering query

array $options optional []

Extra options for the association matching, such as 'joinType' and 'fields'

Returns

array
The resulting containments array

normalized()source public

normalized( Cake\ORM\Table $repository )

Returns the fully normalized array of associations that should be eagerly loaded for a table. The normalized array will restructure the original array by sorting all associations under one key and special options under another.

Each of the levels of the associations tree will converted to a Cake\ORM\EagerLoadable object, that contains all the information required for the association objects to load the information from the database.

Additionally it will set an 'instance' key per association containing the association instance from the corresponding source table

Parameters

Cake\ORM\Table $repository

The table containing the association that will be normalized

Returns

array

setMatching()source public

setMatching( string $assoc , callable $builder null , array $options [] )

Adds a new association to the list that will be used to filter the results of any given query based on the results of finding records for that association. You can pass a dot separated path of associations to this method as its first parameter, this will translate in setting all those associations with the matching option.

Options

  • 'joinType': INNER, OUTER, ...
  • 'fields': Fields to contain

Parameters

string $assoc
A single association or a dot separated path of associations.
callable $builder optional null

the callback function to be used for setting extra options to the filtering query

array $options optional []
Extra options for the association matching.

Returns


$this

Properties detail

$_aliasListsource

protected array

Contains a list of the association names that are to be eagerly loaded

[]

$_autoFieldssource

protected boolean

Controls whether or not fields from associated tables will be eagerly loaded. When set to false, no fields will be loaded from associations.

true

$_containOptionssource

protected array

List of options accepted by associations in contain() index by key for faster access

[
    'associations' => 1,
    'foreignKey' => 1,
    'conditions' => 1,
    'fields' => 1,
    'sort' => 1,
    'matching' => 1,
    'queryBuilder' => 1,
    'finder' => 1,
    'joinType' => 1,
    'strategy' => 1,
    'negateMatch' => 1
]

$_containmentssource

protected array

Nested array describing the association to be fetched and the options to apply for each of them, if any

[]

$_joinsMapsource

protected array

A map of table aliases pointing to the association objects they represent for the query.

[]

$_loadExternalsource

protected Cake\ORM\EagerLoadable[]

A list of associations that should be loaded with a separate query

[]

$_matchingsource

protected Cake\ORM\EagerLoader

Another EagerLoader instance that will be used for 'matching' associations.

$_normalizedsource

protected Cake\ORM\EagerLoadable[]|Cake\ORM\EagerLoadable|null

Contains a nested array with the compiled containments tree This is a normalized version of the user provided containments array.

© 2005–2017 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.4/class-Cake.ORM.EagerLoader.html