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.
arrayContains a list of the association names that are to be eagerly loaded
boolControls whether fields from associated tables will be eagerly loaded. When set to false, no fields will be loaded from associations.
array<string, int>List of options accepted by associations in contain() index by key for faster access
array<string, mixed>Nested array describing the association to be fetched and the options to apply for each of them, if any
array<string,Cake\ORM\EagerLoadable>A map of table aliases pointing to the association objects they represent for the query.
arrayCake\ORM\EagerLoadable>A list of associations that should be loaded with a separate query
Cake\ORM\EagerLoader|nullAnother EagerLoader instance that will be used for 'matching' associations.
Cake\ORM\EagerLoadable|arrayCake\ORM\EagerLoadable>|nullContains a nested array with the compiled containments tree This is a normalized version of the user provided containments array.
Handles cloning eager loaders and eager loadables.
An internal method to build a map which is used for the return value of the associationsMap() method.
Helper function used to return the keys from the query records that will be used to eagerly load associations.
Changes the association fetching strategy if required because of duplicate under the same direct associations chain
Iterates over the joinable aliases list and corrects the fetching strategies in order to avoid aliases collision in the generated queries.
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()
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
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.
Remove any existing non-matching based containments.
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.
Disable auto loading fields of contained associations.
Sets whether 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 {@link \Cake\ORM\EagerLoadable} object.
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 the current tree of associations to be matched.
Gets whether contained associations will load fields automatically.
Decorates the passed statement object in order to inject data from associations that cannot be joined directly.
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.
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.
__clone(): void
Handles cloning eager loaders and eager loadables.
void_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.
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().
array_collectKeys(arrayCake\ORM\EagerLoadable> $external, Cake\ORM\Query $query, Cake\Database\StatementInterface $statement): array
Helper function used to return the keys from the query records that will be used to eagerly load associations.
arrayCake\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
array_correctStrategy(Cake\ORM\EagerLoadable $loadable): void
Changes the association fetching strategy if required because of duplicate under the same direct associations chain
Cake\ORM\EagerLoadable $loadable The association config
void_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.
void_groupKeys(Cake\Database\Statement\BufferedStatement $statement, array<string, array> $collectKeys): array
Helper function used to iterate a statement and extract the columns defined in $collectKeys
Cake\Database\Statement\BufferedStatement $statement The statement to read from.
array<string, array> $collectKeys The keys to collect
array_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()
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.
Cake\ORM\EagerLoadableInvalidArgumentException_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
array $associations user provided containments array
array $original The original containments array to merge with the new one
array_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.
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.
arrayCake\ORM\EagerLoadable>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.
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.
voidassociationsMap(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
matching().Cake\ORM\Table $table The table containing the association that will be normalized
arrayattachAssociations(Cake\ORM\Query $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.
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
voidattachableAssociations(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.
Cake\ORM\Table $repository The table containing the associations to be attached
arrayCake\ORM\EagerLoadable>clearContain(): void
Remove any existing non-matching based containments.
This will reset/clear out any contained associations that were not added via matching().
voidcontain(array|string $associations, callable|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:
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
arrayInvalidArgumentExceptiondisableAutoFields(): $this
Disable auto loading fields of contained associations.
$thisenableAutoFields(bool $enable = true): $this
Sets whether contained associations will load fields automatically.
bool $enable optional The value to set.
$thisexternalAssociations(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.
Cake\ORM\Table $repository The table containing the associations to be loaded
arrayCake\ORM\EagerLoadable>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.
arraygetMatching(): array
Returns the current tree of associations to be matched.
arrayisAutoFieldsEnabled(): bool
Gets whether contained associations will load fields automatically.
boolloadExternal(Cake\ORM\Query $query, Cake\Database\StatementInterface $statement): Cake\Database\StatementInterface
Decorates the passed statement object in order to inject data from associations that cannot be joined directly.
Cake\ORM\Query $query The query for which to eager load external associations
Cake\Database\StatementInterface $statement The statement created after executing the $query
Cake\Database\StatementInterfaceRuntimeExceptionnormalized(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
Cake\ORM\Table $repository The table containing the association that will be normalized
arraysetMatching(string $associationPath, callable|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.
joinType: INNER, OUTER, ... fields: Fields to containnegateMatch: Whether to add conditions negate match on target associationstring $associationPath Dot separated association path, 'Name1.Name2.Name3'
callable|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.
$thisContains a list of the association names that are to be eagerly loaded
arrayControls whether fields from associated tables will be eagerly loaded. When set to false, no fields will be loaded from associations.
boolList of options accepted by associations in contain() index by key for faster access
array<string, int>Nested array describing the association to be fetched and the options to apply for each of them, if any
array<string, mixed>A map of table aliases pointing to the association objects they represent for the query.
array<string,Cake\ORM\EagerLoadable>A list of associations that should be loaded with a separate query
arrayCake\ORM\EagerLoadable>Another EagerLoader instance that will be used for 'matching' associations.
Cake\ORM\EagerLoader|nullContains a nested array with the compiled containments tree This is a normalized version of the user provided containments array.
Cake\ORM\EagerLoadable|arrayCake\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.4/class-Cake.ORM.EagerLoader.html