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

Properties summary

  • $_aliasList protected
    array

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

  • $_autoFields protected
    bool

    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
    \Cake\ORM\EagerLoader|null

    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

    Handles cloning eager loaders and eager loadables.

  • _buildAssociationsMap() protected

    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

  • _normalizeContain() protected

    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.

  • addToJoinsMap() public

    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.

  • associationsMap() public

    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

  • attachAssociations() public

    Modifies the passed query to apply joins or any other transformation required in order to eager load the associations described in the contain array.

  • attachableAssociations() public

    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.

  • clearContain() public

    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.

  • disableAutoFields() public

    Disable auto loading fields of contained associations.

  • enableAutoFields() public

    Sets whether or not contained associations will load fields automatically.

  • externalAssociations() public

    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.

  • getContain() public

    Gets 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.

  • getMatching() public

    Returns the current tree of associations to be matched.

  • isAutoFieldsEnabled() public

    Gets whether or not contained associations will load fields automatically.

  • loadExternal() public

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

  • 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.

Method Detail

__clone() public 

__clone()

Handles cloning eager loaders and eager loadables.

_buildAssociationsMap() protected 

_buildAssociationsMap(array $map, array $level, bool $matching)

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.

\Cake\ORM\EagerLoadable[] $level

An array of EagerLoadable instances.

bool $matching optional

Whether or not it is an association loaded through matching().

Returns

array

_collectKeys() protected 

_collectKeys(array $external, \Cake\ORM\Query $query, mixed $statement)

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

Parameters

\Cake\ORM\EagerLoadable[] $external

the list of external associations to be loaded

\Cake\ORM\Query $query

The query from which the results where generated

\Cake\Database\StatementInterface $statement

The statement to work on

Returns

array

_correctStrategy() 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() 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() 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() 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() 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() protected 

_resolveJoins(array $associations, array $matching)

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

Parameters

\Cake\ORM\EagerLoadable[] $associations

list of associations from which to obtain joins.

\Cake\ORM\EagerLoadable[] $matching optional

list of associations that should be forcibly joined.

Returns

\Cake\ORM\EagerLoadable[]

addToJoinsMap() public 

addToJoinsMap(string $alias, \Cake\ORM\Association $assoc, bool $asMatching, ?string $targetProperty)

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

bool $asMatching optional

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

string $targetProperty optional

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() 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() public 

attachAssociations(\Cake\ORM\Query $query, \Cake\ORM\Table $repository, bool $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

bool $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() 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

\Cake\ORM\EagerLoadable[]

clearContain() public 

clearContain()

Remove any existing non-matching based containments.

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

contain() public 

contain(mixed $associations, ?callable $queryBuilder)

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

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

callable|null $queryBuilder optional

The query builder callable

Returns

array

Containments.

Throws

InvalidArgumentException
When using $queryBuilder with an array of $associations

disableAutoFields() public 

disableAutoFields()

Disable auto loading fields of contained associations.

Returns

$this

enableAutoFields() public 

enableAutoFields(bool $enable)

Sets whether or not contained associations will load fields automatically.

Parameters

bool $enable optional

The value to set.

Returns

$this

externalAssociations() 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[]

getContain() public 

getContain()

Gets 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.

Returns

array

Containments.

getMatching() public 

getMatching()

Returns the current tree of associations to be matched.

Returns

array

The resulting containments array

isAutoFieldsEnabled() public 

isAutoFieldsEnabled()

Gets whether or not contained associations will load fields automatically.

Returns

bool

The current value.

loadExternal() 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

Throws

RuntimeException

normalized() 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() public 

setMatching(string $assoc, ?callable $builder, 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|null $builder optional

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

Property Detail

$_aliasList protected

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

Type

array

$_autoFields protected

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

Type

bool

$_containOptions protected

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

Type

array

$_containments protected

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

Type

array

$_joinsMap protected

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

Type

array

$_loadExternal protected

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

Type

\Cake\ORM\EagerLoadable[]

$_matching protected

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

Type

\Cake\ORM\EagerLoader|null

$_normalized protected

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

Type

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

© 2005–present 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/4.1/class-Cake.ORM.EagerLoader.html