Class FOFTableRelations

Package: FrameworkOnFramework\table
Copyright: Copyright (C) 2010-2016 Nicholas K. Dionysopoulos / Akeeba Ltd. All rights reserved.
License: General Public License version 2 or later; see LICENSE.txt
Located at fof/table/relations.php

Methods summary

`public`	# `__construct( FOFTable $table )` Create a relations object based on the provided FOFTable instance Create a relations object based on the provided FOFTable instance Parameters `$table` `FOFTable` - $table The table instance used to initialise the relations
`public`	# `addChildRelation( string $itemName, string $tableClass = null, string $localKey = null, string $remoteKey = null, boolean $default = true )` Add a 1:1 forward (child) relation. This adds relations for the getChild() method. Add a 1:1 forward (child) relation. This adds relations for the getChild() method. In other words: does a table HAVE ONE child Parent and child relations works the same way. We have them separated as it makes more sense for us humans to read code like $item->getParent() and $item->getChild() than $item->getRelatedObject('someRandomKeyName') Parameters `$itemName` `string` - $itemName is how it will be known locally to the getRelatedItem method (singular) `$tableClass` `string` - $tableClass if skipped it is defined automatically as ComponentnameTableItemname `$localKey` `string` - $localKey is the column containing our side of the FK relation, default: our primary key `$remoteKey` `string` - $remoteKey is the remote table's FK column, default: componentname_itemname_id `$default` `boolean` - $default add as the default child relation?
`public`	# `addParentRelation( string $itemName, string $tableClass = null, string $localKey = null, string $remoteKey = null, boolean $default = true )` Defining an inverse 1:1 (parent) relation. You must specify at least the $tableClass or the $localKey. This adds relations for the getParent() method. Defining an inverse 1:1 (parent) relation. You must specify at least the $tableClass or the $localKey. This adds relations for the getParent() method. In other words: does a table BELONG TO ONE parent Parent and child relations works the same way. We have them separated as it makes more sense for us humans to read code like $item->getParent() and $item->getChild() than $item->getRelatedObject('someRandomKeyName') Parameters `$itemName` `string` - $itemName is how it will be known locally to the getRelatedItem method (singular) `$tableClass` `string` - $tableClass if skipped it is defined automatically as ComponentnameTableItemname `$localKey` `string` - $localKey is the column containing our side of the FK relation, default: componentname_itemname_id `$remoteKey` `string` - $remoteKey is the remote table's FK column, default: componentname_itemname_id `$default` `boolean` - $default Is this the default parent relationship?
`public`	# `addChildrenRelation( string $itemName, string $tableClass = null, string $localKey = null, string $remoteKey = null, boolean $default = true )` Defining a forward 1:∞ (children) relation. This adds relations to the getChildren() method. Defining a forward 1:∞ (children) relation. This adds relations to the getChildren() method. In other words: does a table HAVE MANY children? The children relation works very much the same as the parent and child relation. The difference is that the parent and child relations return a single table object, whereas the children relation returns an iterator to many objects. Parameters `$itemName` `string` - $itemName is how it will be known locally to the getRelatedItems method (plural) `$tableClass` `string` - $tableClass if skipped it is defined automatically as ComponentnameTableItemname `$localKey` `string` - $localKey is the column containing our side of the FK relation, default: our primary key `$remoteKey` `string` - $remoteKey is the remote table's FK column, default: componentname_itemname_id `$default` `boolean` - $default is this the default children relationship?
`public`	# `addMultipleRelation( string $itemName, string $tableClass = null, string $localKey = null, string $ourPivotKey = null, string $theirPivotKey = null, string $remoteKey = null, string $glueTable = null, boolean $default = true )` Defining a ∞:∞ (multiple) relation. This adds relations to the getMultiple() method. Defining a ∞:∞ (multiple) relation. This adds relations to the getMultiple() method. In other words: is a table RELATED TO MANY other records? Parameters `$itemName` `string` - $itemName is how it will be known locally to the getRelatedItems method (plural) `$tableClass` `string` - $tableClass if skipped it is defined automatically as ComponentnameTableItemname `$localKey` `string` - $localKey is the column containing our side of the FK relation, default: our primary key field name `$ourPivotKey` `string` - $ourPivotKey is the column containing our side of the FK relation in the pivot table, default: $localKey `$theirPivotKey` `string` - $theirPivotKey is the column containing the other table's side of the FK relation in the pivot table, default $remoteKey `$remoteKey` `string` - $remoteKey is the remote table's FK column, default: componentname_itemname_id `$glueTable` `string` - $glueTable is the name of the glue (pivot) table, default: #__componentname_thisclassname_itemname with plural items (e.g. #__foobar_users_roles) `$default` `boolean` - $default is this the default multiple relation?
`public`	# `removeRelation( string $itemName, string $type = null )` Removes a previously defined relation by name. You can optionally specify the relation type. Removes a previously defined relation by name. You can optionally specify the relation type. Parameters `$itemName` `string` - $itemName The name of the relation to remove `$type` `string` - $type [optional] The relation type (child, parent, children, ...)
`public`	# `clearRelations( string $type = null )` Removes all existing relations Removes all existing relations Parameters `$type` `string` - $type The type or relations to remove, omit to remove all relation types
`public boolean`	# `hasRelation( string $itemName, string $type = null )` Does the named relation exist? You can optionally specify the type. Does the named relation exist? You can optionally specify the type. Parameters `$itemName` `string` - $itemName The name of the relation to check `$type` `string` - $type [optional] The relation type (child, parent, children, ...) Returns `boolean`
`public array`	# `getRelation( string $itemName, string $type )` Get the definition of a relation Get the definition of a relation Parameters `$itemName` `string` - $itemName The name of the relation to check `$type` `string` - $type [optional] The relation type (child, parent, children, ...) Returns `array` Throws `RuntimeException` - When the relation is not found
`public FOFTable`	# `getRelatedItem( string $itemName, string $type = null )` Gets the item referenced by a named relation. You can optionally specify the type. Only single item relation types will be searched. Gets the item referenced by a named relation. You can optionally specify the type. Only single item relation types will be searched. Parameters `$itemName` `string` - $itemName The name of the relation to use `$type` `string` - $type [optional] The relation type (child, parent) Returns `FOFTable` Throws `RuntimeException` - If the named relation doesn't exist or isn't supposed to return single items
`public FOFDatabaseIterator`	# `getRelatedItems( string $itemName, string $type = null )` Gets the iterator for the items referenced by a named relation. You can optionally specify the type. Only multiple item relation types will be searched. Gets the iterator for the items referenced by a named relation. You can optionally specify the type. Only multiple item relation types will be searched. Parameters `$itemName` `string` - $itemName The name of the relation to use `$type` `string` - $type [optional] The relation type (children, multiple) Returns `FOFDatabaseIterator` Throws `RuntimeException` - If the named relation doesn't exist or isn't supposed to return single items
`public FOFTable`	# `getParent( string $itemName = null )` Gets a parent item Gets a parent item Parameters `$itemName` `string` - $itemName [optional] The name of the relation to use, skip to use the default parent relation Returns `FOFTable` Throws `RuntimeException` - When the relation is not found
`public FOFTable`	# `getChild( string $itemName = null )` Gets a child item Gets a child item Parameters `$itemName` `string` - $itemName [optional] The name of the relation to use, skip to use the default child relation Returns `FOFTable` Throws `RuntimeException` - When the relation is not found
`public FOFDatabaseIterator`	# `getChildren( string $itemName = null )` Gets an iterator for the children items Gets an iterator for the children items Parameters `$itemName` `string` - $itemName [optional] The name of the relation to use, skip to use the default children relation Returns `FOFDatabaseIterator` Throws `RuntimeException` - When the relation is not found
`public FOFDatabaseIterator`	# `getSiblings( string $itemName = null )` Gets an iterator for the sibling items. This relation is inferred from the parent relation. It returns all elements on the same table which have the same parent. Gets an iterator for the sibling items. This relation is inferred from the parent relation. It returns all elements on the same table which have the same parent. Parameters `$itemName` `string` - $itemName [optional] The name of the relation to use, skip to use the default children relation Returns `FOFDatabaseIterator` Throws `RuntimeException` - When the relation is not found
`public FOFDatabaseIterator`	# `getMultiple( string $itemName = null )` Gets an iterator for the multiple items Gets an iterator for the multiple items Parameters `$itemName` `string` - $itemName [optional] The name of the relation to use, skip to use the default multiple relation Returns `FOFDatabaseIterator` Throws `RuntimeException` - When the relation is not found
`protected FOFTable`	# `getTableFromRelation( array $relation )` Returns a FOFTable object based on a given relation Returns a FOFTable object based on a given relation Parameters `$relation` `array` - $relation Indexed array holding relation definition. tableClass => name of the related table class localKey => name of the local key remoteKey => name of the remote key Returns `FOFTable` Throws `RuntimeException` `InvalidArgumentException`
`protected FOFDatabaseIterator`	# `getIteratorFromRelation( array $relation )` Returns a FOFDatabaseIterator based on a given relation Returns a FOFDatabaseIterator based on a given relation Parameters `$relation` `array` - $relation Indexed array holding relation definition. tableClass => name of the related table class localKey => name of the local key remoteKey => name of the remote key pivotTable => name of the pivot table (optional) theirPivotKey => name of the remote key in the pivot table (mandatory if pivotTable is set) ourPivotKey => name of our key in the pivot table (mandatory if pivotTable is set) Returns `FOFDatabaseIterator` Throws `RuntimeException` `InvalidArgumentException`
`protected`	# `addBespokeSimpleRelation( string $relationType, string $itemName, string $tableClass, string $localKey, string $remoteKey, boolean $default )` Add any bespoke relation which doesn't involve a pivot table. Add any bespoke relation which doesn't involve a pivot table. Parameters `$relationType` `string` - $relationType The type of the relationship (parent, child, children) `$itemName` `string` - $itemName is how it will be known locally to the getRelatedItems method `$tableClass` `string` - $tableClass if skipped it is defined automatically as ComponentnameTableItemname `$localKey` `string` - $localKey is the column containing our side of the FK relation, default: componentname_itemname_id `$remoteKey` `string` - $remoteKey is the remote table's FK column, default: componentname_itemname_id `$default` `boolean` - $default is this the default children relationship?
`protected`	# `addBespokePivotRelation( string $relationType, string $itemName, string $tableClass, string $localKey, string $remoteKey, string $ourPivotKey, string $theirPivotKey, string $pivotTable, boolean $default )` Add any bespoke relation which involves a pivot table. Add any bespoke relation which involves a pivot table. Parameters `$relationType` `string` - $relationType The type of the relationship (multiple) `$itemName` `string` - $itemName is how it will be known locally to the getRelatedItems method `$tableClass` `string` - $tableClass if skipped it is defined automatically as ComponentnameTableItemname `$localKey` `string` - $localKey is the column containing our side of the FK relation, default: componentname_itemname_id `$remoteKey` `string` - $remoteKey is the remote table's FK column, default: componentname_itemname_id `$ourPivotKey` `string` - $ourPivotKey is the column containing our side of the FK relation in the pivot table, default: $localKey `$theirPivotKey` `string` - $theirPivotKey is the column containing the other table's side of the FK relation in the pivot table, default $remoteKey `$pivotTable` `string` - $pivotTable is the name of the glue (pivot) table, default: #__componentname_thisclassname_itemname with plural items (e.g. #__foobar_users_roles) `$default` `boolean` - $default is this the default children relationship?
`protected`	# `normaliseParameters( boolean $pivot = false, string & $itemName, string & $tableClass, string & $localKey, string & $remoteKey, string & $ourPivotKey, string & $theirPivotKey, string & $pivotTable )` Normalise the parameters of a relation, guessing missing values Normalise the parameters of a relation, guessing missing values Parameters `$pivot` `boolean` - $pivot Is this a many to many relation involving a pivot table? `$itemName` `string` - $itemName is how it will be known locally to the getRelatedItems method (plural) `$tableClass` `string` - $tableClass if skipped it is defined automatically as ComponentnameTableItemname `$localKey` `string` - $localKey is the column containing our side of the FK relation, default: componentname_itemname_id `$remoteKey` `string` - $remoteKey is the remote table's FK column, default: componentname_itemname_id `$ourPivotKey` `string` - $ourPivotKey is the column containing our side of the FK relation in the pivot table, default: $localKey `$theirPivotKey` `string` - $theirPivotKey is the column containing the other table's side of the FK relation in the pivot table, default $remoteKey `$pivotTable` `string` - $pivotTable is the name of the glue (pivot) table, default: #__componentname_thisclassname_itemname with plural items (e.g. #__foobar_users_roles)
`protected string`	# `normaliseItemName( string $itemName, boolean $pluralise = false )` Normalises the format of a relation name Normalises the format of a relation name Parameters `$itemName` `string` - $itemName The raw relation name `$pluralise` `boolean` - $pluralise Should I pluralise the name? If not, I will singularise it Returns `string` - The normalised relation key name

Magic methods summary

Properties summary

`protected array`	`$relations`	# Holds all known relation definitions Holds all known relation definitions
`protected array`	`$defaultRelation`	# Holds the default relations' keys Holds the default relations' keys
`protected FOFTable`	`$table`	# The table these relations are attached to The table these relations are attached to
`protected string`	`$componentName`	# The name of the component used by our attached table The name of the component used by our attached table
`protected string`	`$tableType`	# The type (table name without prefix and component name) of our attached table The type (table name without prefix and component name) of our attached table

Namespaces

Classes

Interfaces

Exceptions

Constants

Functions

Class FOFTableRelations

Methods summary

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Parameters

Parameters

Parameters

Returns

Magic methods summary

Properties summary