CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 3.3 Red Velvet API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 3.3
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Console
    • Controller
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
      • Association
      • Behavior
      • Exception
      • Locator
      • Rule
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

Class HasMany

Represents an N - 1 relationship where the target side of the relationship will have one or multiple records per each one in the source side.

An example of a HasMany association would be Author has many Articles.

Namespace: Cake\ORM\Association

Constants

  • string
    MANY_TO_MANY ¶
    'manyToMany'

    Association type for many to many associations.

  • string
    MANY_TO_ONE ¶
    'manyToOne'

    Association type for many to one associations.

  • string
    ONE_TO_MANY ¶
    'oneToMany'

    Association type for one to many associations.

  • string
    ONE_TO_ONE ¶
    'oneToOne'

    Association type for one to one associations.

  • string
    SAVE_APPEND ¶
    'append'

    Saving strategy that will only append to the links set

  • string
    SAVE_REPLACE ¶
    'replace'

    Saving strategy that will replace the links with the provided set

  • string
    STRATEGY_JOIN ¶
    'join'

    Strategy name to use joins for fetching associated records

  • string
    STRATEGY_SELECT ¶
    'select'

    Strategy name to use a select for fetching associated records

  • string
    STRATEGY_SUBQUERY ¶
    'subquery'

    Strategy name to use a subquery for fetching associated records

Property Summary

  • $_bindingKey protected
    string|array

    The field name in the owning side table that is used to match with the foreignKey

  • $_cascadeCallbacks protected
    bool

    Whether or not cascaded deletes should also fire callbacks.

  • $_className protected
    string

    The class name of the target table object

  • $_conditions protected
    array

    A list of conditions to be always included when fetching records from the target association

  • $_dependent protected
    bool

    Whether the records on the target table are dependent on the source table, often used to indicate that records should be removed if the owning record in the source table is deleted.

  • $_finder protected
    string

    The default finder name to use for fetching rows from the target table

  • $_foreignKey protected
    string|array

    The name of the field representing the foreign key to the table to load

  • $_joinType protected
    string

    The type of join to be used when adding the association to a query

  • $_name protected
    string

    Name given to the association, it usually represents the alias assigned to the target associated table

  • $_propertyName protected
    string

    The property name that should be filled with data from the target table in the source table record.

  • $_saveStrategy protected
    string

    Saving strategy to be used by this association

  • $_sort protected
    mixed

    Order in which target records should be returned

  • $_sourceTable protected
    Cake\ORM\Table

    Source table instance

  • $_strategy protected
    string

    The strategy name to be used to fetch associated records.

  • $_tableLocator protected
    Cake\ORM\Locator\LocatorInterface

    Table locator instance

  • $_targetTable protected
    Cake\ORM\Table

    Target table instance

  • $_validStrategies protected
    array

    Valid strategies for this type of association

Method Summary

  • __call() public

    Proxies method calls to the target table.

  • __construct() public

    Constructor. Subclasses can override _options function to get the original list of passed options if expecting any other special key

  • __get() public

    Proxies property retrieval to the target table. This is handy for getting this association's associations

  • __isset() public

    Proxies the isset call to the target table. This is handy to check if the target table has another association with the passed name

  • _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.

  • _appendFields() protected

    Helper function used to conditionally append fields to the select clause of a query from the fields found in another query object.

  • _appendNotMatching() protected

    Conditionally adds a condition to the passed Query that will make it find records where there is no match with this association.

  • _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.

  • _bindNewAssociations() protected

    Applies all attachable associations to $query out of the containments found in the $surrogate query.

  • _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.

  • _camelize() protected

    Creates a camelized version of $name

  • _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

  • _dispatchBeforeFind() protected

    Triggers beforeFind on the target table for the query this association is attaching to

  • _entityName() protected

    Creates the proper entity name (singular) for the specified name

  • _extractFinder() protected

    Helper method to infer the requested finder and its options.

  • _fixtureName() protected

    Creates a fixture name

  • _foreignKeyAcceptsNull() protected

    Checks the nullable flag of the foreign key

  • _formatAssociationResults() protected

    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.

  • _joinCondition() protected

    Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.

  • _linkField() protected

    Generates a string used as a table field that contains the values upon which the filter should be applied

  • _modelKey() protected

    Creates the proper underscored model key for associations

  • _modelNameFromKey() protected

    Creates the proper model name from a foreign key

  • _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.

  • _pluginNamespace() protected

    Return plugin's namespace

  • _pluginPath() protected

    Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.

  • _pluralHumanName() protected

    Creates the plural human name used in views

  • _propertyName() protected

    Returns default property name based on association name.

  • _resultInjector() protected

    Returns a callable to be used for each row in a query result set for injecting the eager loaded rows

  • _singularHumanName() protected

    Creates the singular human name used in views

  • _singularName() protected

    Creates the singular name for use in views.

  • _subqueryFields() protected

    Calculate the fields that need to participate in a subquery.

  • _unlink() protected

    Deletes/sets null the related objects matching $conditions. The action which is taken depends on the dependency between source and targets and also on foreign key nullability

  • _unlinkAssociated() protected

    Deletes/sets null the related objects according to the dependency between source and targets and foreign key nullability Skips deleting records present in $remainingEntities

  • _variableName() protected

    Creates the plural variable name for views

  • attachTo() public

    Alters a Query object to include the associated target table data in the final result

  • bindingKey() public

    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.

  • canBeJoined() public

    Whether this association can be expressed directly in a query join

  • cascadeCallbacks() public

    Sets whether or not cascaded deletes should also fire callbacks. If no arguments are passed, the current configured value is returned

  • cascadeDelete() public

    Cascade a delete to remove dependent records.

  • className() public

    The class name of the target table object

  • conditions() public

    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

  • defaultRowValue() public

    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.

  • deleteAll() public

    Proxies the delete operation to the target table's deleteAll method

  • dependent() public

    Sets whether the records on the target table are dependent on the source table.

  • 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.

  • exists() public

    Proxies the operation to the target table's exists method after appending the default conditions for this association

  • find() public

    Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration

  • finder() public

    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.

  • 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

  • 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.

  • joinType() public

    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.

  • link() public

    Associates the source entity to each of the target entities provided. When using this method, all entities in $targetEntities will be appended to the source entity's property corresponding to this association object.

  • name() public

    Sets the name for this association. If no argument is passed then the current configured name will be returned

  • property() public

    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.

  • replace() public

    Replaces existing association links between the source entity and the target with the ones passed. This method does a smart cleanup, links that are already persisted and present in $targetEntities will not be deleted, new links will be created for the passed target entities that are not already in the database and the rest will be removed.

  • 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.

  • 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

  • saveStrategy() public

    Sets the strategy that should be used for saving. If called with no arguments, it will return the currently configured strategy

  • sort() public

    Sets the sort order in which target records should be returned. If no arguments are passed the currently configured value is returned

  • source() public

    Sets the table instance for the source side of the association. If no arguments are passed, the current configured table instance is returned

  • strategy() public

    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.

  • tableLocator() public

    Sets the table locator. If no parameters are passed, it will return the currently used locator.

  • target() public

    Sets the table instance for the target side of the association. If no arguments are passed, the current configured table instance is returned

  • transformRow() public

    Correctly nests a result row associated values into the correct array keys inside the source results.

  • type() public

    Get the relationship type.

  • unlink() public

    Removes all links between the passed source entity and each of the provided target entities. This method assumes that all passed objects are already persisted in the database and that each of them contain a primary key value.

  • updateAll() public

    Proxies the update operation to the target table's updateAll method

Method Detail

__call() ¶ public

__call(string $method, array $argument): mixed

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
mixed
Throws
BadMethodCallException

__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): Cake\ORM\Association

Proxies property retrieval to the target table. This is handy for getting this association's associations

Parameters
string $property

the property name

Returns
Cake\ORM\Association
Throws
RuntimeException
if no association with such name exists

__isset() ¶ public

__isset(string $property): bool

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
bool

_addFilteringCondition() ¶ protected

_addFilteringCondition(Cake\ORM\Query $query, string|array $key, mixed $filter): Cake\ORM\Query

Appends 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\Query

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.

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

_appendFields() ¶ protected

_appendFields(Cake\ORM\Query $query, Cake\ORM\Query $surrogate, array $options): void

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

Returns
void

_appendNotMatching() ¶ protected

_appendNotMatching(Cake\Datasource\QueryInterface $query, array $options): void

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 negateMatch key.

Returns
void

_assertFieldsPresent() ¶ protected

_assertFieldsPresent(Cake\ORM\Query $fetchQuery, array $key): void

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.

Parameters
Cake\ORM\Query $fetchQuery

The association fetching query

array $key

The foreign key fields to check

Returns
void
Throws
InvalidArgumentException

_bindNewAssociations() ¶ protected

_bindNewAssociations(Cake\ORM\Query $query, Cake\ORM\Query $surrogate, array $options): void

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

Returns
void

_buildQuery() ¶ protected

_buildQuery(array $options): Cake\ORM\Query

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

Parameters
array $options

options accepted by eagerLoader()

Returns
Cake\ORM\Query
Throws
InvalidArgumentException
When a key is required for associations but not selected.

_buildResultMap() ¶ protected

_buildResultMap(Cake\ORM\Query $fetchQuery, array $options): array

Builds 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\Query

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.

Parameters
Cake\ORM\Query $query

the original query used to load source records

Returns
Cake\ORM\Query

_camelize() ¶ protected

_camelize(string $name): string

Creates a camelized version of $name

Parameters
string $name

name

Returns
string

_createTupleCondition() ¶ protected

_createTupleCondition(Cake\ORM\Query $query, array $keys, mixed $filter, string $operator): Cake\Database\Expression\TupleComparison

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.

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(): array

Returns the default options to use for the eagerLoader

Returns
array

_dispatchBeforeFind() ¶ protected

_dispatchBeforeFind(Cake\ORM\Query $query): void

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

Returns
void

_entityName() ¶ protected

_entityName(string $name): string

Creates the proper entity name (singular) for the specified name

Parameters
string $name

Name

Returns
string

_extractFinder() ¶ protected

_extractFinder(string|array $finderData): array

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
array

_fixtureName() ¶ protected

_fixtureName(string $name): string

Creates a fixture name

Parameters
string $name

Model class name

Returns
string

_foreignKeyAcceptsNull() ¶ protected

_foreignKeyAcceptsNull(Cake\ORM\Table $table, array $properties): bool

Checks the nullable flag of the foreign key

Parameters
Cake\ORM\Table $table

the table containing the foreign key

array $properties

the list of fields that compose the foreign key

Returns
bool

_formatAssociationResults() ¶ protected

_formatAssociationResults(Cake\ORM\Query $query, Cake\ORM\Query $surrogate, array $options): void

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

Returns
void

_joinCondition() ¶ protected

_joinCondition(array $options): array

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
array
Throws
RuntimeException
if the number of columns in the foreignKey do not match the number of columns in the source table primaryKey

_linkField() ¶ protected

_linkField(array $options): string|array

Generates a string used as a table field that contains the values upon which the filter should be applied

Parameters
array $options
Returns
string|array

_modelKey() ¶ protected

_modelKey(string $name): string

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
string

_modelNameFromKey() ¶ protected

_modelNameFromKey(string $key): string

Creates the proper model name from a foreign key

Parameters
string $key

Foreign key

Returns
string

_multiKeysInjector() ¶ protected

_multiKeysInjector(array $resultMap, array $sourceKeys, string $nestKey): Closure

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

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): void

Parse extra options passed in the constructor.

Parameters
array $opts

original list of options passed in constructor

Returns
void

_pluginNamespace() ¶ protected

_pluginNamespace(string $pluginName): string

Return plugin's namespace

Parameters
string $pluginName

Plugin name

Returns
string

_pluginPath() ¶ protected

_pluginPath(string $pluginName): string

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
string

_pluralHumanName() ¶ protected

_pluralHumanName(string $name): string

Creates the plural human name used in views

Parameters
string $name

Controller name

Returns
string

_propertyName() ¶ protected

_propertyName(): string

Returns default property name based on association name.

Returns
string

_resultInjector() ¶ protected

_resultInjector(Cake\ORM\Query $fetchQuery, array $resultMap, array $options): Closure

Returns 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

_singularHumanName() ¶ protected

_singularHumanName(string $name): string

Creates the singular human name used in views

Parameters
string $name

Controller name

Returns
string

_singularName() ¶ protected

_singularName(string $name): string

Creates the singular name for use in views.

Parameters
string $name

Name to use

Returns
string

_subqueryFields() ¶ protected

_subqueryFields(Cake\ORM\Query $query): array

Calculate 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
array

_unlink() ¶ protected

_unlink(array $foreignKey, Cake\ORM\Table $target, array $conditions = [], array $options = []): bool

Deletes/sets null the related objects matching $conditions. The action which is taken depends on the dependency between source and targets and also on foreign key nullability

Parameters
array $foreignKey

array of foreign key properties

Cake\ORM\Table $target

The associated table

array $conditions optional

The conditions that specifies what are the objects to be unlinked

array $options optional

list of options accepted by Table::delete()

Returns
bool

_unlinkAssociated() ¶ protected

_unlinkAssociated(array $properties, Cake\Datasource\EntityInterface $entity, Cake\ORM\Table $target, array $remainingEntities = [], array $options = []): bool

Deletes/sets null the related objects according to the dependency between source and targets and foreign key nullability Skips deleting records present in $remainingEntities

Parameters
array $properties

array of foreignKey properties

Cake\Datasource\EntityInterface $entity

the entity which should have its associated entities unassigned

Cake\ORM\Table $target

The associated table

array $remainingEntities optional

Entities that should not be deleted

array $options optional

list of options accepted by Table::delete()

Returns
bool

_variableName() ¶ protected

_variableName(string $name): string

Creates the plural variable name for views

Parameters
string $name

Name to use

Returns
string

attachTo() ¶ public

attachTo(Cake\ORM\Query $query, array $options = []): void

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

Returns
void
Throws
RuntimeException
if the query builder passed does not return a query object

bindingKey() ¶ public

bindingKey(string|null $key = null): string|array

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

Parameters
string|null $key optional

the table field to be used to link both tables together

Returns
string|array

canBeJoined() ¶ public

canBeJoined(array $options = []): bool

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
bool

cascadeCallbacks() ¶ public

cascadeCallbacks(bool|null $cascadeCallbacks = null): bool

Sets whether or not cascaded deletes should also fire callbacks. If no arguments are passed, the current configured value is returned

Parameters
bool|null $cascadeCallbacks optional

cascade callbacks switch value

Returns
bool

cascadeDelete() ¶ public

cascadeDelete(Cake\Datasource\EntityInterface $entity, array $options = []): bool

Cascade a delete to remove dependent records.

This method does nothing if the association is not dependent.

Parameters
Cake\Datasource\EntityInterface $entity

The entity that started the cascaded delete.

array $options optional

The options for the original delete.

Returns
bool

className() ¶ public

className(): string

The class name of the target table object

Returns
string

conditions() ¶ public

conditions(array|null $conditions = null): array

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

Parameters
array|null $conditions optional

list of conditions to be used

Returns
array
See Also
\Cake\Database\Query::where() for examples on the format of the array

defaultRowValue() ¶ public

defaultRowValue(array $row, bool $joined): array

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
bool $joined
Returns
array

deleteAll() ¶ public

deleteAll(mixed $conditions): int

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
int
See Also
\Cake\ORM\Table::deleteAll()

dependent() ¶ public

dependent(bool|null $dependent = null): bool

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
bool|null $dependent optional

Set the dependent mode. Use null to read the current state.

Returns
bool

eagerLoader() ¶ public

eagerLoader(array $options): Closure

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.

The required way of passing related source records is controlled by "strategy" When the subquery strategy is used it will require a query on the source table. When using the select strategy, the list of primary keys will be used.

Returns a closure that should be run for each record returned in a specific Query. This callable will be responsible for injecting the fields that are related to each specific passed row.

Options array accepts the following keys:

  • query: Query object setup to find the source table records
  • keys: List of primary key values from the source table
  • foreignKey: The name of the field used to relate both tables
  • conditions: List of conditions to be passed to the query where() method
  • sort: The direction in which the records should be returned
  • fields: List of fields to select from the target table
  • contain: List of related tables to eager load associated to the target table
  • strategy: The name of strategy to use for finding target table records
  • nestKey: The array key under which results will be found when transforming the row
Parameters
array $options
Returns
Closure

exists() ¶ public

exists(array|callable|Cake\Database\ExpressionInterface $conditions): bool

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
bool
See Also
\Cake\ORM\Table::exists()

find() ¶ public

find(string|array|null $type = null, array $options = []): Cake\ORM\Query

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

the type of query to perform, if an array is passed, it will be interpreted as the $options parameter

array $options optional

The options to for the find

Returns
Cake\ORM\Query
See Also
\Cake\ORM\Table::find()

finder() ¶ public

finder(string|null $finder = null): string

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.

Parameters
string|null $finder optional

the finder name to use

Returns
string

foreignKey() ¶ public

foreignKey(string|null $key = null): string

Sets 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
string

isOwningSide() ¶ public

isOwningSide(Cake\ORM\Table $side): bool

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
bool

joinType() ¶ public

joinType(string|null $type = null): string

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.

Parameters
string|null $type optional

the join type to be used (e.g. INNER)

Returns
string

link() ¶ public

link(Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = []): bool

Associates the source entity to each of the target entities provided. When using this method, all entities in $targetEntities will be appended to the source entity's property corresponding to this association object.

This method does not check link uniqueness. Changes are persisted in the database and also in the source entity.

Example:

$user = $users->get(1);
$allArticles = $articles->find('all')->toArray();
$users->Articles->link($user, $allArticles);

$user->get('articles') will contain all articles in $allArticles after linking

Parameters
Cake\Datasource\EntityInterface $sourceEntity

the row belonging to the source side of this association

array $targetEntities

list of entities belonging to the target side of this association

array $options optional

list of options to be passed to the internal save call

Returns
bool

name() ¶ public

name(string|null $name = null): string

Sets the name for this association. If no argument is passed then the current configured name will be returned

Parameters
string|null $name optional

Name to be assigned

Returns
string

property() ¶ public

property(string|null $name = null): string

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.

Parameters
string|null $name optional

The name of the association property. Use null to read the current value.

Returns
string

replace() ¶ public

replace(Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = []): bool

Replaces existing association links between the source entity and the target with the ones passed. This method does a smart cleanup, links that are already persisted and present in $targetEntities will not be deleted, new links will be created for the passed target entities that are not already in the database and the rest will be removed.

For example, if an author has many articles, such as 'article1','article 2' and 'article 3' and you pass to this method an array containing the entities for articles 'article 1' and 'article 4', only the link for 'article 1' will be kept in database, the links for 'article 2' and 'article 3' will be deleted and the link for 'article 4' will be created.

Existing links are not deleted and created again, they are either left untouched or updated.

This method does not check link uniqueness.

On success, the passed $sourceEntity will contain $targetEntities as value in the corresponding property for this association.

Additional options for new links to be saved can be passed in the third argument, check Table::save() for information on the accepted options.

Example:

$author->articles = [$article1, $article2, $article3, $article4];
$authors->save($author);
$articles = [$article1, $article3];
$authors->association('articles')->replace($author, $articles);

$author->get('articles') will contain only [$article1, $article3] at the end

Parameters
Cake\Datasource\EntityInterface $sourceEntity

an entity persisted in the source table for this association

array $targetEntities

list of entities from the target table to be linked

array $options optional

list of options to be passed to the internal save/delete calls when persisting/updating new links, or deleting existing ones

Returns
bool
Throws
InvalidArgumentException
if non persisted entities are passed or if any of them is lacking a primary key value

requiresKeys() ¶ public

requiresKeys(array $options = []): bool

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
bool

saveAssociated() ¶ public

saveAssociated(Cake\Datasource\EntityInterface $entity, array|ArrayObject $options = []): bool|Cake\Datasource\EntityInterface

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|ArrayObject $options optional

options to be passed to the save method in the target table

Returns
bool|Cake\Datasource\EntityInterface
Throws
InvalidArgumentException
when the association data cannot be traversed.
See Also
\Cake\ORM\Table::save()

saveStrategy() ¶ public

saveStrategy(string|null $strategy = null): string

Sets the strategy that should be used for saving. If called with no arguments, it will return the currently configured strategy

Parameters
string|null $strategy optional

the strategy name to be used

Returns
string
Throws
InvalidArgumentException
if an invalid strategy name is passed

sort() ¶ public

sort(mixed $sort = null): mixed

Sets 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

source() ¶ public

source(Cake\ORM\Table|null $table = null): Cake\ORM\Table

Sets the table instance for the source side of the association. If no arguments are passed, the current configured table instance is returned

Parameters
Cake\ORM\Table|null $table optional

the instance to be assigned as source side

Returns
Cake\ORM\Table

strategy() ¶ public

strategy(string|null $name = null): string

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.

Parameters
string|null $name optional

The strategy type. Use null to read the current value.

Returns
string
Throws
InvalidArgumentException
When an invalid strategy is provided.

tableLocator() ¶ public

tableLocator(Cake\ORM\Locator\LocatorInterface|null $tableLocator = null): Cake\ORM\Locator\LocatorInterface

Sets the table locator. If no parameters are passed, it will return the currently used locator.

Parameters
Cake\ORM\Locator\LocatorInterface|null $tableLocator optional

LocatorInterface instance.

Returns
Cake\ORM\Locator\LocatorInterface

target() ¶ public

target(Cake\ORM\Table|null $table = null): Cake\ORM\Table

Sets the table instance for the target side of the association. If no arguments are passed, the current configured table instance is returned

Parameters
Cake\ORM\Table|null $table optional

the instance to be assigned as target side

Returns
Cake\ORM\Table

transformRow() ¶ public

transformRow(array $row, string $nestKey, bool $joined, string $targetProperty = null): array

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

bool $joined

Whether or not the row is a result of a direct join with this association

string $targetProperty optional

The property name in the source results where the association data should be nested in. Will use the default one if not provided.

Returns
array

type() ¶ public

type(): string

Get the relationship type.

Returns
string

unlink() ¶ public

unlink(Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = []): void

Removes all links between the passed source entity and each of the provided target entities. This method assumes that all passed objects are already persisted in the database and that each of them contain a primary key value.

Options

Additionally to the default options accepted by Table::delete(), the following keys are supported:

  • cleanProperty: Whether or not to remove all the objects in $targetEntities that are stored in $sourceEntity (default: true)

By default this method will unset each of the entity objects stored inside the source entity.

Changes are persisted in the database and also in the source entity.

Example:

$user = $users->get(1);
$user->articles = [$article1, $article2, $article3, $article4];
$users->save($user, ['Associated' => ['Articles']]);
$allArticles = [$article1, $article2, $article3];
$users->Articles->unlink($user, $allArticles);

$article->get('articles') will contain only [$article4] after deleting in the database

Parameters
Cake\Datasource\EntityInterface $sourceEntity

an entity persisted in the source table for this association

array $targetEntities

list of entities persisted in the target table for this association

array $options optional

list of options to be passed to the internal delete call

Returns
void
Throws
InvalidArgumentException
if non persisted entities are passed or if any of them is lacking a primary key value

updateAll() ¶ public

updateAll(array $fields, mixed $conditions): bool

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
bool
See Also
\Cake\ORM\Table::updateAll()

Property Detail

$_bindingKey ¶ protected

The field name in the owning side table that is used to match with the foreignKey

Type
string|array

$_cascadeCallbacks ¶ protected

Whether or not cascaded deletes should also fire callbacks.

Type
bool

$_className ¶ protected

The class name of the target table object

Type
string

$_conditions ¶ protected

A list of conditions to be always included when fetching records from the target association

Type
array

$_dependent ¶ protected

Whether the records on the target table are dependent on the source table, often used to indicate that records should be removed if the owning record in the source table is deleted.

Type
bool

$_finder ¶ protected

The default finder name to use for fetching rows from the target table

Type
string

$_foreignKey ¶ protected

The name of the field representing the foreign key to the table to load

Type
string|array

$_joinType ¶ protected

The type of join to be used when adding the association to a query

Type
string

$_name ¶ protected

Name given to the association, it usually represents the alias assigned to the target associated table

Type
string

$_propertyName ¶ protected

The property name that should be filled with data from the target table in the source table record.

Type
string

$_saveStrategy ¶ protected

Saving strategy to be used by this association

Type
string

$_sort ¶ protected

Order in which target records should be returned

Type
mixed

$_sourceTable ¶ protected

Source table instance

Type
Cake\ORM\Table

$_strategy ¶ protected

The strategy name to be used to fetch associated records.

Type
string

$_tableLocator ¶ protected

Table locator instance

Type
Cake\ORM\Locator\LocatorInterface

$_targetTable ¶ protected

Target table instance

Type
Cake\ORM\Table

$_validStrategies ¶ protected

Valid strategies for this type of association

Type
array
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs