Fr3nch13/CakePHP Utilities

EagerLoader
in package

Application

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.

Properties

$_aliasList : array<string|int, mixed>: Contains a list of the association names that are to be eagerly loaded
$_autoFields : bool: Controls whether fields from associated tables will be eagerly loaded. When set to false, no fields will be loaded from associations.
$_containments : array<string, mixed>: Nested array describing the association to be fetched and the options to apply for each of them, if any
$_containOptions : array<string, int>: List of options accepted by associations in contain() index by key for faster access
$_joinsMap : array<string, EagerLoadable>: A map of table aliases pointing to the association objects they represent for the query.
$_loadExternal : array<string|int, EagerLoadable>: A list of associations that should be loaded with a separate query
$_matching : EagerLoader|null: Another EagerLoader instance that will be used for 'matching' associations.
$_normalized : EagerLoadable|array<string|int, EagerLoadable>|null: Contains a nested array with the compiled containments tree This is a normalized version of the user provided containments array.

Methods

__clone() : void: Handles cloning eager loaders and eager loadables.
addToJoinsMap() : 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.
associationsMap() : array<string|int, mixed>: 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
attachableAssociations() : array<string|int, 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.
attachAssociations() : 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.
clearContain() : void: Remove any existing non-matching based containments.
contain() : array<string|int, mixed>: 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() : $this: Disable auto loading fields of contained associations.
enableAutoFields() : $this: Sets whether contained associations will load fields automatically.
externalAssociations() : array<string|int, 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.
getContain() : array<string|int, mixed>: 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() : array<string|int, mixed>: Returns the current tree of associations to be matched.
isAutoFieldsEnabled() : bool: Gets whether contained associations will load fields automatically.
loadExternal() : StatementInterface: Decorates the passed statement object in order to inject data from associations that cannot be joined directly.
normalized() : array<string|int, mixed>: 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() : $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.
_buildAssociationsMap() : array<string|int, mixed>: An internal method to build a map which is used for the return value of the associationsMap() method.
_collectKeys() : array<string|int, mixed>: Helper function used to return the keys from the query records that will be used to eagerly load associations.
_correctStrategy() : void: Changes the association fetching strategy if required because of duplicate under the same direct associations chain
_fixStrategies() : void: Iterates over the joinable aliases list and corrects the fetching strategies in order to avoid aliases collision in the generated queries.
_groupKeys() : array<string|int, mixed>: Helper function used to iterate a statement and extract the columns defined in $collectKeys
_normalizeContain() : EagerLoadable: Auxiliary function responsible for fully normalizing deep associations defined using `contain()`
_reformatContain() : array<string|int, mixed>: 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() : array<string|int, EagerLoadable>: Helper function used to compile a list of all associations that can be joined in the query.

$_aliasList

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


    protected
        array<string|int, mixed>
    $_aliasList
     = []

$_autoFields

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


    protected
        bool
    $_autoFields
     = true

$_containments

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


    protected
        array<string, mixed>
    $_containments
     = []

$_containOptions

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


    protected
        array<string, int>
    $_containOptions
     = ['associations' => 1, 'foreignKey' => 1, 'conditions' => 1, 'fields' => 1, 'sort' => 1, 'matching' => 1, 'queryBuilder' => 1, 'finder' => 1, 'joinType' => 1, 'strategy' => 1, 'negateMatch' => 1]

$_joinsMap

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


    protected
        array<string, EagerLoadable>
    $_joinsMap
     = []

$_loadExternal

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


    protected
        array<string|int, EagerLoadable>
    $_loadExternal
     = []

$_matching

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


    protected
        EagerLoader|null
    $_matching

$_normalized

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


    protected
        EagerLoadable|array<string|int, EagerLoadable>|null
    $_normalized

__clone()

Handles cloning eager loaders and eager loadables.


    public
                    __clone() : void

addToJoinsMap()

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.


    public
                    addToJoinsMap(string $alias, Association $assoc[, bool $asMatching = false ][, string|null $targetProperty = null ]) : void

Parameters

$alias : string: The table alias as it appears in the query.
$assoc : Association: The association object the alias represents; will be normalized
$asMatching : bool = false: Whether this join results should be treated as a 'matching' association.
$targetProperty : string|null = 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()

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


    public
                    associationsMap(Table $table) : array<string|int, mixed>

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

$table : Table: The table containing the association that will be normalized

Return values

array<string|int, mixed>

attachableAssociations()

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.


    public
                    attachableAssociations(Table $repository) : array<string|int, EagerLoadable>

Parameters

$repository : Table: The table containing the associations to be attached

Return values

array<string|int, EagerLoadable>

attachAssociations()

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


    public
                    attachAssociations(Query $query, Table $repository, bool $includeFields) : void

This method will not modify the query for loading external associations, i.e. those that cannot be loaded without executing a separate query.

Parameters

$query : Query: The query to be modified
$repository : Table: The repository containing the associations
$includeFields : bool: 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

clearContain()

Remove any existing non-matching based containments.


    public
                    clearContain() : void

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

contain()

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.


    public
                    contain(array<string|int, mixed>|string $associations[, callable|null $queryBuilder = null ]) : array<string|int, mixed>

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

$associations : array<string|int, mixed>|string: list of table aliases to be queried. When this method is called multiple times it will merge previous list with the new one.
$queryBuilder : callable|null = null: The query builder callable

Return values

array<string|int, mixed> —

Containments.

disableAutoFields()

Disable auto loading fields of contained associations.


    public
                    disableAutoFields() : $this

Return values

$this

enableAutoFields()

Sets whether contained associations will load fields automatically.


    public
                    enableAutoFields([bool $enable = true ]) : $this

Parameters

$enable : bool = true: The value to set.

Return values

$this

externalAssociations()

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.


    public
                    externalAssociations(Table $repository) : array<string|int, EagerLoadable>

Parameters

$repository : Table: The table containing the associations to be loaded

Return values

array<string|int, EagerLoadable>

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.


    public
                    getContain() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Containments.

getMatching()

Returns the current tree of associations to be matched.


    public
                    getMatching() : array<string|int, mixed>

Return values

array<string|int, mixed> —

The resulting containments array

isAutoFieldsEnabled()

Gets whether contained associations will load fields automatically.


    public
                    isAutoFieldsEnabled() : bool

Return values

bool —

The current value.

loadExternal()

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


    public
                    loadExternal(Query $query, StatementInterface $statement) : StatementInterface

Parameters

$query : Query: The query for which to eager load external associations
$statement : StatementInterface: The statement created after executing the $query

Return values

StatementInterface —

statement modified statement with extra loaders

normalized()

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.


    public
                    normalized(Table $repository) : array<string|int, mixed>

Each of the levels of the associations tree will be converted to a 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

$repository : Table: The table containing the association that will be normalized

Return values

array<string|int, mixed>

setMatching()

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.


    public
                    setMatching(string $associationPath[, callable|null $builder = null ][, array<string, mixed> $options = [] ]) : $this

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

$associationPath : string: Dot separated association path, 'Name1.Name2.Name3'
$builder : callable|null = null: the callback function to be used for setting extra options to the filtering query
$options : array<string, mixed> = []: Extra options for the association matching.

Return values

$this

_buildAssociationsMap()

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


    protected
                    _buildAssociationsMap(array<string|int, mixed> $map, array<string|int, EagerLoadable> $level[, bool $matching = false ]) : array<string|int, mixed>

Parameters

$map : array<string|int, mixed>: An initial array for the map.
$level : array<string|int, EagerLoadable>: An array of EagerLoadable instances.
$matching : bool = false: Whether it is an association loaded through matching().

Return values

array<string|int, mixed>

_collectKeys()

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


    protected
                    _collectKeys(array<string|int, EagerLoadable> $external, Query $query, StatementInterface $statement) : array<string|int, mixed>

Parameters

$external : array<string|int, EagerLoadable>: the list of external associations to be loaded
$query : Query: The query from which the results where generated
$statement : StatementInterface: The statement to work on

Return values

array<string|int, mixed>

_correctStrategy()

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


    protected
                    _correctStrategy(EagerLoadable $loadable) : void

Parameters

$loadable : EagerLoadable: The association config

_fixStrategies()

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


    protected
                    _fixStrategies() : void

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

_groupKeys()

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


    protected
                    _groupKeys(BufferedStatement $statement, array<string, array<string|int, mixed>> $collectKeys) : array<string|int, mixed>

Parameters

$statement : BufferedStatement: The statement to read from.
$collectKeys : array<string, array<string|int, mixed>>: The keys to collect

Return values

array<string|int, mixed>

_normalizeContain()

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


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

Parameters

$parent : Table: owning side of the association
$alias : string: name of the association to be loaded
$options : array<string, mixed>: list of extra options to use for this association
$paths : array<string, mixed>: 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.

Return values

EagerLoadable —

Object with normalized associations

_reformatContain()

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


    protected
                    _reformatContain(array<string|int, mixed> $associations, array<string|int, mixed> $original) : array<string|int, mixed>

Parameters

$associations : array<string|int, mixed>: user provided containments array
$original : array<string|int, mixed>: The original containments array to merge with the new one

Return values

array<string|int, mixed>

_resolveJoins()

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


    protected
                    _resolveJoins(array<string|int, EagerLoadable> $associations[, array<string|int, EagerLoadable> $matching = [] ]) : array<string|int, EagerLoadable>

Parameters

$associations : array<string|int, EagerLoadable>: list of associations from which to obtain joins.
$matching : array<string|int, EagerLoadable> = []: list of associations that should be forcibly joined.

Return values

array<string|int, EagerLoadable>

EagerLoader in package Application

Table of Contents

Properties

Methods

Properties

$_aliasList

$_autoFields

$_containments

$_containOptions

$_joinsMap

$_loadExternal

$_matching

$_normalized

Methods

__clone()

addToJoinsMap()

Parameters

associationsMap()

Parameters

Return values

attachableAssociations()

Parameters

Return values

attachAssociations()

Parameters

clearContain()

contain()

Parameters

Tags

Return values

disableAutoFields()

Return values

enableAutoFields()

Parameters

Return values

externalAssociations()

Parameters

Return values

getContain()

Return values

getMatching()

Return values

isAutoFieldsEnabled()

Return values

loadExternal()

Parameters

Tags

Return values

normalized()

Parameters

Return values

setMatching()

Options

Parameters

Return values

_buildAssociationsMap()

Parameters

Return values

_collectKeys()

Parameters

Return values

_correctStrategy()

Parameters

_fixStrategies()

_groupKeys()

Parameters

Return values

_normalizeContain()

Parameters

Tags

Return values

_reformatContain()

Parameters

Return values

_resolveJoins()

Parameters

Return values

EagerLoader
in package

Application