* @changes 1.0.0b24 Backwards Compatibility Break - Callbacks registered via ::registerRecordSetMethod() should now accept the `$method_name` in the position where the `$pointer` parameter used to be passed [wb, 2010-09-28]

* 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 - see the [http://flourishlib.com/docs/fORM#values $values] documentation for details

* - **`&$old_values`**: The old values array for the record - see the [http://flourishlib.com/docs/fORM#old_values $old_values] documentation for details

* - **`&$related_records`**: The related records array for the record - see the [http://flourishlib.com/docs/fORM#related_records $related_records] documentation for details

* - **`&$cache`**: The cache array for the record - see the [http://flourishlib.com/docs/fORM#cache $cache] documentation for details

*

* 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 - see the [http://flourishlib.com/docs/fORM#validation_messages $validation_messages] documentation for details

*

* The `'pre::replicate()'`, `'post::replicate()'` and

* `'cloned::replicate()'` hooks have an extra parameter:

*

* - **`$replication_level`**: An integer representing the level of recursion - the object being replicated will be `0`, children will be `1`, grandchildren `2` and so on.

*

* 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::loadFromIdentityMap()'`

* - `'post::loadFromResult()'`

* - `'pre::populate()'`

* - `'post::populate()'`

* - `'pre::replicate()'`

* - `'post::replicate()'`

* - `'cloned::replicate()'`

* - `'pre::store()'`

* - `'post-begin::store()'`

* - `'post-validate::store()'`

* - `'pre-commit::store()'`

* - `'post-commit::store()'`

* - `'post-rollback::store()'`

* - `'post::store()'`

* - `'pre::validate()'`

* - `'post::validate()'`

*

* @param mixed $class The class name or instance of the class to hook, `'*'` will hook all classes

* @param string $hook The hook to register for

* @param callback $callback The callback to register - see the method description for details about the method signature

* @return void

*/

staticpublicfunctionregisterHookCallback($class, $hook, $callback)

{

$class=self::getClass($class);

static$valid_hooks=array(

'post::__construct()',

'pre::delete()',

'post-begin::delete()',

'pre-commit::delete()',

'post-commit::delete()',

'post-rollback::delete()',

'post::delete()',

'post::loadFromIdentityMap()',

'post::loadFromResult()',

'pre::populate()',

'post::populate()',

'pre::replicate()',

'post::replicate()',

'cloned::replicate()',

'pre::store()',

'post-begin::store()',

'post-validate::store()',

'pre-commit::store()',

'post-commit::store()',

'post-rollback::store()',

'post::store()',

'pre::validate()',

'post::validate()'

);

if (!in_array($hook, $valid_hooks)) {

thrownewfProgrammerException(

'The hook specified, %1$s, should be one of: %2$s.',

$hook,

join(', ', $valid_hooks)

);

}

if (!isset(self::$hook_callbacks[$class])) {

self::$hook_callbacks[$class] =array();

}

if (!isset(self::$hook_callbacks[$class][$hook])) {

self::$hook_callbacks[$class][$hook] =array();

}

if (is_string($callback) &&strpos($callback, '::') !==FALSE) {

$callback=explode('::', $callback);

}

self::$hook_callbacks[$class][$hook][] =$callback;

}

/**

* Registers a callback to modify the results of fActiveRecord::inspect() methods

*

* @param mixed $class The class name or instance of the class to register for

* @param string $column The column to register for

* @param callback $callback The callback to register. Callback should accept a single parameter by reference, an associative array of the various metadata about a column.