\Dewdrop\Db\ManyToManyRelationship

This class configures and offers utilities for managing many-to-many relationships in your database. Typically, you won't instantiate and interact with this class directly. Rather, you'll register a new relationship by calling hasMany() in your table class.

Typically, this class only needs a reference to the \Dewdrop\Db\Table object that created it and the name of the cross-reference table leveraged for this many-to-many relationship. From there it will determine which column references back from the cross-reference table to the source table and which other foreign key in the cross-reference table points to the options table.

If those items can't be determined, you can pass those additional options to this class explicitly (typically using the $additionalOptions parameter of \Dewdrop\Db\Table).

Summary

Methods
Properties
Constants
__construct()
setOptions()
setAllowDuplicateValues()
setSourceTable()
getSourceTable()
setXrefTableName()
setSourceColumnName()
getSourceColumnName()
setXrefAnchorColumnName()
getXrefAnchorColumnName()
setXrefReferenceColumnName()
getXrefReferenceColumnName()
setReferenceTableName()
getReferenceTableName()
setReferenceColumnName()
getReferenceColumnName()
setReferenceTitleColumn()
augmentSelect()
loadInitialValue()
getFieldMetadata()
getOptionPairsReference()
getFilterSubquery()
setSaveCallback()
save()
defaultSave()
buildDeleteWhereClause()
No public properties found
No constants found
loadXrefTableMetadata()
No protected properties found
N/A
findReferenceTitleColumn()
$sourceTable
$sourceColumnName
$xrefTableName
$xrefAnchorColumnName
$xrefReferenceColumnName
$referenceTableName
$referenceColumnName
$xrefMetadata
$referenceTitleColumn
$allowDuplicateValues
$saveCallback
N/A

Properties

$sourceTable

$sourceTable : \Dewdrop\Db\Table

A reference to the Dewdrop\Db\Table object that created this relationship in a hasMany() call.

Type

\Dewdrop\Db\Table

$sourceColumnName

$sourceColumnName : string

The name of the column in the source table that is referenced by the cross-reference table. This is typically, though not necessarily, the source table's primary key.

Type

string

$xrefTableName

$xrefTableName : string

The name of the cross-reference table where this relationship is stored in the database.

Type

string

$xrefAnchorColumnName

$xrefAnchorColumnName : string

The name of the column in the cross-reference table that points back to the source table.

Type

string

$xrefReferenceColumnName

$xrefReferenceColumnName : string

The name of the column in the cross-reference table that points to the reference, or options, table.

Type

string

$referenceTableName

$referenceTableName : string

The name of the reference, or options, table that sits on the other side of the many-to-many relationship from the source table.

Type

string

$referenceColumnName

$referenceColumnName : string

The name of the reference column that ties the cross-reference table to the reference table.

Type

string

$xrefMetadata

$xrefMetadata : array

The loaded DB metadata definition for the cross reference table.

Type

array

$referenceTitleColumn

$referenceTitleColumn : string|\Dewdrop\Db\Expr

Title column names or Expr objects that can be used to represent cross-reference values. If the reference table has a "name" or "title" column that will be used automatically, but you can use setReferenceTitleColumn() to override that behavior.

Type

string|\Dewdrop\Db\Expr

$allowDuplicateValues

$allowDuplicateValues : boolean

Whether duplicate values should be saved for this field. By default, we assume a ManyToMany is something that could be well represented by a checkbox list in a UI.

In some cases, however, the same item can be associated with your record many times. If that is the case, set this to true to allow those values to be added.

Type

boolean

$saveCallback

$saveCallback : callable

A callback that is used in place of the default save method.

Type

callable

Methods

__construct()

__construct(\Dewdrop\Db\Table  $sourceTable, string  $xrefTableName) 

Create relationship using the supplied source table and cross-reference table name.

Parameters

\Dewdrop\Db\Table $sourceTable
string $xrefTableName

setOptions()

setOptions(array  $options) : \Dewdrop\Db\ManyToMany\Relationship

Set one or more options using the supplied array of name-value pairs. If the named option does not have a setter method in this class, an exception will be thrown.

Parameters

array $options

Throws

\Dewdrop\Exception

Returns

\Dewdrop\Db\ManyToMany\Relationship

setAllowDuplicateValues()

setAllowDuplicateValues(boolean  $allowDuplicateValues) : $this

Parameters

boolean $allowDuplicateValues

Returns

$this

getSourceTable()

getSourceTable() : \Dewdrop\Db\Table

Get the source table this relationship is associated with.

Returns

\Dewdrop\Db\Table

setXrefTableName()

setXrefTableName(string  $xrefTableName) : \Dewdrop\Db\ManyToMany\Relationship

Set the name of the cross-reference table that is used to store the records for this many-to-many relationship.

Parameters

string $xrefTableName

Returns

\Dewdrop\Db\ManyToMany\Relationship

setSourceColumnName()

setSourceColumnName(string  $sourceColumnName) : \Dewdrop\Db\ManyToMany\Relationship

Set the name of the column in the source table that is referenced by the cross reference table.

Parameters

string $sourceColumnName

Returns

\Dewdrop\Db\ManyToMany\Relationship

getSourceColumnName()

getSourceColumnName() : string

Get the name of the column in the source table that is refernced by the cross-reference table. If this is not set explicitly, we'll attempt to auto-detect it using the cross-reference table's metadata, looking for any references that point back to the source table.

Throws

\Dewdrop\Exception

Returns

string

setXrefAnchorColumnName()

setXrefAnchorColumnName(string  $xrefAnchorColumnName) : \Dewdrop\Db\ManyToMany\Relationship

Set the name of the column in the cross-reference table that is used to tie it back to the source table.

Parameters

string $xrefAnchorColumnName

Returns

\Dewdrop\Db\ManyToMany\Relationship

getXrefAnchorColumnName()

getXrefAnchorColumnName() : string

Get the name of the column that ties the cross-reference table back to the source table that created this many-to-many relationship. If this is not set manually, we'll look at the references defined on the cross- reference table and return the column from the first references that points back to the source table.

Throws

\Dewdrop\Exception

Returns

string

setXrefReferenceColumnName()

setXrefReferenceColumnName(string  $xrefReferenceColumnName) : \Dewdrop\Db\ManyToMany\Relationship

Set the name of the column in the cross-reference table that is used to reference the table containing the options for this relationship.

For example, if you've added this relationship to your "projects" table and the cross-reference table is "project_staff", this column is likely "staff_id".

Parameters

string $xrefReferenceColumnName

Returns

\Dewdrop\Db\ManyToMany\Relationship

getXrefReferenceColumnName()

getXrefReferenceColumnName() : string

Get the cross-reference table reference column. If it has not been set already, we try to auto-detect the column name using the cross-reference table's metadata. Basically, we look for a foreign key that does not reference the source table.

Throws

\Dewdrop\Exception

Returns

string

setReferenceTableName()

setReferenceTableName(string  $referenceTableName) : \Dewdrop\Db\ManyToMany\Relationship

Set the name of the table where the options are stored for this relationship. For example, if you've added this relationship to your "projects" table and the cross-reference table is "project_staff", this property will likely be "staff".

Parameters

string $referenceTableName

Returns

\Dewdrop\Db\ManyToMany\Relationship

getReferenceTableName()

getReferenceTableName() : string

Get the reference table name. If it hasn't been set already, we will retrieve the table name using the cross-reference table metadata.

Returns

string

setReferenceColumnName()

setReferenceColumnName(string  $referenceColumnName) : \Dewdrop\Db\ManyToMany\Relationship

Set the name of the column in the reference table that is linked to from the cross-reference table. For example, if you've added this relationship to your "projects" table and the cross-reference table is "project_staff", this property will like be "staff_id" or "id", depending upon your primary key naming conventions.

Parameters

string $referenceColumnName

Returns

\Dewdrop\Db\ManyToMany\Relationship

getReferenceColumnName()

getReferenceColumnName() : string

Get the reference column name. If it hasn't been set already, we will retrieve the column name using the cross-reference table metadata.

Returns

string

setReferenceTitleColumn()

setReferenceTitleColumn(string|\Dewdrop\Db\Expr  $titleColumn) : $this

Set the name of the column (or an Expr) that should be used when building the list of values to add to a Select in augmentSelect().

Parameters

string|\Dewdrop\Db\Expr $titleColumn

Returns

$this

augmentSelect()

augmentSelect(\Dewdrop\Db\Select  $select, string  $name) : \Dewdrop\Db\Select

Augment the provided Select object with a comma-separated list of values for this many-to-many relationship, using the name parameter as the name of the value in the resultset.

Parameters

\Dewdrop\Db\Select $select
string $name

Returns

\Dewdrop\Db\Select

loadInitialValue()

loadInitialValue(\Dewdrop\Db\Row  $row) : array

Using the supplied source table row, retrieve the initial value for this relationship. This is typically called by \Dewdrop\Db\Row when get() is first called for this relationship.

Parameters

\Dewdrop\Db\Row $row

Returns

array

getFieldMetadata()

getFieldMetadata() : array

Get the metadata associated with the reference column in this relationship's cross reference table. This metadata is used in \Dewdrop\Db\ManyToMany\Field objects to allow them validate array members according to the DB metadata.

Returns

array

getOptionPairsReference()

getOptionPairsReference() : array

Get the reference definition from the cross-reference table metadata that can be used by to configure an OptionPairs object. Whereas in a one-to-many relationship, the reference needed to get a list of options would be on the source table itself, in the case of a many-to-many relationship, that reference is instead on the cross-reference table.

Throws

\Dewdrop\Exception

Returns

array

getFilterSubquery()

getFilterSubquery(integer  $value) : string

Get a subquery that can be used when filtering by a many-to-many field.

Basically gets all the anchor column values that are associated with the selected reference column value in the cross-reference table.

Parameters

integer $value

Returns

string

setSaveCallback()

setSaveCallback(callable  $callback) : $this

Register a save callback.

Parameters

callable $callback

Throws

\Dewdrop\Exception

Returns

$this

save()

save(array  $xrefValues, mixed  $anchorValue) : integer

Save new values for this relationship. This is typically called from \Dewdrop\Db\Table when running insert() or update().

Parameters

array $xrefValues
mixed $anchorValue

Returns

integer

defaultSave()

defaultSave(array  $xrefValues, mixed  $anchorValue) : integer

Save new values for this relationship. This is typically called from \Dewdrop\Db\Table when running insert() or update().

Parameters

array $xrefValues
mixed $anchorValue

Returns

integer

buildDeleteWhereClause()

buildDeleteWhereClause(\Dewdrop\Db\Adapter  $db, array  $xrefValues, mixed  $anchorValue) : string

Build a WHERE clause for use in deleting cross-reference values while saving. If we have no cross-reference values, we delete all cross-reference rows with the given anchor value. Otherwise, we only delete those rows that are not related to the newly supplied $xrefValues.

Parameters

\Dewdrop\Db\Adapter $db
array $xrefValues
mixed $anchorValue

Returns

string

loadXrefTableMetadata()

loadXrefTableMetadata() : array

Load the cross-reference table metadata.

Returns

array

findReferenceTitleColumn()

findReferenceTitleColumn() : \Dewdrop\Db\Expr|string

Attempt to get a reasonable reference title column for many-to-many values retrieved in augmentSelect(). Will use name or title, if available, and then fall back to the first column in the reference table. You can override this behavior with setReferenceTitleColumn().

Throws

\Dewdrop\Exception

Returns

\Dewdrop\Db\Expr|string