fORMRelatedstatic classv1.0.0b25
Handles related record tasks for fActiveRecord classes
The functionality of this class only works with single-field FOREIGN KEY constraints.
| 1.0.0b25 | Fixed a bug when storing a one-to-one related record with different column names on each end of the relationship 3/4/10 |
|---|---|
| 1.0.0b24 | Added the ability to associate a single record via primary key 3/3/10 |
| 1.0.0b23 | Fixed a column aliasing issue with SQLite 1/25/10 |
| 1.0.0b22 | Fixed a bug with associating a non-contiguous array of fActiveRecord objects 12/17/09 |
| 1.0.0b21 | Added support for the $force_cascade parameter of fActiveRecord::store(), added hasRecords() and fixed a bug with creating non-existent one-to-one related records 12/16/09 |
| 1.0.0b20 | Updated code for the new fORMDatabase and fORMSchema APIs 10/28/09 |
| 1.0.0b19 | Internal Backwards Compatibility Break - Added the $class parameter to storeManyToMany() - also fixed countRecords() to work across all databases, changed SQL statements to use value placeholders, identifier escaping and support schemas 10/22/09 |
| 1.0.0b18 | Fixed a bug in countRecords() that would occur when multiple routes existed to the table being counted 10/5/09 |
| 1.0.0b17 | Updated code for new fRecordSet API 9/16/09 |
| 1.0.0b16 | Fixed a bug with createRecord() not creating non-existent record when the related value is NULL 8/25/09 |
| 1.0.0b15 | Fixed a bug with createRecord() where foreign keys with a different column and related column name would not load properly 8/17/09 |
| 1.0.0b14 | Fixed a bug with createRecord() when a foreign key constraint is on a column other than the primary key 8/10/09 |
| 1.0.0b13 | setOrderBys() now (properly) only recognizes *-to-many relationships 7/31/09 |
| 1.0.0b12 | Changed how related record values are set and how related validation messages are ignored because of recursive relationships 7/29/09 |
| 1.0.0b11 | Fixed some bugs with one-to-one relationships 7/21/09 |
| 1.0.0b10 | Fixed a couple of bugs with validating related records 6/26/09 |
| 1.0.0b9 | Fixed a bug where store() would not save associations with no related records 6/23/09 |
| 1.0.0b8 | Changed associateRecords() to work for *-to-many instead of just many-to-many relationships 6/17/09 |
| 1.0.0b7 | Updated code for new fORM API, fixed API documentation bugs 6/15/09 |
| 1.0.0b6 | Updated code to use new fValidationException::formatField() method 6/4/09 |
| 1.0.0b5 | Added getPrimaryKeys() and setPrimaryKeys(), renamed setRecords() to setRecordSet() and tallyRecords() to setCount() 6/2/09 |
| 1.0.0b4 | Updated code to handle new association method for related records and new $related_records structure, added store() and validate() 6/2/09 |
| 1.0.0b3 | associateRecords() can now accept an array of records or primary keys instead of only an fRecordSet 6/1/09 |
| 1.0.0b2 | populateRecords() now accepts any input field keys instead of sequential ones starting from 0 5/3/09 |
| 1.0.0b | The initial implementation 12/30/07 |
Static Methods
::associateRecord() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Creates associations for one-to-one relationships
Signatures
void associateRecord( string $class, string $related_class, fActiveRecord|array|string|integer $record, string $route )
void associateRecord( array $related_records )
Parameters
| string | $class | The class to get the related values for |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class we are associating with the current record |
| fActiveRecord|array|string|integer | $record | The record (or primary key of the record) to be associated |
| string | $route | The route to use between the current class and the related class |
::associateRecords() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Creates associations for *-to-many relationships
Signatures
void associateRecords( string $class, string $related_class, fRecordSet|array $records_to_associate, string $route )
void associateRecords( array $related_records )
Parameters
| string | $class | The class to get the related values for |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class we are associating with the current record |
| fRecordSet|array | $records_to_associate | An fRecordSet, an array or records, or an array of primary keys of the records to be associated |
| string | $route | The route to use between the current class and the related class |
::buildRecords() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Builds a set of related records along a one-to-many or many-to-many relationship
Signatures
fRecordSet buildRecords( string $class, string $related_class, string $route )
fRecordSet buildRecords( array $values, array $related_records )
Parameters
| string | $class | The class to get the related values for |
| array | &$values | The values for the fActiveRecord class |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class that is related to the current record |
| string | $route | The route to follow for the class specified |
Returns
A record set of the related records
::countRecords() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Counts the number of related one-to-many or many-to-many records
Signatures
integer countRecords( string $class, string $related_class, string $route )
integer countRecords( array $values, array $related_records )
Parameters
| string | $class | The class to get the related values for |
| array | &$values | The values for the fActiveRecord class |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class that is related to the current record |
| string | $route | The route to follow for the class specified |
Returns
The number of related records
::createRecord() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Builds the object for the related class specified
Signatures
fActiveRecord createRecord( string $class, array $values, string $related_class, string $route )
fActiveRecord createRecord( array $related_records )
Parameters
| string | $class | The class to create the related record for |
| array | $values | The values existing in the fActiveRecord class |
| array | &$related_records | The related records for the record |
| string | $related_class | The related class name |
| string | $route | The route to the related class |
Returns
An instace of the class specified
::determineFirstPKColumn() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Figures out the first primary key column for a related class that is not the related column
Signature
string determineFirstPKColumn( string $class, string $related_class, string $route )
Parameters
| string | $class | The class name of the main class |
| string | $related_class | The related class being filtered for |
| string | $route | The route to the related class |
Returns
The first primary key column in the related class
::determineRequestFilter() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Figures out what filter to pass to fRequest::filter() for the specified related class
Signature
string determineRequestFilter( string $class, string $related_class, string $route )
Parameters
| string | $class | The class name of the main class |
| string | $related_class | The related class being filtered for |
| string | $route | The route to the related class |
Returns
The prefix to filter the request fields by
::flagForAssociation() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Sets the related records for a *-to-many relationship to be associated upon fActiveRecord::store()
Signatures
void flagForAssociation( string $class, string $related_class, string $route )
void flagForAssociation( array $related_records )
Parameters
| string | $class | The class to associate the related records to |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class we are associating with the current record |
| string | $route | The route to use between the current class and the related class |
::getOrderBys() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Gets the ordering to use when returning an fRecordSet of related objects
Signature
array getOrderBys( string $class, string $related_class, string $route )
Parameters
| string | $class | The class to get the order bys for |
| string | $related_class | The related class the ordering rules apply to |
| string | $route | The route to the related table, should be a column name in the current table or a join table name |
Returns
An array of the order bys - see fRecordSet::build() for format
::getPrimaryKeys() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Gets the primary keys of the related records for *-to-many relationships
Signatures
array getPrimaryKeys( string $class, string $related_class, string $route )
array getPrimaryKeys( array $values, array $related_records )
Parameters
| string | $class | The class to get the related primary keys for |
| array | &$values | The values for the fActiveRecord class |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class that is related to the current record |
| string | $route | The route to follow for the class specified |
Returns
The primary keys of the related records
::getRelatedRecordName() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Returns the record name for a related class
The default record name of a related class is the result of fGrammar::humanize() called on the class.
Signature
string getRelatedRecordName( string $class, string $related_class, $route=NULL )
Parameters
| string | $class | The class to get the related class name for |
| string | $related_class | The related class to get the record name of |
| $route |
Returns
The record name for the related class specified
::hasRecords() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Indicates if a record has a one-to-one or any *-to-many related records
Signatures
void hasRecords( string $class, string $related_class, string $route )
void hasRecords( array $values, array $related_records )
Parameters
| string | $class | The class to check related records for |
| array | &$values | The values for the record we are checking |
| array | &$related_records | The related records for the record we are checking |
| string | $related_class | The related class we are checking for |
| string | $route | The route to the related class |
::linkRecords() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Parses associations for many-to-many relationships from the page request
Signatures
void linkRecords( string $class, string $related_class, string $route )
void linkRecords( array $related_records )
Parameters
| string | $class | The class to get link the related records to |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The related class to populate |
| string | $route | The route to the related class |
::overrideRelatedRecordName() public
Allows overriding of default record names or related records
The default record name of a related record is the result of fGrammar::humanize() called on the class name.
Signature
void overrideRelatedRecordName( mixed $class, mixed $related_class, string $record_name, string $route=NULL )
Parameters
| mixed | $class | The class name or instance of the class to set the related record name for |
| mixed | $related_class | The name of the related class, or an instance of it |
| string | $record_name | The human version of the related record |
| string | $route | The route to the related class |
::populateRecords() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Sets the values for records in a one-to-many relationship with this record
Signatures
void populateRecords( string $class, string $related_class, string $route )
void populateRecords( array $related_records )
Parameters
| string | $class | The class to populate the related records of |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The related class to populate |
| string | $route | The route to the related class |
::reflect() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Adds information about methods provided by this class to fActiveRecord
Signatures
void reflect( string $class, boolean $include_doc_comments )
void reflect( array $signatures )
Parameters
| string | $class | The class to reflect the related record methods for |
| array | &$signatures | The associative array of {method_name} => {signature} |
| boolean | $include_doc_comments | If the doc block comments for each method should be included |
::reset() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Resets the configuration of the class
Signature
void reset( )
::setCount() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Records the number of related one-to-many or many-to-many records
Signatures
void setCount( string $class, string $related_class, integer $count, string $route )
void setCount( array $related_records, array $values )
Parameters
| string | $class | The class to set the related records count for |
| array | &$values | The values for the fActiveRecord class |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class that is related to the current record |
| integer | $count | The number of records |
| string | $route | The route to follow for the class specified |
::setOrderBys() public
Sets the ordering to use when returning an fRecordSet of related objects
Signature
void setOrderBys( mixed $class, string $related_class, array $order_bys, string $route=NULL )
Parameters
| mixed | $class | The class name or instance of the class this ordering rule applies to |
| string | $related_class | The related class we are getting info from |
| array | $order_bys | An array of the order bys for this table.column combination - see fRecordSet::build() for format |
| string | $route | The route to the related table, this should be a column name in the current table or a join table name |
::setPrimaryKeys() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Sets the related records for *-to-many relationships, providing only primary keys
Signatures
void setPrimaryKeys( string $class, string $related_class, array $primary_keys, string $route )
void setPrimaryKeys( array $related_records )
Parameters
| string | $class | The class to set the related primary keys for |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class we are setting the records for |
| array | $primary_keys | The records to set |
| string | $route | The route to use between the current class and the related class |
::setRecordSet() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Sets the related records for *-to-many relationships
Signatures
void setRecordSet( string $class, string $related_class, fRecordSet $records, string $route )
void setRecordSet( array $related_records )
Parameters
| string | $class | The class to set the related records for |
| array | &$related_records | The related records existing for the fActiveRecord class |
| string | $related_class | The class we are associating with the current record |
| fRecordSet | $records | The records are associating |
| string | $route | The route to use between the current class and the related class |
::store() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Stores any many-to-many associations or any one-to-many records that have been flagged for association
Signatures
void store( string $class, boolean $force_cascade )
void store( array $values, array $related_records )
Parameters
| string | $class | The class to store the related records for |
| array | &$values | The current values for the main record being stored |
| array | &$related_records | The related records array |
| boolean | $force_cascade | This flag will be passed to the fActiveRecord::delete() method on related records that are being deleted |
::storeManyToMany() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Associates a set of many-to-many related records with the current record
Signatures
void storeManyToMany( string $class, array $relationship, array $related_info )
void storeManyToMany( array $values )
Parameters
| string | $class | The class the relationship is being stored for |
| array | &$values | The current values for the main record being stored |
| array | $relationship | The information about the relationship between this object and the records in the record set |
| array | $related_info | An array containing the keys 'record_set', 'count', 'primary_keys' and 'associate' |
::storeOneToStar() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Stores a set of one-to-many related records in the database
Signatures
void storeOneToStar( string $class, string $related_class, string $route, boolean $force_cascade )
void storeOneToStar( array $values, array $related_records )
Parameters
| string | $class | The class to store the related records for |
| array | &$values | The current values for the main record being stored |
| array | &$related_records | The related records array |
| string | $related_class | The related class being stored |
| string | $route | The route to the related class |
| boolean | $force_cascade | This flag will be passed to the fActiveRecord::delete() method on related records that are being deleted |
Throws
- fValidationException
- When one of the "many" records throws an exception from fActiveRecord::store()
::validate() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Validates any many-to-many associations or any one-to-many records that have been flagged for association
Signatures
void validate( string $class )
void validate( array $values, array $related_records )
Parameters
| string | $class | The class to validate the related records for |
| array | &$values | The values for the object |
| array | &$related_records | The related records for the object |
