Flourish PHP Unframework

fORMRelated

Class Resources

Static Methods

Uses

Used By

static class, v1.0.0b44

Handles related record tasks for fActiveRecord classes

The functionality of this class only works with single-field FOREIGN KEY constraints.

Changes:
1.0.0b44Added missing information for has and list methods to reflect() 9/7/11
1.0.0b43Fixed some bugs in handling relationships between PHP 5.3 namespaced classes 5/26/11
1.0.0b42Fixed a bug with associateRecords() not associating record set via primary key 5/23/11
1.0.0b41Fixed a bug in generating errors messages for many-to-many relationships 3/7/11
1.0.0b40Updated getRelatedRecordName() to use fText if loaded 2/2/11
1.0.0b39Fixed a bug with validate() not properly removing validation messages about a related primary key value not being present yet, if the column and related column names were different 11/24/10
1.0.0b38Updated overrideRelatedRecordName() to prefix any namespace from $class to $related_class if not already present 11/24/10
1.0.0b37Fixed a documentation typo 11/4/10
1.0.0b36Fixed getPrimaryKeys() to not throw SQL exceptions 10/20/10
1.0.0b35Backwards Compatibility Break - changed the validation messages array to use nesting for child records 10/3/10
1.0.0b35Updated getPrimaryKeys() to always return primary keys in a consistent order when no order bys are specified 7/26/10
1.0.0b34Updated the class to work with fixes in fORMRelated 7/22/10
1.0.0b33Fixed the related table populate action to use the plural underscore_notation version of the related class name 7/8/10
1.0.0b32Backwards Compatibility Break - related table populate action now use the underscore_notation version of the class name instead of the related table name, allowing for related tables in non-standard schemas 6/23/10
1.0.0b31Fixed reflect() to properly show parameters for associate methods 6/8/10
1.0.0b30Fixed a bug where related record error messages could be overwritten if there were multiple related records with the same error 5/29/10
1.0.0b29Changed validation messages array to use column name keys 5/26/10
1.0.0b28Updated associateRecords() to accept just a single fActiveRecord 5/6/10
1.0.0b27Updated the class to force configure classes before peforming actions with them 3/30/10
1.0.0b26Fixed reflect() to show the proper return values for associate, link and populate methods 3/15/10
1.0.0b25Fixed 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.0b24Added the ability to associate a single record via primary key 3/3/10
1.0.0b23Fixed a column aliasing issue with SQLite 1/25/10
1.0.0b22Fixed a bug with associating a non-contiguous array of fActiveRecord objects 12/17/09
1.0.0b21Added 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.0b20Updated code for the new fORMDatabase and fORMSchema APIs 10/28/09
1.0.0b19Internal 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.0b18Fixed a bug in countRecords() that would occur when multiple routes existed to the table being counted 10/5/09
1.0.0b17Updated code for new fRecordSet API 9/16/09
1.0.0b16Fixed a bug with createRecord() not creating non-existent record when the related value is NULL 8/25/09
1.0.0b15Fixed a bug with createRecord() where foreign keys with a different column and related column name would not load properly 8/17/09
1.0.0b14Fixed a bug with createRecord() when a foreign key constraint is on a column other than the primary key 8/10/09
1.0.0b13setOrderBys() now (properly) only recognizes *-to-many relationships 7/31/09
1.0.0b12Changed how related record values are set and how related validation messages are ignored because of recursive relationships 7/29/09
1.0.0b11Fixed some bugs with one-to-one relationships 7/21/09
1.0.0b10Fixed a couple of bugs with validating related records 6/26/09
1.0.0b9Fixed a bug where store() would not save associations with no related records 6/23/09
1.0.0b8Changed associateRecords() to work for *-to-many instead of just many-to-many relationships 6/17/09
1.0.0b7Updated code for new fORM API, fixed API documentation bugs 6/15/09
1.0.0b6Updated code to use new fValidationException::formatField() method 6/4/09
1.0.0b5Added getPrimaryKeys() and setPrimaryKeys(), renamed setRecords() to setRecordSet() and tallyRecords() to setCount() 6/2/09
1.0.0b4Updated code to handle new association method for related records and new $related_records structure, added store() and validate() 6/2/09
1.0.0b3associateRecords() can now accept an array of records or primary keys instead of only an fRecordSet 6/1/09
1.0.0b2populateRecords() now accepts any input field keys instead of sequential ones starting from 0 5/3/09
1.0.0bThe 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

Signature

void associateRecord( string $class, array &$related_records, string $related_class, fActiveRecord|array|string|integer $record, string $route=NULL )

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

Signature

void associateRecords( string $class, array &$related_records, string $related_class, fRecordSet|array $records_to_associate, string $route=NULL )

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

Signature

fRecordSet buildRecords( string $class, array &$values, array &$related_records, string $related_class, string $route=NULL )

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

Signature

integer countRecords( string $class, array &$values, array &$related_records, string $related_class, string $route=NULL )

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

Signature

fActiveRecord createRecord( string $class, array $values, array &$related_records, string $related_class, string $route=NULL )

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 instance 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()

Signature

void flagForAssociation( string $class, array &$related_records, string $related_class, string $route=NULL )

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

Signature

array getPrimaryKeys( string $class, array &$values, array &$related_records, string $related_class, string $route=NULL )

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

Signature

void hasRecords( string $class, array &$values, array &$related_records, string $related_class, string $route=NULL )

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

Signature

void linkRecords( string $class, array &$related_records, string $related_class, string $route=NULL )

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

Signature

void populateRecords( string $class, array &$related_records, string $related_class, string $route=NULL )

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

Signature

void reflect( string $class, array &$signatures, boolean $include_doc_comments )

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

::registerValidationNameMethod() public

Registers a method to use to get a name for a related record when doing validation

Signature

void registerValidationNameMethod( string|fActiveRecord $class, string $related_class, string $method, string $route=NULL )

Parameters

string|fActiveRecord $class The class to register the method for
string $related_class The related class to register the method for
string $method The method to be called on the related class that will return the name
string $route The route to the related class

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

Signature

void setCount( string $class, array &$related_records, string $related_class, integer $count, string $route=NULL, 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

Signature

void setPrimaryKeys( string $class, array &$related_records, string $related_class, array $primary_keys, string $route=NULL )

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

Signature

void setRecordSet( string $class, array &$related_records, string $related_class, fRecordSet $records, string $route=NULL )

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

Signature

void store( string $class, array &$values, array &$related_records, boolean $force_cascade )

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

Signature

void storeManyToMany( string $class, array &$values, array $relationship, array $related_info )

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

Signature

void storeOneToStar( string $class, array &$values, array &$related_records, string $related_class, string $route, boolean $force_cascade )

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

Signature

void validate( string $class, 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