Trait ExternalAssociationTrait
Represents a type of association that that needs to be recovered by performing an extra query.
Property Summary
-
$_sort protected
mixedOrder in which target records should be returned
Method Summary
-
_addFilteringCondition() protected
Appends any conditions required to load the relevant set of records in the target table query given a filter key and some filtering values.
-
_addFilteringJoin() public
Appends any conditions required to load the relevant set of records in the target table query given a filter key and some filtering values when the filtering needs to be done using a subquery.
-
_assertFieldsPresent() protected
Checks that the fetching query either has auto fields on or has the foreignKey fields selected. If the required fields are missing, throws an exception.
-
_buildQuery() protected
Auxiliary function to construct a new Query object to return all the records in the target table that are associated to those specified in $options from the source table
-
_buildResultMap() protected
Builds an array containing the results from fetchQuery indexed by the foreignKey value corresponding to this association.
-
_buildSubquery() protected
Builds a query to be used as a condition for filtering records in the target table, it is constructed by cloning the original query that was used to load records in the source table.
-
_createTupleCondition() protected
Returns a TupleComparison object that can be used for matching all the fields from $keys with the tuple values in $filter using the provided operator.
-
_defaultOptions() protected
Returns the default options to use for the eagerLoader
-
_linkField() abstract protected
Generates a string used as a table field that contains the values upon which the filter should be applied
-
_multiKeysInjector() protected
Returns a callable to be used for each row in a query result set for injecting the eager loaded rows when the matching needs to be done with multiple foreign keys
-
_options() protected
Parse extra options passed in the constructor.
-
_resultInjector() protected
Returns a callable to be used for each row in a query result set for injecting the eager loaded rows
-
_subqueryFields() protected
Calculate the fields that need to participate in a subquery.
-
canBeJoined() public
Whether this association can be expressed directly in a query join
-
defaultRowValue() public
{@inheritDoc}
-
eagerLoader() public
{@inheritDoc}
-
foreignKey() public
Sets the name of the field representing the foreign key to the source table. If no parameters are passed current field is returned
-
requiresKeys() public
Returns true if the eager loading process will require a set of the owning table's binding keys in order to use them as a filter in the finder query.
-
sort() public
Sets the sort order in which target records should be returned. If no arguments are passed the currently configured value is returned
Method Detail
_addFilteringCondition() ¶ protected
_addFilteringCondition(Cake\ORM\Query $query, string|array $key, mixed $filter): Cake\ORM\QueryAppends any conditions required to load the relevant set of records in the target table query given a filter key and some filtering values.
Parameters
-
Cake\ORM\Query$query Target table's query
-
string|array$key the fields that should be used for filtering
-
mixed$filter the value that should be used to match for $key
Returns
Cake\ORM\Query_addFilteringJoin() ¶ public
_addFilteringJoin(Cake\ORM\Query $query, string $key, Cake\ORM\Query $subquery): Cake\ORM\QueryAppends any conditions required to load the relevant set of records in the target table query given a filter key and some filtering values when the filtering needs to be done using a subquery.
Parameters
-
Cake\ORM\Query$query Target table's query
-
string$key the fields that should be used for filtering
-
Cake\ORM\Query$subquery The Subquery to use for filtering
Returns
Cake\ORM\Query_assertFieldsPresent() ¶ protected
_assertFieldsPresent(Cake\ORM\Query $fetchQuery, array $key): voidChecks that the fetching query either has auto fields on or has the foreignKey fields selected. If the required fields are missing, throws an exception.
Parameters
-
Cake\ORM\Query$fetchQuery The association fetching query
-
array$key The foreign key fields to check
Returns
voidThrows
InvalidArgumentException_buildQuery() ¶ protected
_buildQuery(array $options): Cake\ORM\QueryAuxiliary function to construct a new Query object to return all the records in the target table that are associated to those specified in $options from the source table
Parameters
-
array$options options accepted by eagerLoader()
Returns
Cake\ORM\QueryThrows
InvalidArgumentExceptionWhen a key is required for associations but not selected.
_buildResultMap() ¶ protected
_buildResultMap(Cake\ORM\Query $fetchQuery, array $options): arrayBuilds an array containing the results from fetchQuery indexed by the foreignKey value corresponding to this association.
Parameters
-
Cake\ORM\Query$fetchQuery -
array$options
Returns
array_buildSubquery() ¶ protected
_buildSubquery(Cake\ORM\Query $query): Cake\ORM\QueryBuilds a query to be used as a condition for filtering records in the target table, it is constructed by cloning the original query that was used to load records in the source table.
Parameters
-
Cake\ORM\Query$query the original query used to load source records
Returns
Cake\ORM\Query_createTupleCondition() ¶ protected
_createTupleCondition(Cake\ORM\Query $query, array $keys, mixed $filter, string $operator): Cake\Database\Expression\TupleComparisonReturns a TupleComparison object that can be used for matching all the fields from $keys with the tuple values in $filter using the provided operator.
Parameters
-
Cake\ORM\Query$query Target table's query
-
array$keys the fields that should be used for filtering
-
mixed$filter the value that should be used to match for $key
-
string$operator The operator for comparing the tuples
Returns
Cake\Database\Expression\TupleComparison_defaultOptions() ¶ protected
_defaultOptions(): arrayReturns the default options to use for the eagerLoader
Returns
array_linkField() ¶ abstract protected
_linkField(array $options): string|arrayGenerates a string used as a table field that contains the values upon which the filter should be applied
Parameters
-
array$options The options for getting the link field.
Returns
string|array_multiKeysInjector() ¶ protected
_multiKeysInjector(array $resultMap, array $sourceKeys, string $nestKey): ClosureReturns a callable to be used for each row in a query result set for injecting the eager loaded rows when the matching needs to be done with multiple foreign keys
Parameters
-
array$resultMap A keyed arrays containing the target table
-
array$sourceKeys An array with aliased keys to match
-
string$nestKey The key under which results should be nested
Returns
Closure_options() ¶ protected
_options(array $opts): voidParse extra options passed in the constructor.
Parameters
-
array$opts original list of options passed in constructor
Returns
void_resultInjector() ¶ protected
_resultInjector(Cake\ORM\Query $fetchQuery, array $resultMap, array $options): ClosureReturns a callable to be used for each row in a query result set for injecting the eager loaded rows
Parameters
-
Cake\ORM\Query$fetchQuery the Query used to fetch results
-
array$resultMap an array with the foreignKey as keys and the corresponding target table results as value.
-
array$options The options passed to the eagerLoader method
Returns
Closure_subqueryFields() ¶ protected
_subqueryFields(Cake\ORM\Query $query): arrayCalculate the fields that need to participate in a subquery.
Normally this includes the binding key columns. If there is a an ORDER BY, those columns are also included as the fields may be calculated or constant values, that need to be present to ensure the correct association data is loaded.
Parameters
-
Cake\ORM\Query$query The query to get fields from.
Returns
arrayThe list of fields for the subquery.
canBeJoined() ¶ public
canBeJoined(array $options = []): boolWhether this association can be expressed directly in a query join
Parameters
-
array$options optional custom options key that could alter the return value
Returns
boolif the 'matching' key in $option is true then this function will return true, false otherwise
defaultRowValue() ¶ public
defaultRowValue(mixed $row, mixed $joined){@inheritDoc}
Parameters
-
$row -
$joined
foreignKey() ¶ public
foreignKey(string|null $key = null): stringSets the name of the field representing the foreign key to the source table. If no parameters are passed current field is returned
Parameters
-
string|null$key optional the key to be used to link both tables together
Returns
stringrequiresKeys() ¶ public
requiresKeys(array $options = []): boolReturns true if the eager loading process will require a set of the owning table's binding keys in order to use them as a filter in the finder query.
Parameters
-
array$options optional The options containing the strategy to be used.
Returns
booltrue if a list of keys will be required
sort() ¶ public
sort(mixed $sort = null): mixedSets the sort order in which target records should be returned. If no arguments are passed the currently configured value is returned
Parameters
-
mixed$sort optional A find() compatible order clause
Returns
mixed