BelongsToMany 类

表示 M - N 关系，其中存在一个连接表，其中包含源表和目标表之间的关联字段。

BelongsToMany 关联的一个例子是文章属于多个标签。在这个例子中，"文章" 是源表，"标签" 是目标表。

命名空间： Cake\ORM\Association

常量

字符串

MANY_TO_MANY ¶
```
'manyToMany'
```
多对多关联的关联类型。
字符串

MANY_TO_ONE ¶
```
'manyToOne'
```
多对一关联的关联类型。
字符串

ONE_TO_MANY ¶
```
'oneToMany'
```
一对多关联的关联类型。
字符串

ONE_TO_ONE ¶
```
'oneToOne'
```
一对一关联的关联类型。
字符串

SAVE_APPEND ¶
```
'append'
```
保存策略，只会附加到链接集中
字符串

SAVE_REPLACE ¶
```
'replace'
```
保存策略，将用提供的集合替换链接
字符串

STRATEGY_JOIN ¶
```
'join'
```
策略名称，用于使用联接来获取关联记录
字符串

STRATEGY_SELECT ¶
```
'select'
```
策略名称，用于使用选择来获取关联记录
字符串

STRATEGY_SUBQUERY ¶
```
'subquery'
```
策略名称，用于使用子查询来获取关联记录

属性摘要

$_bindingKey protected

list<string>|string

拥有方表中用于与外键匹配的字段名称
$_cascadeCallbacks protected

bool

级联删除是否也应该触发回调。
$_className protected

字符串

目标表对象的类名
$_conditions protected

Closure|array

从目标关联获取记录时始终包含的条件列表
$_dependent protected

bool

当源表中的记录被删除时，连接表上的记录是否应该被删除。
$_finder protected

array|string

用于从目标表获取行时的默认查找器名称。使用数组值，允许查找器名称和默认选项。
$_foreignKey protected

list<string>|string|false

表示要加载的表的外部键的字段名称
$_joinType protected

字符串

将关联添加到查询时使用的联接类型
$_junctionAssociationName protected

字符串

从目标表到连接表的 hasMany 关联的名称
$_junctionConditions protected

array|null

引用连接表的过滤条件。
$_junctionProperty protected

字符串

从目标表获取记录后，设置包含连接表数据的属性的名称
$_junctionTable protected

Cake\ORM\Table

连接表实例
$_junctionTableName protected

字符串

连接表名称
$_name protected

字符串

赋予关联的名称，通常代表分配给目标关联表的别名
$_propertyName protected

字符串

应该用目标表中的数据填充源表记录中的属性名称。
$_saveStrategy protected

字符串

此关联要使用的保存策略
$_sort protected

Cake\Database\ExpressionInterfaceClosure|arrayCake\Database\ExpressionInterface|string>|string|null

目标记录返回的顺序
$_sourceTable protected

Cake\ORM\Table

源表实例
$_strategy protected

字符串

用于获取关联记录的策略名称。
$_tableLocator protected

Cake\ORM\Locator\LocatorInterface|null

表定位器实例
$_targetConditions protected

array|null

引用目标表的过滤条件。
$_targetForeignKey protected

list<string>|string|null

表示指向目标表的外部键的字段名称
$_targetTable protected

Cake\ORM\Table

目标表实例
$_through protected

Cake\ORM\Table|string|null

连接关系的表实例。
$_validStrategies protected

list<string>

此关联类型的有效策略
$defaultTable protected

string|null

此对象的默认表别名。

方法摘要

__call() public

将方法调用代理给目标表。
__construct() public

构造函数。子类可以覆盖 _options 函数来获取传递选项的原始列表（如果期望任何其他特殊键）。
__get() public

将属性检索代理给目标表。这对于获取此关联的关联很有用
__isset() public

将 isset 调用代理给目标表。这对于检查目标表是否具有与传递名称相同的其他关联很有用
_appendFields() protected

辅助函数，用于有条件地将来自另一个查询对象中找到的字段的字段附加到查询的选择子句中。
_appendJunctionJoin() protected

将联接到连接表。
_appendNotMatching() protected

有条件地将条件添加到传递的查询中，这将使其找到与该关联不匹配的记录。
_bindNewAssociations() protected

将 $surrogate 查询中找到的所有可附加关联应用于 $query。
_camelize() protected

创建 $name 的驼峰式版本。
_checkPersistenceStatus() protected

如果传递的任何实体未持久化，则抛出异常。
_collectJointEntities() protected

返回源实体和每个传递的目标实体之间存在的联合实体列表。
_diffLinks() protected

帮助方法，用于删除 $existing 和 $jointEntities 中传递的链接之间的差异。此方法将返回从计算差异中未删除的 $targetEntities 中的值。
_dispatchBeforeFind() protected

触发此关联所附加的查询的目标表的 beforeFind 事件。
_entityName() protected

为指定名称创建正确的实体名称（单数）。
_extractFinder() protected

帮助方法，用于推断请求的查找器及其选项。
_fixtureName() protected

创建设备名称。
_formatAssociationResults() protected

如果 $surrogate 查询声明了任何其他格式化程序，则将格式化程序函数添加到传递的 $query 中。由于 $surrogate 查询对应于关联的目标表，因此结果格式化程序将是将代理格式化程序应用于仅对应于该表的属性的结果。
_generateJunctionAssociations() protected

根据需要在联接表上生成关联。
_generateSourceAssociations() protected

根据需要生成其他源表关联。
_generateTargetAssociations() protected

根据需要生成互惠关联。
_joinCondition() protected

返回 false，因为联接条件是在联接表中定义的。
_junctionAssociationName() protected

返回从目标表到联接表的关联的名称，此名称用于在查询中生成别名，并在稍后检索结果。
_junctionTableName() protected

设置联接表的名称。如果没有传递参数，则返回当前配置的名称。如果未找到，将生成基于关联表的默认名称。
_modelKey() protected

为关联创建正确的带下划线的模型键。
_modelNameFromKey() protected

从外键创建正确的模型名称。
_options() protected

解析构造函数中传递的额外选项。
_pluginNamespace() protected

返回插件的命名空间。
_pluginPath() protected

找到插件的正确路径。扫描 $pluginPaths 中的插件。
_pluralHumanName() protected

创建视图中使用的复数人名。
_propertyName() protected

返回基于关联名称的默认属性名称。
_saveLinks() protected

在源实体和每个传递的目标实体之间创建链接。
_saveTarget() protected

将每个实体持久化到目标表中，并在父实体和每个保存的目标实体之间创建链接。
_singularHumanName() protected

创建视图中使用的单数人名。
_singularName() protected

创建用于视图的单数名称。
_variableName() protected

创建视图的复数变量名。
attachTo() public

更改查询对象，以在最终结果中包含关联的目标表数据。
canBeJoined() public

此关联是否可以直接在查询联接中表达。
cascadeDelete() public

清除给定实体的联接表中的数据。
defaultRowValue() public

在为该关联追加一个具有默认空值的属性后，返回修改后的行，该属性取决于关联是通过联接还是通过外部获取。
deleteAll() public

将删除操作代理到目标 Table::deleteAll() 方法。
eagerLoader() public

渴望加载目标表中与源表中另一组记录相关的记录列表。源记录可以通过两种方式指定：第一种是通过传递一个在源表上查找的查询对象，另一种方式是通过显式传递源表的主键值数组。
exists() public

将操作代理到目标表的 exists 方法，并在其后追加该关联的默认条件。
fetchTable() public

用于获取表实例的便捷方法。
find() public

将查找操作代理到目标表的 find 方法，并根据该关联配置相应地修改查询。
getBindingKey() public

获取表示与目标表绑定字段的字段的名称。如果未手动指定，则使用拥有方表的主键。
getCascadeCallbacks() public

获取级联删除是否也应该触发回调。
getClassName() public

获取目标表对象的类名。
getConditions() public

获取从目标关联获取记录时始终包含的条件列表。
getDependent() public

设置目标表上的记录是否依赖于源表。
getFinder() public

获取用于从目标表获取行的默认查找器。
getForeignKey() public

获取表示指向目标表的外键的字段的名称。
getJoinType() public

获取将关联添加到查询时使用的联接类型。
getName() public

获取此关联的名称，通常是分配给目标关联表的别名。
getProperty() public

获取应使用目标表中的数据在源表记录中填充的属性名称。
getSaveStrategy() public

获取应用于保存的策略。
getSort() public

获取应返回目标记录的排序顺序。
getSource() public

获取关联源侧的表实例。
getStrategy() public

获取用于获取关联记录的策略名称。请记住，某些关联类型可能没有实现，但有一个默认策略，这将使对该设置的任何更改无效。
getTableLocator() public

获取表定位器。
getTarget() public

获取关联目标侧的表实例。
getTargetForeignKey() public

获取表示指向目标表的外键的字段的名称。
getThrough() public

获取当前联接表，可以是 Table 实例的名称，也可以是实例本身。如果未定义，则返回 null。
isOwningSide() public

返回布尔值 true，因为两个表都通过联接表拥有关联另一侧的行。
junction() public

设置联接关系的表实例。如果没有传递参数，则返回当前配置的表实例。
junctionConditions() protected

返回专门引用联接表的过滤条件。
link() public

通过在联接表中创建链接，将源实体关联到每个提供的目标实体。源实体和每个目标实体都假定已持久化，如果它们被标记为新实体或其状态未知，则将抛出异常。
replaceLinks() public

用传递的链接替换源实体和目标之间现有的关联链接。此方法执行智能清理，已持久化并在 $targetEntities 中存在的链接将不会被删除，将为传递的目标实体创建新链接（这些实体尚未在数据库中），其余链接将被删除。
requiresKeys() public

如果渴望加载过程需要一组拥有方表绑定键才能在查找器查询中用作过滤器，则返回 true。
saveAssociated() public

获取源表中的实体，并查看是否有与该关联的属性名称匹配的字段。找到的实体将通过传递提供的 $options 保存到该关联的目标表中。
setBindingKey() public

设置表示与目标表绑定字段的字段的名称。如果未手动指定，则使用拥有方表的主键。
setCascadeCallbacks() public

设置级联删除是否也应该触发回调。
setClassName() public

设置目标表对象的类名。
setConditions() public

设置从目标关联获取记录时始终包含的条件列表。
setDependent() public

设置目标表上的记录是否依赖于源表。
setFinder() public

设置用于从目标表获取行的默认查找器。
setForeignKey() public

设置表示指向目标表的外键的字段的名称。
setJoinType() public

设置将关联添加到查询时使用的联接类型。
setProperty() public

设置应使用目标表中的数据在源表记录中填充的属性名称。
setSaveStrategy() public

设置应用于保存的策略。
setSort() public

设置应返回目标记录的排序顺序。
setSource() public

设置关联源侧的表实例。
setStrategy() public

设置用于获取关联记录的策略名称。请注意，某些关联类型可能没有实现，而是使用默认策略，因此对该设置的任何更改都会无效。
setTableLocator() public

设置表定位器。
setTarget() public

设置关联目标端的目标表实例。
setTargetForeignKey() public

设置表示指向目标表的外键的字段的名称。
setThrough() public

设置当前连接表，可以是 Table 实例的名称或实例本身。
targetConditions() protected

返回引用目标表的过滤条件。
transformRow() public

将与结果行关联的值正确嵌套到源结果中的正确数组键中。
type() public

获取关系类型。
unlink() public

删除传递的源实体与提供的目标实体之间的所有链接。此方法假设所有传递的对象已持久化到数据库中，并且每个对象都包含主键值。
updateAll() public

将更新操作代理到目标 Table::updateAll() 方法

方法详情

__call() ¶ public

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

将方法调用代理给目标表。

参数

string $method: 要调用的方法的名称
array $argument: 传递给函数的参数列表

返回值

混合

抛出

BadMethodCallException

__construct() ¶ public

__construct(string $alias, array<string, mixed> $options = [])

构造函数。子类可以覆盖 _options 函数来获取传递选项的原始列表（如果期望任何其他特殊键）。

参数

string $alias: 给关联起的名称
array<string, mixed> $options optional: 要在此对象上设置的属性列表

__get() ¶ public

__get(string $property): self

将属性检索代理给目标表。这对于获取此关联的关联很有用

参数

string $property: 属性名称

返回值

自我

抛出

RuntimeException
如果不存在具有该名称的关联

__isset() ¶ public

__isset(string $property): bool

将 isset 调用代理给目标表。这对于检查目标表是否具有与传递名称相同的其他关联很有用

参数

string $property: 属性名称

返回值

bool

_appendFields() ¶ protected

_appendFields(Cake\ORM\Query\SelectQuery $query, Cake\ORM\Query\SelectQuery $surrogate, array<string, mixed> $options): void

辅助函数，用于有条件地将来自另一个查询对象中找到的字段的字段附加到查询的选择子句中。

参数

Cake\ORM\Query\SelectQuery $query: 将要追加字段的查询
Cake\ORM\Query\SelectQuery $surrogate: 将要复制字段的查询
array<string, mixed> $options: 传递给 attachTo 方法的选项

返回值

空

_appendJunctionJoin() ¶ protected

_appendJunctionJoin(Cake\ORM\Query\SelectQuery $query, array|null $conditions = null): Cake\ORM\Query\SelectQuery

将联接到连接表。

参数

Cake\ORM\Query\SelectQuery $query: 要追加的查询。
array|null $conditions optional: 要使用的查询条件。

返回值

Cake\ORM\Query\SelectQuery

_appendNotMatching() ¶ protected

_appendNotMatching(Cake\ORM\Query\SelectQuery $query, array<string, mixed> $options): void

有条件地将条件添加到传递的查询中，这将使其找到与该关联不匹配的记录。

参数

Cake\ORM\Query\SelectQuery $query
array<string, mixed> $options

返回值

空

_bindNewAssociations() ¶ protected

_bindNewAssociations(Cake\ORM\Query\SelectQuery $query, Cake\ORM\Query\SelectQuery $surrogate, array<string, mixed> $options): void

将 $surrogate 查询中找到的所有可附加关联应用于 $query。

将 $surrogate 查询中包含的所有关联复制到传递的 $query 中。包含项已更改，以便它们尊重其起源的关联链。

参数

Cake\ORM\Query\SelectQuery $query: 将要附加关联的查询
Cake\ORM\Query\SelectQuery $surrogate: 具有要附加的包含项的查询
array<string, mixed> $options: 传递给 attachTo 方法的选项

返回值

空

_camelize() ¶ protected

_camelize(string $name): string

创建 $name 的驼峰式版本。

参数

string $name: 名称

返回值

字符串

_checkPersistenceStatus() ¶ protected

_checkPersistenceStatus(Cake\Datasource\EntityInterface $sourceEntity, arrayCake\Datasource\EntityInterface> $targetEntities): bool

如果传递的任何实体未持久化，则抛出异常。

参数

Cake\Datasource\EntityInterface $sourceEntity: 属于此关联 source 侧的行
arrayCake\Datasource\EntityInterface> $targetEntities: 属于此关联 target 侧的实体列表

返回值

bool

抛出

InvalidArgumentException

_collectJointEntities() ¶ protected

_collectJointEntities(Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities): arrayCake\Datasource\EntityInterface>

返回源实体和每个传递的目标实体之间存在的联合实体列表。

参数

Cake\Datasource\EntityInterface $sourceEntity: 属于此关联源侧的行。
array $targetEntities: 属于此关联目标侧的行。

返回值

arrayCake\Datasource\EntityInterface>

抛出

InvalidArgumentException
如果任何实体缺少主键值

_diffLinks() ¶ protected

_diffLinks(Cake\ORM\Query\SelectQuery $existing, arrayCake\Datasource\EntityInterface> $jointEntities, array $targetEntities, array<string, mixed> $options = []): array|false

帮助方法，用于删除 $existing 和 $jointEntities 中传递的链接之间的差异。此方法将返回从计算差异中未删除的 $targetEntities 中的值。

参数

Cake\ORM\Query\SelectQuery $existing: 获取现有链接的查询
arrayCake\Datasource\EntityInterface> $jointEntities: 应持久化的链接实体
array $targetEntities: 与 $jointEntities 相关的目标表中的实体
array<string, mixed> $options optional: Table::delete() 接受的选项列表

返回值

数组|false

_dispatchBeforeFind() ¶ protected

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

触发此关联所附加的查询的目标表的 beforeFind 事件。

参数

Cake\ORM\Query\SelectQuery $query: 此关联正在附加到的查询

返回值

空

_entityName() ¶ protected

_entityName(string $name): string

为指定名称创建正确的实体名称（单数）。

参数

string $name: 名称

返回值

字符串

_extractFinder() ¶ protected

_extractFinder(array|string $finderData): array

帮助方法，用于推断请求的查找器及其选项。

返回从查找器 $type 推断出的选项。

示例

以下将使用查找器的值作为其选项调用查找器“translations”：$query->contain(['Comments' => ['finder' => ['translations']]]); $query->contain(['Comments' => ['finder' => ['translations' => []]]]); $query->contain(['Comments' => ['finder' => ['translations' => ['locales' => ['en_US']]]]]);

参数

array|string $finderData: 查找器名称或包含名称作为键和选项作为值的数组。

返回值

数组

_fixtureName() ¶ protected

_fixtureName(string $name): string

创建设备名称。

参数

string $name: 模型类名称

返回值

字符串

_formatAssociationResults() ¶ protected

_formatAssociationResults(Cake\ORM\Query\SelectQuery $query, Cake\ORM\Query\SelectQuery $surrogate, array<string, mixed> $options): void

如果 $surrogate 查询声明了任何其他格式化程序，则将格式化程序函数添加到传递的 $query 中。由于 $surrogate 查询对应于关联的目标表，因此结果格式化程序将是将代理格式化程序应用于仅对应于该表的属性的结果。

参数

Cake\ORM\Query\SelectQuery $query: 将要应用格式化程序的查询
Cake\ORM\Query\SelectQuery $surrogate: 具有关联目标表的格式化程序的查询。
array<string, mixed> $options: 传递给 attachTo 方法的选项

返回值

空

_generateJunctionAssociations() ¶ protected

_generateJunctionAssociations(Cake\ORM\Table $junction, Cake\ORM\Table $source, Cake\ORM\Table $target): void

根据需要在联接表上生成关联。

生成以下关联

连接属于源，例如 ArticlesTags 属于 Tags
连接属于目标，例如 ArticlesTags 属于 Articles

您可以通过定义具有正确别名的关联来覆盖这些生成的关联。

参数

Cake\ORM\Table $junction: 连接表。
Cake\ORM\Table $source: 源表。
Cake\ORM\Table $target: 目标表。

返回值

空

抛出

InvalidArgumentException
如果预期关联与现有关联不兼容。

_generateSourceAssociations() ¶ protected

_generateSourceAssociations(Cake\ORM\Table $junction, Cake\ORM\Table $source): void

根据需要生成其他源表关联。

生成以下关联

源具有多个连接，例如 Tags 具有多个 ArticlesTags

您可以通过定义具有正确别名的关联来覆盖这些生成的关联。

参数

Cake\ORM\Table $junction: 连接表。
Cake\ORM\Table $source: 源表。

返回值

空

_generateTargetAssociations() ¶ protected

_generateTargetAssociations(Cake\ORM\Table $junction, Cake\ORM\Table $source, Cake\ORM\Table $target): void

根据需要生成互惠关联。

生成以下关联

目标具有多个连接，例如 Articles 具有多个 ArticlesTags
目标属于多个源，例如 Articles 属于多个 Tags。

您可以通过定义具有正确别名的关联来覆盖这些生成的关联。

参数

Cake\ORM\Table $junction: 连接表。
Cake\ORM\Table $source: 源表。
Cake\ORM\Table $target: 目标表。

返回值

空

_joinCondition() ¶ protected

_joinCondition(array<string, mixed> $options): array

返回 false，因为联接条件是在联接表中定义的。

参数

array<string, mixed> $options: 传递给 attachTo 方法的选项列表

返回值

数组

_junctionAssociationName() ¶ protected

_junctionAssociationName(): string

返回从目标表到联接表的关联的名称，此名称用于在查询中生成别名，并在稍后检索结果。

返回值

字符串

_junctionTableName() ¶ protected

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

设置联接表的名称。如果没有传递参数，则返回当前配置的名称。如果未找到，将生成基于关联表的默认名称。

参数

string|null $name optional: 连接表的名称。

返回值

字符串

_modelKey() ¶ protected

_modelKey(string $name): string

为关联创建正确的带下划线的模型键。

如果输入包含点，则假设右侧是真正的表名。

参数

string $name: 模型类名称

返回值

字符串

_modelNameFromKey() ¶ protected

_modelNameFromKey(string $key): string

从外键创建正确的模型名称。

参数

string $key: 外键

返回值

字符串

_options() ¶ protected

_options(array<string, mixed> $options): void

解析构造函数中传递的额外选项。

参数

array<string, mixed> $options: 构造函数中传递的原始选项列表

返回值

空

_pluginNamespace() ¶ protected

_pluginNamespace(string $pluginName): string

返回插件的命名空间。

参数

string $pluginName: 插件名称

返回值

字符串

_pluginPath() ¶ protected

_pluginPath(string $pluginName): string

找到插件的正确路径。扫描 $pluginPaths 中的插件。

参数

string $pluginName: 您想要的插件名称，例如 DebugKit

返回值

字符串

_pluralHumanName() ¶ protected

_pluralHumanName(string $name): string

创建视图中使用的复数人名。

参数

string $name: 控制器名称

返回值

字符串

_propertyName() ¶ protected

_propertyName(): string

返回基于关联名称的默认属性名称。

返回值

字符串

_saveLinks() ¶ protected

_saveLinks(Cake\Datasource\EntityInterface $sourceEntity, arrayCake\Datasource\EntityInterface> $targetEntities, array<string, mixed> $options): bool

在源实体和每个传递的目标实体之间创建链接。

参数

Cake\Datasource\EntityInterface $sourceEntity: 此关联中源表中的实体
arrayCake\Datasource\EntityInterface> $targetEntities: 要使用联接表链接到源实体的实体列表
array<string, mixed> $options: Table::save() 接受的选项列表

返回值

bool

_saveTarget() ¶ protected

_saveTarget(Cake\Datasource\EntityInterface $parentEntity, array $entities, array<string, mixed> $options): Cake\Datasource\EntityInterface|false

将每个实体持久化到目标表中，并在父实体和每个保存的目标实体之间创建链接。

参数

Cake\Datasource\EntityInterface $parentEntity: 包含要保存的目标实体的源实体。
array $entities: 要持久化到目标表并链接到父实体的实体列表
array<string, mixed> $options: Table::save() 接受的选项列表

返回值

Cake\Datasource\EntityInterface|false

抛出

InvalidArgumentException
如果父实体中表示关联的属性无法遍历

_singularHumanName() ¶ protected

_singularHumanName(string $name): string

创建视图中使用的单数人名。

参数

string $name: 控制器名称

返回值

字符串

_singularName() ¶ protected

_singularName(string $name): string

创建用于视图的单数名称。

参数

string $name: 要使用的名称

返回值

字符串

_variableName() ¶ protected

_variableName(string $name): string

创建视图的复数变量名。

参数

string $name: 要使用的名称

返回值

字符串

attachTo() ¶ public

attachTo(Cake\ORM\Query\SelectQuery $query, array<string, mixed> $options = []): void

更改查询对象，以在最终结果中包含关联的目标表数据。

选项数组接受以下键

includeFields: 是否在结果中包含目标模型字段
foreignKey: 要用作外键的字段名称，如果为 false，则不使用任何字段
conditions: 包含用于过滤联接的条件列表的数组
fields: 要在结果中包含的目标表中的字段列表
type: 要使用的联接类型（例如 INNER）

参数

Cake\ORM\Query\SelectQuery $query: 要更改以包含目标表数据的查询
array<string, mixed> $options optional: 要考虑的任何额外选项或覆盖

返回值

空

canBeJoined() ¶ public

canBeJoined(array<string, mixed> $options = []): bool

此关联是否可以直接在查询联接中表达。

参数

array<string, mixed> $options optional: 可以更改返回值的自定义选项键

返回值

bool

cascadeDelete() ¶ public

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

清除给定实体的联接表中的数据。

每个实现类都应该根据需要处理级联删除。

参数

Cake\Datasource\EntityInterface $entity: 开始级联删除的实体。
array<string, mixed> $options optional: 原始删除的选项。

返回值

bool

defaultRowValue() ¶ public

defaultRowValue(array<string, mixed> $row, bool $joined): array<string, mixed>

在为该关联追加一个具有默认空值的属性后，返回修改后的行，该属性取决于关联是通过联接还是通过外部获取。

参数

array<string, mixed> $row
bool $joined

返回值

array<string, mixed>

deleteAll() ¶ public

deleteAll(Cake\Database\Expression\QueryExpressionClosure|array|string|null $conditions): int

将删除操作代理到目标 Table::deleteAll() 方法。

参数

Cake\Database\Expression\QueryExpressionClosure|array|string|null $conditions: 要使用的条件，接受 Query::where() 可以接受的任何内容。

返回值

int

另请参见

\Cake\ORM\Table::deleteAll()

eagerLoader() ¶ public

eagerLoader(array<string, mixed> $options): Closure

渴望加载目标表中与源表中另一组记录相关的记录列表。源记录可以通过两种方式指定：第一种是通过传递一个在源表上查找的查询对象，另一种方式是通过显式传递源表的主键值数组。

传递相关源记录的必需方式由“策略”控制。当使用子查询策略时，它需要对源表进行查询。当使用选择策略时，将使用主键列表。

返回一个闭包，该闭包应为特定查询中返回的每条记录执行。此可调用对象将负责注入与每个传递的特定行相关的字段。

选项数组接受以下键

query: 设置用于查找源表记录的 SelectQuery 对象
keys: 来自源表的键列表
foreignKey: 用于关联两个表的字段名称
conditions: 要传递给查询 where() 方法的条件列表
sort: 记录应返回的方向
fields: 要从目标表中选择的字段列表
contain: 要急切加载与目标表相关联的相关表列表
strategy: 用于查找目标表记录的策略名称
nestKey: 当转换行时将在其下找到结果的数组键

参数

array<string, mixed> $options

返回值

Closure

exists() ¶ public

exists(Cake\Database\ExpressionInterfaceClosure|array|string|null $conditions): bool

将操作代理到目标表的 exists 方法，并在其后追加该关联的默认条件。

参数

Cake\Database\ExpressionInterfaceClosure|array|string|null $conditions: 用于检查是否有任何记录匹配的条件。

返回值

bool

另请参见

\Cake\ORM\Table::exists()

fetchTable() ¶ public

fetchTable(string|null $alias = null, array<string, mixed> $options = []): Cake\ORM\Table

用于获取表实例的便捷方法。

参数

string|null $alias optional: 您要获取的别名。应该采用驼峰命名法。如果为 `null`，则使用 `$defaultTable` 属性的值。
array<string, mixed> $options optional: 您要使用这些选项构建表。如果表已加载，则注册表选项将被忽略。

返回值

Cake\ORM\Table

抛出

Cake\Core\Exception\CakeException
如果 `$alias` 参数和 `$defaultTable` 属性都为 `null`。

另请参见

\Cake\ORM\TableLocator::get()

find() ¶ public

find(array<string, mixed>|string|null $type = null, mixed ...$args): Cake\ORM\Query\SelectQuery

将查找操作代理到目标表的 find 方法，并根据该关联配置相应地修改查询。

如果您的关联包含条件或查找器，则联接表将包含在查询的包含关联中。

参数

array<string, mixed>|string|null $type optional: 要执行的查询类型，如果传递一个数组，它将被解释为 `$options` 参数
mixed ...$args: 与查找器特定参数匹配的参数

\Cake\Database\Query::where() 的示例，了解数组的格式

getDependent() ¶ public

getDependent(): bool

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

返回布尔值 true，因为两个表都通过联接表拥有关联另一侧的行。

参数

Cake\ORM\Table $side: 具有所有权的潜在表

返回值

bool

junction() ¶ public

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

设置联接关系的表实例。如果没有传递参数，则返回当前配置的表实例。

参数

Cake\ORM\Table|string|null $table 可选: 连接表的名称或实例

返回值

Cake\ORM\Table

抛出

InvalidArgumentException
如果预期关联与现有关联不兼容。

junctionConditions() ¶ protected

junctionConditions(): array

返回专门引用联接表的过滤条件。

返回值

数组

link() ¶ public

link(Cake\Datasource\EntityInterface $sourceEntity, arrayCake\Datasource\EntityInterface> $targetEntities, array<string, mixed> $options = []): bool

通过在联接表中创建链接，将源实体关联到每个提供的目标实体。源实体和每个目标实体都假定已持久化，如果它们被标记为新实体或其状态未知，则将抛出异常。

使用此方法时，$targetEntities 中的所有实体将被附加到源实体中与该关联对象相对应的属性。

此方法不检查链接的唯一性。

示例

$newTags = $tags->find('relevant')->toArray();
$articles->getAssociation('tags')->link($article, $newTags);

链接后，$article->get('tags') 将包含 $newTags 中的所有标签

参数

Cake\Datasource\EntityInterface $sourceEntity: 属于此关联 source 侧的行
arrayCake\Datasource\EntityInterface> $targetEntities: 属于此关联 target 侧的实体列表
array<string, mixed> $options optional: 要传递给内部 save 调用的选项列表

返回值

bool

抛出

InvalidArgumentException
当检测到 $targetEntities 中的任何值尚未持久化时

replaceLinks() ¶ public

replaceLinks(Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array<string, mixed> $options = []): bool

用传递的链接替换源实体和目标之间现有的关联链接。此方法执行智能清理，已持久化并在 $targetEntities 中存在的链接将不会被删除，将为传递的目标实体创建新链接（这些实体尚未在数据库中），其余链接将被删除。

例如，如果一篇文章与标签 "cake" 和 "framework" 链接，并且您将包含 "cake"、"php" 和 "awesome" 标签的实体数组传递给此方法，则仅保留 "cake" 的链接，"framework" 的链接将被删除，"php" 和 "awesome" 的链接将被创建。

现有的链接不会被删除并重新创建，它们要么保持不变，要么被更新，以确保存储在连接行中的潜在额外信息不会丢失。通过确保相应的传递目标实体包含带有主键的连接属性以及要存储的任何额外信息，可以更新链接行。

成功后，传递的 $sourceEntity 将包含 $targetEntities 作为该关联对应属性的值。

此方法假定源实体和每个目标实体之间的链接都是唯一的。也就是说，对于源表中的任何给定行，连接表中只能有一条指向目标表中任何其他给定行的链接。

可以在第三个参数中传递用于保存新链接的其他选项，有关接受的选项的信息，请查看 Table::save()。

示例

$article->tags = [$tag1, $tag2, $tag3, $tag4];
$articles->save($article);
$tags = [$tag1, $tag3];
$articles->getAssociation('tags')->replaceLinks($article, $tags);

$article->get('tags') 最终将只包含 [$tag1, $tag3]

参数

Cake\Datasource\EntityInterface $sourceEntity: 此关联的源表中持久化的实体
array $targetEntities: 要链接的目标表中的实体列表
array<string, mixed> $options optional: 要传递给内部 save/delete 调用的选项列表，这些调用在持久化/更新新链接或删除现有链接时使用

返回值

bool

抛出

InvalidArgumentException
如果传递了未持久化的实体，或者其中任何一个实体缺少主键值

requiresKeys() ¶ public

requiresKeys(array<string, mixed> $options = []): bool

如果渴望加载过程需要一组拥有方表绑定键才能在查找器查询中用作过滤器，则返回 true。

参数

array<string, mixed> $options optional: 包含要使用策略的选项。

返回值

bool

saveAssociated() ¶ public

saveAssociated(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options = []): Cake\Datasource\EntityInterface|false

获取源表中的实体，并查看是否有与该关联的属性名称匹配的字段。找到的实体将通过传递提供的 $options 保存到该关联的目标表中。

使用 "append" 策略时，此函数将只创建该关联两侧之间的新链接。即使这些链接可能不存在于要保存的实体数组中，它也不会销毁现有链接。

使用 "replace" 策略时，将删除现有链接并创建连接表中的新链接。如果数据库中存在指向要通过此方法保存的某些实体的链接，则这些链接将被更新，而不是被删除。

参数

Cake\Datasource\EntityInterface $entity: 源表中的实体
array<string, mixed> $options optional: 要传递给目标表中 save 方法的选项

返回值

Cake\Datasource\EntityInterface|false

抛出

InvalidArgumentException
如果父实体中表示关联的属性无法遍历

另请参见

\Cake\ORM\Table::save()
\Cake\ORM\Association\BelongsToMany::replaceLinks()

setBindingKey() ¶ public

setBindingKey(list<string>|string $key): $this

设置表示与目标表绑定字段的字段的名称。如果未手动指定，则使用拥有方表的主键。

参数

list<string>|string $key: 用于将两个表链接在一起的表字段或字段

返回值

$this

setCascadeCallbacks() ¶ public

setCascadeCallbacks(bool $cascadeCallbacks): $this

设置级联删除是否也应该触发回调。

参数

bool $cascadeCallbacks: 级联回调开关值

返回值

$this

setClassName() ¶ public

setClassName(string $className): $this

设置目标表对象的类名。

参数

string $className: 要设置的类名。

返回值

$this

抛出

InvalidArgumentException
如果在解析目标表后设置类名，并且它与目标表的类名不匹配。

setConditions() ¶ public

setConditions(Closure|array $conditions): $this

设置从目标关联获取记录时始终包含的条件列表。

参数

Closure|array $conditions

返回值

$this

setDependent() ¶ public

setDependent(bool $dependent): $this

设置目标表上的记录是否依赖于源表。

这主要用于指示如果源表中的拥有记录被删除，则应删除记录。

如果未传递参数，则返回当前设置。

参数

bool $dependent: 设置依赖模式。使用 null 读取当前状态。

返回值

$this

setFinder() ¶ public

setFinder(array|string $finder): $this

设置用于从目标表获取行的默认查找器。

参数

array|string $finder: 要使用的查找器名称或查找器名称和选项数组。

返回值

$this

setForeignKey() ¶ public

setForeignKey(list<string>|string $key): $this

设置表示指向目标表的外键的字段的名称。

参数

list<string>|string $key: 用于将两个表链接在一起的键或键

返回值

$this

setJoinType() ¶ public

setJoinType(string $type): $this

设置将关联添加到查询时使用的联接类型。

参数

string $type: 要使用的连接类型（例如 INNER）

返回值

$this

setProperty() ¶ public

setProperty(string $name): $this

设置应使用目标表中的数据在源表记录中填充的属性名称。

参数

string $name: 关联属性的名称。使用 null 读取当前值。

返回值

$this

setSaveStrategy() ¶ public

setSaveStrategy(string $strategy): $this

设置应用于保存的策略。

参数

string $strategy: 要使用的策略名称

返回值

$this

抛出

InvalidArgumentException
如果传递了无效的策略名称

setSort() ¶ public

setSort(Cake\Database\ExpressionInterfaceClosure|arrayCake\Database\ExpressionInterface|string>|string $sort): $this

设置应返回目标记录的排序顺序。

参数

Cake\Database\ExpressionInterfaceClosure|arrayCake\Database\ExpressionInterface|string>|string $sort: 与 find() 兼容的排序子句

返回值

$this

setSource() ¶ public

setSource(Cake\ORM\Table $table): $this

设置关联源侧的表实例。

参数

Cake\ORM\Table $table: 要分配为源端的实例

返回值

$this

setStrategy() ¶ public

setStrategy(string $name): $this

设置用于获取关联记录的策略名称。请注意，某些关联类型可能没有实现，而是使用默认策略，因此对该设置的任何更改都会无效。

参数

string $name: 策略类型。使用 null 读取当前值。

返回值

$this

抛出

InvalidArgumentException
当提供无效的策略时。

setTableLocator() ¶ public

setTableLocator(Cake\ORM\Locator\LocatorInterface $tableLocator): $this

设置表定位器。

参数

Cake\ORM\Locator\LocatorInterface $tableLocator: LocatorInterface 实例。

返回值

$this

setTarget() ¶ public

setTarget(Cake\ORM\Table $table): $this

设置关联目标端的目标表实例。

参数

Cake\ORM\Table $table: 要分配为目标端的实例

返回值

$this

setTargetForeignKey() ¶ public

setTargetForeignKey(list<string>|string $key): $this

设置表示指向目标表的外键的字段的名称。

参数

list<string>|string $key: 用于将两个表链接在一起的键

返回值

$this

setThrough() ¶ public

setThrough(Cake\ORM\Table|string $through): $this

设置当前连接表，可以是 Table 实例的名称或实例本身。

参数

Cake\ORM\Table|string $through: Table 实例的名称或实例本身

返回值

$this

targetConditions() ¶ protected

targetConditions(): Closure|array|null

返回引用目标表的过滤条件。

任何字符串表达式或表达式对象也将在此列表中返回。

返回值

Closure|array|null

transformRow() ¶ public

transformRow(array<string, mixed> $row, string $nestKey, bool $joined, string|null $targetProperty = null): array

将与结果行关联的值正确嵌套到源结果中的正确数组键中。

参数

array<string, mixed> $row: 要转换的行
string $nestKey: 此关联结果应在其中找到的数组键
bool $joined: 行是否与该关联直接连接的结果
string|null $targetProperty 可选: 源结果中关联数据应嵌套的属性名称。如果没有提供，将使用默认名称。

返回值

数组

type() ¶ public

type(): string

获取关系类型。

返回值

字符串

unlink() ¶ public

unlink(Cake\Datasource\EntityInterface $sourceEntity, arrayCake\Datasource\EntityInterface> $targetEntities, array<string, mixed>|bool $options = []): bool

删除传递的源实体与提供的目标实体之间的所有链接。此方法假设所有传递的对象已持久化到数据库中，并且每个对象都包含主键值。

选项

除了 Table::delete() 接受的默认选项之外，还支持以下键

cleanProperty：是否删除存储在 $sourceEntity 中的 $targetEntities 中的所有对象（默认值：true）

默认情况下，此方法将取消设置存储在源实体中的每个实体对象。

示例

$article->tags = [$tag1, $tag2, $tag3, $tag4];
$tags = [$tag1, $tag2, $tag3];
$articles->getAssociation('tags')->unlink($article, $tags);

在数据库中删除后，$article->get('tags') 将只包含 [$tag4]

参数

Cake\Datasource\EntityInterface $sourceEntity: 此关联的源表中持久化的实体。
arrayCake\Datasource\EntityInterface> $targetEntities: 此关联的目标表中持久化的实体列表。
array<string, mixed>|bool $options 可选: 要传递给内部 delete 调用的选项列表，或作为 cleanProperty 键快捷方式的 boolean。

返回值

bool

抛出

InvalidArgumentException
如果传递了非持久化实体，或者其中任何一个缺少主键值。

updateAll() ¶ public

updateAll(Cake\Database\Expression\QueryExpressionClosure|array|string $fields, Cake\Database\Expression\QueryExpressionClosure|array|string|null $conditions): int

将更新操作代理到目标 Table::updateAll() 方法

参数

Cake\Database\Expression\QueryExpressionClosure|array|string $fields: 字段 => 新值的哈希。
Cake\Database\Expression\QueryExpressionClosure|array|string|null $conditions: 要使用的条件，接受 Query::where() 接受的任何内容。

返回值

int

另请参见

\Cake\ORM\Table::updateAll()

属性详情

`$_dependent` ¶ protected

`$defaultTable` ¶ protected

此对象的默认表别名。

类型

string|null

命名空间

BelongsToMany 类

常量

属性摘要

方法摘要

__call() public

__construct() public

__get() public

__isset() public

_appendFields() protected

_appendJunctionJoin() protected

_appendNotMatching() protected

_bindNewAssociations() protected

_camelize() protected

_checkPersistenceStatus() protected

_collectJointEntities() protected

_diffLinks() protected

_dispatchBeforeFind() protected

_entityName() protected

_extractFinder() protected

_fixtureName() protected

_formatAssociationResults() protected

_generateJunctionAssociations() protected

_generateSourceAssociations() protected

_generateTargetAssociations() protected

_joinCondition() protected

_junctionAssociationName() protected

_junctionTableName() protected

_modelKey() protected

_modelNameFromKey() protected

_options() protected

_pluginNamespace() protected

_pluginPath() protected

_pluralHumanName() protected

_propertyName() protected

_saveLinks() protected

_saveTarget() protected

_singularHumanName() protected

_singularName() protected

_variableName() protected

attachTo() public

canBeJoined() public

cascadeDelete() public

defaultRowValue() public

deleteAll() public

eagerLoader() public

exists() public

fetchTable() public

find() public

getBindingKey() public

getCascadeCallbacks() public

getClassName() public

getConditions() public

getDependent() public

getFinder() public

getForeignKey() public

getJoinType() public

getName() public

getProperty() public

getSaveStrategy() public

getSort() public

getSource() public

getStrategy() public

getTableLocator() public

getTarget() public

getTargetForeignKey() public

getThrough() public

isOwningSide() public

junction() public

junctionConditions() protected

link() public

replaceLinks() public

requiresKeys() public

saveAssociated() public

setBindingKey() public

setCascadeCallbacks() public

setClassName() public

setConditions() public

setDependent() public

setFinder() public