fORMstatic classv1.0.0b17
Dynamically handles many centralized object-relational mapping tasks
| 1.0.0b17 | Changed enableSchemaCaching() to rely on fDatabaseclearCache() instead of explicitly calling fSQLTranslation::clearCache() 3/9/10 |
|---|---|
| 1.0.0b16 | Backwards Compatibility Break - renamed addCustomClassToTableMapping() to mapClassToTable(). Added getDatabaseName() and mapClassToDatabase(). Updated code for new fORMDatabase and fORMSchema APIs 10/28/09 |
| 1.0.0b15 | Added support for fActiveRecord to getRecordName() 10/6/09 |
| 1.0.0b14 | Updated documentation for registerActiveRecordMethod() to include info about prefix method matches 8/7/09 |
| 1.0.0b13 | Updated documentation for registerRecordSetMethod() 7/14/09 |
| 1.0.0b12 | Updated callReflectCallbacks() to accept a class name instead of an object 7/13/09 |
| 1.0.0b11 | Added registerInspectCallback() and callInspectCallbacks() 7/13/09 |
| 1.0.0b10 | Fixed a bug with objectify() caching during NULL date/time/timestamp values and breaking further objectification 6/18/09 |
| 1.0.0b9 | Added caching for performance and changed some method APIs to only allow class names instead of instances 6/15/09 |
| 1.0.0b8 | Updated documentation to reflect removal of $associate parameter for callbacks passed to registerRecordSetMethod() 6/2/09 |
| 1.0.0b7 | Added enableSchemaCaching() to replace fORMSchema::enableSmartCaching() 5/4/09 |
| 1.0.0b6 | Added the ability to pass a class instance to addCustomClassTableMapping() 2/23/09 |
| 1.0.0b5 | Backwards compatibility break - renamed addCustomTableClassMapping() to addCustomClassTableMapping() and swapped the parameters 1/26/09 |
| 1.0.0b4 | Fixed a bug with retrieving fActiveRecord methods registered for all classes 1/14/09 |
| 1.0.0b3 | Fixed a static method callback constant 12/17/08 |
| 1.0.0b2 | Added replicate() and registerReplicateCallback() for fActiveRecord::replicate() 12/12/08 |
| 1.0.0b | The initial implementation 8/4/07 |
Static Methods
::callHookCallbacks() 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
Calls the hook callbacks for the class and hook specified
Signatures
void callHookCallbacks( fActiveRecord $object, string $hook )
void callHookCallbacks( array $values, array $old_values, array $related_records, array $cache, mixed $parameter=NULL )
Parameters
| fActiveRecord | $object | The instance of the class to call the hook for |
| string | $hook | The hook to call |
| array | &$values | The current values of the record |
| array | &$old_values | The old values of the record |
| array | &$related_records | Records related to the current record |
| array | &$cache | The cache array of the record |
| mixed | &$parameter | The parameter to send the callback |
::callInspectCallbacks() 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
Calls all inspect callbacks for the class and column specified
Signatures
void callInspectCallbacks( string $class, string $column )
void callInspectCallbacks( array $metadata )
Parameters
| string | $class | The class to inspect the column of |
| string | $column | The column to inspect |
| array | &$metadata | The associative array of data about the column |
::callReflectCallbacks() 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
Calls all reflect callbacks for the class passed
Signatures
void callReflectCallbacks( string $class, boolean $include_doc_comments )
void callReflectCallbacks( array $signatures )
Parameters
| string | $class | The class to call the callbacks for |
| array | &$signatures | The associative array of {method_name} => {signature} |
| boolean | $include_doc_comments | If the doc comments should be included in the signature |
::checkHookCallback() 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
Checks to see if any (or a specific) callback has been registered for a specific hook
Signature
boolean checkHookCallback( string $class, string $hook, array $callback=NULL )
Parameters
| string | $class | The name of the class |
| string | $hook | The hook to check |
| array | $callback | The specific callback to check for |
Returns
If the specified callback exists
::classize() public
Takes a table and turns it into a class name - uses custom mapping if set
Signature
string classize( string $table )
Parameters
| string | $table | The table name |
Returns
The class name
::defineActiveRecordClass() public
Will dynamically create an fActiveRecord-based class for a database table
Normally this would be called from an __autoload() function.
This method will only create classes for tables in the default ORM database.
Signature
void defineActiveRecordClass( string $class )
Parameters
| string | $class | The name of the class to create |
::enableSchemaCaching() public
Enables caching on the fDatabase, fSQLTranslation and fSchema objects used for the ORM
This method will cache database schema information to the three objects that use it during normal ORM operation: fDatabase, fSQLTranslation and fSchema. To allow for schema changes without having to manually clear the cache, all cached information will be cleared if any fUnexpectedException objects are thrown.
This method should be called right after fORMDatabase::attach().
Signature
void enableSchemaCaching( fCache $cache, string $database_name='default', string $key_token=NULL )
Parameters
| fCache | $cache | The object to cache schema information to |
| string | $database_name | The database to enable caching for |
| string | $key_token | This is a token that is used in cache keys to prevent conflicts for server-wide caches - when non-NULL the document root is used |
::getActiveRecordMethod() 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 a matching callback for the class and method specified
The callback returned will be determined by the following logic:
1. If an exact callback has been defined for the method, it will be returned 2. If a callback in the form {prefix}* has been defined that matches the method, it will be returned 3. NULL will be returned
Signature
string|null getActiveRecordMethod( string $class, string $method )
Parameters
| string | $class | The name of the class |
| string | $method | The method to get the callback for |
Returns
The callback for the method or NULL if none exists - see method description for details
::getClass() 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
Takes a class name or class and returns the class name
Signature
string getClass( mixed $class )
Parameters
| mixed | $class | The object to get the name of, or possibly a string already containing the class |
Returns
The class name
::getColumnName() 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 column name
The default column name is the result of calling fGrammar::humanize() on the column.
Signature
string getColumnName( string $class, string $column )
Parameters
| string | $class | The class name the column is part of |
| string | $column | The database column |
Returns
The column name for the column specified
::getDatabaseName() 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 name for the database used by the class specified
Signature
string getDatabaseName( string $class )
Parameters
| string | $class | The class name to get the database name for |
Returns
The name of the database to use
::getRecordName() 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 class
The default record name is the result of calling fGrammar::humanize() on the class.
Signature
string getRecordName( string $class )
Parameters
| string | $class | The class name to get the record name of |
Returns
The record name for the class specified
::getRecordSetMethod() 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 a matching callback for the method specified
The callback returned will be determined by the following logic:
1. If an exact callback has been defined for the method, it will be returned 2. If a callback in the form {action}* has been defined that matches the method, it will be returned 3. NULL will be returned
Signature
string|null getRecordSetMethod( string $method )
Parameters
| string | $method | The method to get the callback for |
Returns
The callback for the method or NULL if none exists - see method description for details
::mapClassToDatabase() public
Sets a class to use a database other than the "default"
Multiple database objects can be attached for the ORM by passing a unique $name to the attach() method.
Signature
void mapClassToDatabase( mixed $class, string $database_name )
Parameters
| mixed | $class | The name of the class, or an instance of it |
| string | $database_name | The name given to the database when passed to attach() |
::mapClassToTable() public
Allows non-standard class to table mapping
By default, all database tables are assumed to be plural nouns in underscore_notation and all class names are assumed to be singular nouns in UpperCamelCase. This method allows arbitrary class to table mapping.
Signature
void mapClassToTable( mixed $class, string $table )
Parameters
| mixed | $class | The name of the class, or an instance of it |
| string | $table | The name of the database table |
::objectify() 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
Takes a scalar value and turns it into an object if applicable
Signature
mixed objectify( mixed $class, string $column, mixed $value )
Parameters
| mixed | $class | The class name or instance of the class the column is part of |
| string | $column | The database column |
| mixed | $value | The value to possibly objectify |
Returns
The scalar or object version of the value, depending on the column type and column options
::overrideColumnName() public
Allows overriding of default column names
By default a column name is the result of fGrammar::humanize() called on the column.
Signature
void overrideColumnName( mixed $class, string $column, string $column_name )
Parameters
| mixed | $class | The class name or instance of the class the column is located in |
| string | $column | The database column |
| string | $column_name | The name for the column |
::overrideRecordName() public
Allows overriding of default record names
By default a record name is the result of fGrammar::humanize() called on the class.
Signature
void overrideRecordName( mixed $class, string $record_name )
Parameters
| mixed | $class | The class name or instance of the class to override the name of |
| string | $record_name | The human version of the record |
::parseMethod() 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 a camelCase method name for an action and subject in the form actionSubject()
Signature
array parseMethod( string $method )
Parameters
| string | $method | The method name to parse |
Returns
An array of 0 => {action}, 1 => {subject}
::registerActiveRecordMethod() public
Registers a callback for an fActiveRecord method that falls through to fActiveRecord::__call() or hits a predefined method hook
The callback should accept the following parameters:
- $object: The fActiveRecord instance
- &$values: The values array for the record
- &$old_values: The old values array for the record
- &$related_records: The related records array for the record
- &$cache: The cache array for the record
- $method_name: The method that was called
- &$parameters: The parameters passed to the method
Signature
void registerActiveRecordMethod( mixed $class, string $method, callback $callback )
Parameters
| mixed | $class | The class name or instance of the class to register for, '*' will register for all classes |
| string | $method | The method to hook for - this can be a complete method name or {prefix}* where * will match any column name |
| callback | $callback | The callback to execute - see method description for parameter list |
::registerHookCallback() public
Registers a callback for one of the various fActiveRecord hooks - multiple callbacks can be registered for each hook
The method signature should include the follow parameters:
- $object: The fActiveRecord instance
- &$values: The values array for the record
- &$old_values: The old values array for the record
- &$related_records: The related records array for the record
- &$cache: The cache array for the record
The 'pre::validate()' and 'post::validate()' hooks have an extra parameter:
- &$validation_messages: An ordered array of validation errors that will be returned or tossed as an fValidationException
Below is a list of all valid hooks:
- 'post::__construct()'
- 'pre::delete()'
- 'post-begin::delete()'
- 'pre-commit::delete()'
- 'post-commit::delete()'
- 'post-rollback::delete()'
- 'post::delete()'
- 'post::loadFromResult()'
- 'pre::populate()'
- 'post::populate()'
- 'pre::store()'
- 'post-begin::store()'
- 'post-validate::store()'
- 'pre-commit::store()'
- 'post-commit::store()'
- 'post-rollback::store()'
- 'post::store()'
- 'pre::validate()'
- 'post::validate()'
Signature
void registerHookCallback( mixed $class, string $hook, callback $callback )
Parameters
| mixed | $class | The class name or instance of the class to hook, '*' will hook all classes |
| string | $hook | The hook to register for |
| callback | $callback | The callback to register - see the method description for details about the method signature |
::registerInspectCallback() public
Registers a callback to modify the results of fActiveRecord::inspect() methods
Signature
void registerInspectCallback( mixed $class, string $column, callback $callback )
Parameters
| mixed | $class | The class name or instance of the class to register for |
| string | $column | The column to register for |
| callback | $callback | The callback to register. Callback should accept a single parameter by reference, an associative array of the various metadata about a column. |
::registerObjectifyCallback() public
Registers a callback for when objectify() is called on a specific column
Signature
void registerObjectifyCallback( mixed $class, string $column, callback $callback )
Parameters
| mixed | $class | The class name or instance of the class to register for |
| string | $column | The column to register for |
| callback | $callback | The callback to register. Callback should accept a single parameter, the value to objectify and should return the objectified value. |
::registerRecordSetMethod() public
Registers a callback for an fRecordSet method that fall through to fRecordSet::__call()
The callback should accept the following parameters:
- $object: The actual record set
- $class: The class of each record
- &$records: The ordered array of fActiveRecord objects
- &$pointer: The current array pointer for the records array
- $parameters: Any parameters passed to the method
Signature
void registerRecordSetMethod( string $method, callback $callback )
Parameters
| string | $method | The method to hook for |
| callback | $callback | The callback to execute - see method description for parameter list |
::registerReflectCallback() public
Registers a callback to modify the results of fActiveRecord::reflect()
Callbacks registered here can override default method signatures and add method signatures, however any methods that are defined in the actual class will override these signatures.
The callback should accept three parameters:
- $class: the class name
- &$signatures: an associative array of {method_name} => {signature}
- $include_doc_comments: a boolean indicating if the signature should include the doc comment for the method, or just the signature
Signature
void registerReflectCallback( mixed $class, callback $callback )
Parameters
| mixed | $class | The class name or instance of the class to register for, '*' will register for all classes |
| callback | $callback | The callback to register. Callback should accept a three parameters - see method description for details. |
::registerReplicateCallback() public
Registers a callback for when a value is replicated for a specific column
Signature
void registerReplicateCallback( mixed $class, string $column, callback $callback )
Parameters
| mixed | $class | The class name or instance of the class to register for |
| string | $column | The column to register for |
| callback | $callback | The callback to register. Callback should accept a single parameter, the value to replicate and should return the replicated value. |
::registerScalarizeCallback() public
Registers a callback for when scalarize() is called on a specific column
Signature
void registerScalarizeCallback( mixed $class, string $column, callback $callback )
Parameters
| mixed | $class | The class name or instance of the class to register for |
| string | $column | The column to register for |
| callback | $callback | The callback to register. Callback should accept a single parameter, the value to scalarize and should return the scalarized value. |
::replicate() 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
Takes and value and returns a copy is scalar or a clone if an object
The registerReplicateCallback() allows for custom replication code
Signature
mixed replicate( string $class, string $column, mixed $value )
Parameters
| string | $class | The class the column is part of |
| string | $column | The database column |
| mixed | $value | The value to copy/clone |
Returns
The copied/cloned value
::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( )
::scalarize() 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
If the value passed is an object, calls __toString() on it
Signature
mixed scalarize( mixed $class, string $column, mixed $value )
Parameters
| mixed | $class | The class name or instance of the class the column is part of |
| string | $column | The database column |
| mixed | $value | The value to get the scalar value of |
Returns
The scalar value of the value
::tablize() public
Takes a class name (or class) and turns it into a table name - Uses custom mapping if set
Signature
string tablize( mixed $class )
Parameters
| mixed | $class | he class name or instance of the class |
Returns
The table name
