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

Property Summary

$_aliasList protected

array

Contains a list of the association names that are to be eagerly loaded.
$_autoFields protected

bool

Controls whether fields from associated tables will be eagerly loaded. When set to false, no fields will be loaded from associations.
$_containOptions protected

array<string, int>

List of options accepted by associations in contain() index by key for faster access.
$_containments protected

array<string, mixed>

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

array<string,Cake\ORM\EagerLoadable>

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

arrayCake\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|arrayCake\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. This method will not modify the query for loading external associations, i.e. those that cannot be loaded without executing a separate query.
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 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 {@link \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 contained associations will load fields automatically.
loadExternal() public

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

__clone(): void

Handles cloning eager loaders and eager loadables.

Returns

void

_buildAssociationsMap() ¶ protected

_buildAssociationsMap(array $map, arrayCake\ORM\EagerLoadable> $level, bool $matching = false): array

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.
arrayCake\ORM\EagerLoadable> $level: An array of EagerLoadable instances.
bool $matching optional: Whether it is an association loaded through matching().

Returns

array

_collectKeys() ¶ protected

_collectKeys(arrayCake\ORM\EagerLoadable> $external, Cake\ORM\Query\SelectQuery $query, array $results): array

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

Parameters

arrayCake\ORM\EagerLoadable> $external: The list of external associations to be loaded.
Cake\ORM\Query\SelectQuery $query: The query from which the results where generated.
array $results: Results array.

Returns

array

_correctStrategy() ¶ protected

_correctStrategy(Cake\ORM\EagerLoadable $loadable): void

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

Parameters

Cake\ORM\EagerLoadable $loadable: The association config.

Returns

void

_fixStrategies() ¶ protected

_fixStrategies(): void

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.

Returns

void

_groupKeys() ¶ protected

_groupKeys(array $results, array<string, array> $collectKeys): array

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

Parameters

array $results: Results array.
array<string, array> $collectKeys: The keys to collect.

Returns

array

_normalizeContain() ¶ protected

_normalizeContain(Cake\ORM\Table $parent, string $alias, array<string, mixed> $options, array<string, mixed> $paths): Cake\ORM\EagerLoadable

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<string, mixed> $options: List of extra options to use for this association.
array<string, mixed> $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

Throws

InvalidArgumentException
When containments refer to associations that do not exist.

_reformatContain() ¶ protected

_reformatContain(array $associations, array $original): array

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(arrayCake\ORM\EagerLoadable> $associations, arrayCake\ORM\EagerLoadable> $matching = []): arrayCake\ORM\EagerLoadable>

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

Parameters

arrayCake\ORM\EagerLoadable> $associations: List of associations from which to obtain joins.
arrayCake\ORM\EagerLoadable> $matching optional: List of associations that should be forcibly joined.

Returns

arrayCake\ORM\EagerLoadable>

addToJoinsMap() ¶ public

addToJoinsMap(string $alias, Cake\ORM\Association $assoc, bool $asMatching = false, string|null $targetProperty = null): void

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 this join results should be treated as a 'matching' association.
string|null $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.

Returns

void

associationsMap() ¶ public

associationsMap(Cake\ORM\Table $table): array

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 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 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\SelectQuery $query, Cake\ORM\Table $repository, bool $includeFields): void

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\SelectQuery $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.

Returns

void

attachableAssociations() ¶ public

attachableAssociations(Cake\ORM\Table $repository): arrayCake\ORM\EagerLoadable>

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

arrayCake\ORM\EagerLoadable>

clearContain() ¶ public

clearContain(): void

Remove any existing non-matching based containments.

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

Returns

void

contain() ¶ public

contain(array|string $associations, Closure|null $queryBuilder = null): array

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 callback 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.
Closure|null $queryBuilder optional: The query builder callback.

Returns

array

Throws

InvalidArgumentException
When using $queryBuilder with an array of $associations

disableAutoFields() ¶ public

disableAutoFields(): $this

Disable auto loading fields of contained associations.

Returns

$this

enableAutoFields() ¶ public

enableAutoFields(bool $enable = true): $this

Sets whether contained associations will load fields automatically.

Parameters

bool $enable optional: The value to set.

Returns

$this

externalAssociations() ¶ public

externalAssociations(Cake\ORM\Table $repository): arrayCake\ORM\EagerLoadable>

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

Parameters

Cake\ORM\Table $repository: The table containing the associations to be loaded.

Returns

arrayCake\ORM\EagerLoadable>

getContain() ¶ public

getContain(): array

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

getMatching() ¶ public

getMatching(): array

Returns the current tree of associations to be matched.

Returns

array

isAutoFieldsEnabled() ¶ public

isAutoFieldsEnabled(): bool

Gets whether contained associations will load fields automatically.

Returns

bool

loadExternal() ¶ public

loadExternal(Cake\ORM\Query\SelectQuery $query, array $results): array

Inject data from associations that cannot be joined directly.

Parameters

Cake\ORM\Query\SelectQuery $query: The query for which to eager load external. associations.
array $results: Results array.

Returns

array

Throws

RuntimeException

normalized() ¶ public

normalized(Cake\ORM\Table $repository): array

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 be converted to a {@link \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 $associationPath, Closure|null $builder = null, array<string, mixed> $options = []): $this

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
- negateMatch: Whether to add conditions negate match on target association

Parameters

string $associationPath: Dot separated association path, 'Name1.Name2.Name3'.
Closure|null $builder optional: the callback function to be used for setting extra options to the filtering query.
array<string, mixed> $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 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<string, int>

`$_containments` ¶ protected

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

Type

array<string, mixed>

`$_joinsMap` ¶ protected

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

Type

array<string,Cake\ORM\EagerLoadable>

`$_loadExternal` ¶ protected

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

Type

arrayCake\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|arrayCake\ORM\EagerLoadable>|null

Namespaces

Class EagerLoader

Property Summary

Method Summary

__clone() public

_buildAssociationsMap() protected

_collectKeys() protected

_correctStrategy() protected

_fixStrategies() protected

_groupKeys() protected

_normalizeContain() protected

_reformatContain() protected

_resolveJoins() protected

addToJoinsMap() public

associationsMap() public

attachAssociations() public

attachableAssociations() public

clearContain() public

contain() public

disableAutoFields() public

enableAutoFields() public

externalAssociations() public

getContain() public

getMatching() public

isAutoFieldsEnabled() public

loadExternal() public

normalized() public

setMatching() public

Method Detail

__clone() ¶ public

Returns

_buildAssociationsMap() ¶ protected

Parameters

Returns

_collectKeys() ¶ protected

Parameters

Returns

_correctStrategy() ¶ protected

Parameters

Returns

_fixStrategies() ¶ protected

Returns

_groupKeys() ¶ protected

Parameters

Returns

_normalizeContain() ¶ protected

Parameters

Returns

Throws

_reformatContain() ¶ protected

Parameters

Returns

_resolveJoins() ¶ protected

Parameters

Returns

addToJoinsMap() ¶ public

Parameters

Returns

associationsMap() ¶ public

Parameters

Returns

attachAssociations() ¶ public

Parameters

Returns

attachableAssociations() ¶ public

Parameters

Returns

clearContain() ¶ public

Returns

contain() ¶ public

Parameters

Returns

Throws

disableAutoFields() ¶ public

Returns

enableAutoFields() ¶ public

Parameters

Returns

externalAssociations() ¶ public

Parameters

`$_aliasList` ¶ protected

`$_autoFields` ¶ protected

`$_containOptions` ¶ protected

`$_containments` ¶ protected

`$_joinsMap` ¶ protected

`$_loadExternal` ¶ protected

`$_matching` ¶ protected

`$_normalized` ¶ protected