Class BelongsTo
Represents an 1 - N relationship where the source side of the relation is related to only one record in the target table.
An example of a BelongsTo association would be Article belongs to Author.
- Cake\ORM\Association uses Cake\Core\ConventionsTrait , Cake\ORM\Locator\LocatorAwareTrait
-
Cake\ORM\Association\BelongsTo
Inherited Constants
Properties summary
-
$_validStrategiesprotectedarrayValid strategies for this type of association
Inherited Properties
Method Summary
-
_joinCondition() protected
Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.
-
_propertyName() protected
Returns default property name based on association name. -
cascadeDelete() public
Handle cascading deletes. -
eagerLoader() public
Eager loads a list of records in the target table that are related to another set of records in the source table. Source records can specified in two ways: first one is by passing a Query object setup to find on the source table and the other way is by explicitly passing an array of primary key values from the source table.
-
getForeignKey() public
Gets the name of the field representing the foreign key to the target table. -
isOwningSide() public
Returns whether or not the passed table is the owning side for this association. This means that rows in the 'target' table would miss important or required information if the row in 'source' did not exist.
-
saveAssociated() public
Takes an entity from the source table and looks if there is a field matching the property name for this association. The found entity will be saved on the target table for this association by passing supplied
$options -
type() public
Get the relationship type.
Method Detail
_joinCondition() protected ¶
_joinCondition( array $options )
Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.
Parameters
- array $options
- list of options passed to attachTo method
Returns
Throws
if the number of columns in the foreignKey do not match the number of columns in the target table primaryKey
Overrides
_propertyName() protected ¶
_propertyName( )
Returns default property name based on association name.
Returns
Overrides
cascadeDelete() public ¶
cascadeDelete( Cake\Datasource\EntityInterface $entity , array $options [] )
Handle cascading deletes.
BelongsTo associations are never cleared in a cascading delete scenario.
Parameters
-
Cake\Datasource\EntityInterface$entity - The entity that started the cascaded delete.
- array $options optional []
- The options for the original delete.
Returns
Success.
eagerLoader() public ¶
eagerLoader( array $options )
Eager loads a list of records in the target table that are related to another set of records in the source table. Source records can specified in two ways: first one is by passing a Query object setup to find on the source table and the other way is by explicitly passing an array of primary key values from the source table.
Parameters
- array $options
- The options for eager loading.
Returns
getForeignKey() public ¶
getForeignKey( )
Gets the name of the field representing the foreign key to the target table.
Returns
Overrides
isOwningSide() public ¶
isOwningSide( Cake\ORM\Table $side )
Returns whether or not the passed table is the owning side for this association. This means that rows in the 'target' table would miss important or required information if the row in 'source' did not exist.
Parameters
-
Cake\ORM\Table$side - The potential Table with ownership
Returns
saveAssociated() public ¶
saveAssociated( Cake\Datasource\EntityInterface $entity , array $options [] )
Takes an entity from the source table and looks if there is a field
matching the property name for this association. The found entity will be
saved on the target table for this association by passing supplied
$options
Parameters
-
Cake\Datasource\EntityInterface$entity - an entity from the source table
- array $options optional []
- options to be passed to the save method in the target table
Returns
Cake\Datasource\EntityInterfacefalse if $entity could not be saved, otherwise it returns the saved entity
See
Methods inherited from Cake\ORM\Association
__call() public ¶
__call( string $method , array $argument )
Proxies method calls to the target table.
Parameters
- string $method
- name of the method to be invoked
- array $argument
- List of arguments passed to the function
Returns
Throws
__construct() public ¶
__construct( string $alias , array $options [] )
Constructor. Subclasses can override _options function to get the original list of passed options if expecting any other special key
Parameters
- string $alias
- The name given to the association
- array $options optional []
- A list of properties to be set on this object
__get() public ¶
__get( string $property )
Proxies property retrieval to the target table. This is handy for getting this association's associations
Parameters
- string $property
- the property name
Returns
Throws
if no association with such name exists
__isset() public ¶
__isset( string $property )
Proxies the isset call to the target table. This is handy to check if the target table has another association with the passed name
Parameters
- string $property
- the property name
Returns
true if the property exists
_appendFields() protected ¶
_appendFields( Cake\ORM\Query $query , Cake\ORM\Query $surrogate , array $options )
Helper function used to conditionally append fields to the select clause of a query from the fields found in another query object.
Parameters
-
Cake\ORM\Query$query - the query that will get the fields appended to
-
Cake\ORM\Query$surrogate - the query having the fields to be copied from
- array $options
- options passed to the method
attachTo
_appendNotMatching() protected ¶
_appendNotMatching( Cake\Datasource\QueryInterface $query , array $options )
Conditionally adds a condition to the passed Query that will make it find records where there is no match with this association.
Parameters
-
Cake\Datasource\QueryInterface$query - The query to modify
- array $options
- Options array containing the
negateMatchkey.
_bindNewAssociations() protected ¶
_bindNewAssociations( Cake\ORM\Query $query , Cake\ORM\Query $surrogate , array $options )
Applies all attachable associations to $query out of the containments found
in the $surrogate query.
Copies all contained associations from the $surrogate query into the
passed $query. Containments are altered so that they respect the associations
chain from which they originated.
Parameters
-
Cake\ORM\Query$query - the query that will get the associations attached to
-
Cake\ORM\Query$surrogate - the query having the containments to be attached
- array $options
- options passed to the method
attachTo
_dispatchBeforeFind() protected ¶
_dispatchBeforeFind( Cake\ORM\Query $query )
Triggers beforeFind on the target table for the query this association is attaching to
Parameters
-
Cake\ORM\Query$query - the query this association is attaching itself to
_extractFinder() protected ¶
_extractFinder( string|array $finderData )
Helper method to infer the requested finder and its options.
Returns the inferred options from the finder $type.
Examples:
The following will call the finder 'translations' with the value of the finder as its options: $query->contain(['Comments' => ['finder' => ['translations']]]); $query->contain(['Comments' => ['finder' => ['translations' => []]]]); $query->contain(['Comments' => ['finder' => ['translations' => ['locales' => ['en_US']]]]]);
Parameters
- string|array $finderData
The finder name or an array having the name as key and options as value.
Returns
_formatAssociationResults() protected ¶
_formatAssociationResults( Cake\ORM\Query $query , Cake\ORM\Query $surrogate , array $options )
Adds a formatter function to the passed $query if the $surrogate query
declares any other formatter. Since the $surrogate query correspond to
the associated target table, the resulting formatter will be the result of
applying the surrogate formatters to only the property corresponding to
such table.
Parameters
-
Cake\ORM\Query$query - the query that will get the formatter applied to
-
Cake\ORM\Query$surrogate the query having formatters for the associated target table.
- array $options
- options passed to the method
attachTo
_getClassName() protected ¶
_getClassName( string $alias , array $options [] )
Gets the table class name.
Parameters
- string $alias
- The alias name you want to get.
- array $options optional []
- Table options array.
Returns
_options() protected ¶
_options( array $options )
Override this function to initialize any concrete association class, it will get passed the original list of options used in the constructor
Parameters
- array $options
- List of options used for initialization
attachTo() public ¶
attachTo( Cake\ORM\Query $query , array $options [] )
Alters a Query object to include the associated target table data in the final result
The options array accept the following keys:
- includeFields: Whether to include target model fields in the result or not
- foreignKey: The name of the field to use as foreign key, if false none will be used
- conditions: array with a list of conditions to filter the join with, this will be merged with any conditions originally configured for this association
- fields: a list of fields in the target table to include in the result
- type: The type of join to be used (e.g. INNER) the records found on this association
- aliasPath: A dot separated string representing the path of association names followed from the passed query main table to this association.
- propertyPath: A dot separated string representing the path of association properties to be followed from the passed query main entity to this association
- joinType: The SQL join type to use in the query.
- negateMatch: Will append a condition to the passed query for excluding matches. with this association.
Parameters
-
Cake\ORM\Query$query - the query to be altered to include the target table data
- array $options optional []
- Any extra options or overrides to be taken in account
Throws
if the query builder passed does not return a query object
bindingKey() public ¶
bindingKey( string|null $key null )
Sets the name of the field representing the binding field with the target table. When not manually specified the primary key of the owning side table is used.
If no parameters are passed the current field is returned
Deprecated
Parameters
- string|null $key optional null
- the table field to be used to link both tables together
Returns
canBeJoined() public ¶
canBeJoined( array $options [] )
Whether this association can be expressed directly in a query join
Parameters
- array $options optional []
- custom options key that could alter the return value
Returns
cascadeCallbacks() public ¶
cascadeCallbacks( boolean|null $cascadeCallbacks null )
Sets whether or not cascaded deletes should also fire callbacks. If no arguments are passed, the current configured value is returned
Deprecated
Parameters
- boolean|null $cascadeCallbacks optional null
- cascade callbacks switch value
Returns
className() public ¶
className( )
The class name of the target table object
Deprecated
Returns
conditions() public ¶
conditions( array|null $conditions null )
Sets a list of conditions to be always included when fetching records from the target association. If no parameters are passed the current list is returned
Deprecated
Parameters
- array|null $conditions optional null
- list of conditions to be used
Returns
See
defaultRowValue() public ¶
defaultRowValue( array $row , boolean $joined )
Returns a modified row after appending a property for this association with the default empty value according to whether the association was joined or fetched externally.
Parameters
- array $row
- The row to set a default on.
- boolean $joined
Whether or not the row is a result of a direct join with this association
Returns
deleteAll() public ¶
deleteAll( mixed $conditions )
Proxies the delete operation to the target table's deleteAll method
Parameters
- mixed $conditions
Conditions to be used, accepts anything Query::where() can take.
Returns
Returns the number of affected rows.
See
dependent() public ¶
dependent( boolean|null $dependent null )
Sets whether the records on the target table are dependent on the source table.
This is primarily used to indicate that records should be removed if the owning record in the source table is deleted.
If no parameters are passed the current setting is returned.
Deprecated
Parameters
- boolean|null $dependent optional null
- Set the dependent mode. Use null to read the current state.
Returns
exists() public ¶
exists( array|callable|Cake\Database\ExpressionInterface $conditions )
Proxies the operation to the target table's exists method after appending the default conditions for this association
Parameters
-
array|callable|
Cake\Database\ExpressionInterface$conditions The conditions to use for checking if any record matches.
Returns
See
find() public ¶
find( string|array|null $type null , array $options [] )
Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration
Parameters
- string|array|null $type optional null
the type of query to perform, if an array is passed, it will be interpreted as the
$optionsparameter- array $options optional []
- The options to for the find
Returns
See
finder() public ¶
finder( string|null $finder null )
Sets the default finder to use for fetching rows from the target table. If no parameters are passed, it will return the currently configured finder name.
Deprecated
Parameters
- string|null $finder optional null
- the finder name to use
Returns
foreignKey() public ¶
foreignKey( string|null $key null )
Sets the name of the field representing the foreign key to the target table. If no parameters are passed the current field is returned
Deprecated
Parameters
- string|null $key optional null
- the key to be used to link both tables together
Returns
getBindingKey() public ¶
getBindingKey( )
Gets the name of the field representing the binding field with the target table. When not manually specified the primary key of the owning side table is used.
Returns
getCascadeCallbacks() public ¶
getCascadeCallbacks( )
Gets whether or not cascaded deletes should also fire callbacks.
Returns
getClassName() public ¶
getClassName( )
Gets the class name of the target table object.
Returns
getConditions() public ¶
getConditions( )
Gets a list of conditions to be always included when fetching records from the target association.
Returns
See
getDependent() public ¶
getDependent( )
Sets whether the records on the target table are dependent on the source table.
This is primarily used to indicate that records should be removed if the owning record in the source table is deleted.
Returns
getFinder() public ¶
getFinder( )
Gets the default finder to use for fetching rows from the target table.
Returns
getJoinType() public ¶
getJoinType( )
Gets the type of join to be used when adding the association to a query.
Returns
getName() public ¶
getName( )
Gets the name for this association, usually the alias assigned to the target associated table
Returns
getProperty() public ¶
getProperty( )
Gets the property name that should be filled with data from the target table in the source table record.
Returns
getStrategy() public ¶
getStrategy( )
Gets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void.
Returns
joinType() public ¶
joinType( string|null $type null )
Sets the type of join to be used when adding the association to a query. If no arguments are passed, the currently configured type is returned.
Deprecated
Parameters
- string|null $type optional null
- the join type to be used (e.g. INNER)
Returns
name() public ¶
name( string|null $name null )
Sets the name for this association.
Deprecated
Parameters
- string|null $name optional null
- Name to be assigned
Returns
property() public ¶
property( string|null $name null )
Sets the property name that should be filled with data from the target table in the source table record. If no arguments are passed, the currently configured type is returned.
Deprecated
Parameters
- string|null $name optional null
- The name of the association property. Use null to read the current value.
Returns
requiresKeys() public ¶
requiresKeys( array $options [] )
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.
Parameters
- array $options optional []
- The options containing the strategy to be used.
Returns
true if a list of keys will be required
setBindingKey() public ¶
setBindingKey( string|array $key )
Sets the name of the field representing the binding field with the target table. When not manually specified the primary key of the owning side table is used.
Parameters
- string|array $key
- the table field or fields to be used to link both tables together
Returns
$this
setCascadeCallbacks() public ¶
setCascadeCallbacks( boolean $cascadeCallbacks )
Sets whether or not cascaded deletes should also fire callbacks.
Parameters
- boolean $cascadeCallbacks
- cascade callbacks switch value
Returns
$this
setClassName() public ¶
setClassName( string $className )
Sets the class name of the target table object.
Parameters
- string $className
- Class name to set.
Returns
$this
Throws
In case the class name is set after the target table has been resolved, and it doesn't match the target table's class name.
setConditions() public ¶
setConditions( array|callable $conditions )
Sets a list of conditions to be always included when fetching records from the target association.
Parameters
- array|callable $conditions
- list of conditions to be used
Returns
$this
See
setDependent() public ¶
setDependent( boolean $dependent )
Sets whether the records on the target table are dependent on the source table.
This is primarily used to indicate that records should be removed if the owning record in the source table is deleted.
If no parameters are passed the current setting is returned.
Parameters
- boolean $dependent
- Set the dependent mode. Use null to read the current state.
Returns
$this
setFinder() public ¶
setFinder( string|array $finder )
Sets the default finder to use for fetching rows from the target table.
Parameters
- string|array $finder
- the finder name to use or array of finder name and option.
Returns
$this
setForeignKey() public ¶
setForeignKey( string|array $key )
Sets the name of the field representing the foreign key to the target table.
Parameters
- string|array $key
- the key or keys to be used to link both tables together
Returns
$this
setJoinType() public ¶
setJoinType( string $type )
Sets the type of join to be used when adding the association to a query.
Parameters
- string $type
- the join type to be used (e.g. INNER)
Returns
$this
setName() public ¶
setName( string $name )
Sets the name for this association, usually the alias assigned to the target associated table
Parameters
- string $name
- Name to be assigned
Returns
$this
setProperty() public ¶
setProperty( string $name )
Sets the property name that should be filled with data from the target table in the source table record.
Parameters
- string $name
- The name of the association property. Use null to read the current value.
Returns
$this
setSource() public ¶
setSource( Cake\ORM\Table $table )
Sets the table instance for the source side of the association.
Parameters
-
Cake\ORM\Table$table - the instance to be assigned as source side
Returns
$this
setStrategy() public ¶
setStrategy( string $name )
Sets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void.
Parameters
- string $name
- The strategy type. Use null to read the current value.
Returns
$this
Throws
When an invalid strategy is provided.
setTarget() public ¶
setTarget( Cake\ORM\Table $table )
Sets the table instance for the target side of the association.
Parameters
-
Cake\ORM\Table$table - the instance to be assigned as target side
Returns
$this
source() public ¶
source( Cake\ORM\Table $table null )
Sets the table instance for the source side of the association. If no arguments are passed, the current configured table instance is returned
Deprecated
Parameters
-
Cake\ORM\Table$table optional null - the instance to be assigned as source side
Returns
strategy() public ¶
strategy( string|null $name null )
Sets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void. If no arguments are passed, the currently configured strategy is returned.
Deprecated
Parameters
- string|null $name optional null
- The strategy type. Use null to read the current value.
Returns
Throws
When an invalid strategy is provided.
target() public ¶
target( Cake\ORM\Table $table null )
Sets the table instance for the target side of the association. If no arguments are passed, the current configured table instance is returned
Deprecated
Parameters
-
Cake\ORM\Table$table optional null - the instance to be assigned as target side
Returns
transformRow() public ¶
transformRow( array $row , string $nestKey , boolean $joined , string|null $targetProperty null )
Correctly nests a result row associated values into the correct array keys inside the source results.
Parameters
- array $row
- The row to transform
- string $nestKey
The array key under which the results for this association should be found
- boolean $joined
Whether or not the row is a result of a direct join with this association
- string|null $targetProperty optional null
The property name in the source results where the association data shuld be nested in. Will use the default one if not provided.
Returns
updateAll() public ¶
updateAll( array $fields , mixed $conditions )
Proxies the update operation to the target table's updateAll method
Parameters
- array $fields
- A hash of field => new value.
- mixed $conditions
Conditions to be used, accepts anything Query::where() can take.
Returns
Count Returns the affected rows.
See
Methods used from Cake\Core\ConventionsTrait
_camelize() protected ¶
_camelize( string $name )
Creates a camelized version of $name
Parameters
- string $name
- name
Returns
Camelized name
_entityName() protected ¶
_entityName( string $name )
Creates the proper entity name (singular) for the specified name
Parameters
- string $name
- Name
Returns
Camelized and plural model name
_fixtureName() protected ¶
_fixtureName( string $name )
Creates a fixture name
Parameters
- string $name
- Model class name
Returns
Singular model key
_modelKey() protected ¶
_modelKey( string $name )
Creates the proper underscored model key for associations
If the input contains a dot, assume that the right side is the real table name.
Parameters
- string $name
- Model class name
Returns
Singular model key
_modelNameFromKey() protected ¶
_modelNameFromKey( string $key )
Creates the proper model name from a foreign key
Parameters
- string $key
- Foreign key
Returns
Model name
_pluginNamespace() protected ¶
_pluginNamespace( string $pluginName )
Return plugin's namespace
Parameters
- string $pluginName
- Plugin name
Returns
Plugin's namespace
_pluginPath() protected ¶
_pluginPath( string $pluginName )
Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.
Parameters
- string $pluginName
- Name of the plugin you want ie. DebugKit
Returns
path path to the correct plugin.
_pluralHumanName() protected ¶
_pluralHumanName( string $name )
Creates the plural human name used in views
Parameters
- string $name
- Controller name
Returns
Plural human name
_singularHumanName() protected ¶
_singularHumanName( string $name )
Creates the singular human name used in views
Parameters
- string $name
- Controller name
Returns
Singular human name
_singularName() protected ¶
_singularName( string $name )
Creates the singular name for use in views.
Parameters
- string $name
- Name to use
Returns
Variable name
_variableName() protected ¶
_variableName( string $name )
Creates the plural variable name for views
Parameters
- string $name
- Name to use
Returns
Plural name for views
Methods used from Cake\ORM\Locator\LocatorAwareTrait
setTableLocator() public ¶
setTableLocator( Cake\ORM\Locator\LocatorInterface $tableLocator )
Sets the table locator.
Parameters
-
Cake\ORM\Locator\LocatorInterface$tableLocator - LocatorInterface instance.
Returns
$this
tableLocator() public ¶
tableLocator( Cake\ORM\Locator\LocatorInterface $tableLocator null )
Sets the table locator. If no parameters are passed, it will return the currently used locator.
Deprecated
Parameters
-
Cake\ORM\Locator\LocatorInterface$tableLocator optional null - LocatorInterface instance.
Returns
Properties detail
$_validStrategies ¶
Valid strategies for this type of association
[
self::STRATEGY_JOIN,
self::STRATEGY_SELECT
]