Docs For Class WFKeyValueCoding

Interface WFKeyValueCoding

Description

Key-Value Coding protocol.

The basic idea behind KVC is to be able to manipulate "properties" of all objects with the same interface. The key is the property name. A keyPath is a dot-separated string of key chains to call. Example: $book->setValueForKey('Charles Dickens', 'name'); Example: $bookList->setValueForKeyPath('Charles Dickens', 'selection.author.name');

This class provides the interface for the Key-Value Coding informal protocol.

The WFObject has a default impementation of this interface that should be good for pretty much all of your subclasses.

Key Value Naming Conventions:

Getters: <key>(), get<Key>()

Setters: set<Key>($value)

Validators: validate<Key>( params )

Instance Var Names: <key>

see: WFObject::valueForKey(), WFObject::valueForKeyPath(), WFObject::setValueForKey(), WFObject::setValueForKeyPath(), WFObject::validateValueForKey(), WFObject::validateValueForKeyPath()

Located in /framework/WFKeyValueCoding.php (line 43)

Method Summary

static mixed valueForStaticKey (string $key, string 1)

static mixed valueForStaticKeyPath (string $keyPath)

static mixed valueForUndefinedStaticKey (string $key)

void setValueForKey (mixed $value, string $key)

void setValueForKeyPath (mixed $value, string $keyPath)

void setValuesForKeys (array $valuesForKeys)

void validatedSetValueForKey ( &$value, $key, &$edited, &$errors)

void validatedSetValueForKeyPath ( &$value, $keyPath, &$edited, &$errors)

boolean validateObject (array &$errors)

boolean validateValueForKey (mixed &$value, string $key, boolean &$edited, array &$errors)

boolean validateValueForKeyPath (mixed &$value, string $keyPath, boolean &$edited, array &$errors)

mixed valueForKey (string $key)

mixed valueForKeyPath (string $keyPath)

mixed valueForUndefinedKey (string $key)

array valuesForKeyPaths (array $keys)

array valuesForKeys (array $keys)

Methods

static method valueForStaticKey (line 250)

Get the value of a static keypath. A static keypath is a key called against a CLASS rather than an instance.

return: The value of the key.
throws: object WFUndefinedKeyException

static mixed valueForStaticKey (string $key, string 1)

string 1: The class name to which the key belongs
string $key: The key (method/property name). Key must be in form "ClassName::MethodName".

static method valueForStaticKeyPath (line 262)

This function is a wrapper of valueForKeyPath that allows you to use KVC to access static methods/properties without having an instance to a class.

MyObject::valueForStaticKeyPath('MyObject::myStaticMethod')

return: The value for the given keyPath.
see: WFKeyValueCoding::valueForKey()
throws: object WFUndefinedKeyException

static mixed valueForStaticKeyPath (string $keyPath)

string $keyPath: The keyPath to retrive the value for.

static method valueForUndefinedStaticKey (line 240)

Called by valueForStaticKey() if the key cannot be located through normal methods.

The default implementation raises as WFUndefinedKeyException. Subclasses can override this function to return an alternate value for the undefined key.

NOTE: subclass overrides probably won't work so well until PHP 5.3.

return: The value of the key.
throws: object WFUndefinedKeyException

static mixed valueForUndefinedStaticKey (string $key)

string $key: The key.

setValueForKey (line 63)

Set the value for the given key.

First tries to use a setter method (set<key>) then attempts access on class member.

void setValueForKey (mixed $value, string $key)

mixed $value: The value to set.
string $key: The key to set the value for.

setValueForKeyPath (line 138)

Set the value for the given keyPath.

see: WFKeyValueCoding::setValueForKey()

void setValueForKeyPath (mixed $value, string $keyPath)

mixed $value: The value to set.
string $keyPath: The keyPath to set the value for.

setValuesForKeys (line 120)

Set values for multiple keys.

throws: object WFUndefinedKeyException

void setValuesForKeys (array $valuesForKeys)

array $valuesForKeys: An array of key => value

validatedSetValueForKey (line 189)

Validate the value, calling the setter if the value is valid.

see: WFKeyValueCoding::validateValueForKey()

void validatedSetValueForKey ( &$value, $key, &$edited, &$errors)

&$value
$key
&$edited
&$errors

validatedSetValueForKeyPath (line 196)

Validate the value, calling the setter if the value is valid.

see: WFKeyValueCoding::validateValueForKeyPath()

void validatedSetValueForKeyPath ( &$value, $keyPath, &$edited, &$errors)

&$value
$keyPath
&$edited
&$errors

validateObject (line 217)

Run the object-level validation code.

An object-level validator is used for interproperty validation, for instance validating 'postalCode' depends on 'country'.

The default implementation will call all defined Key-Value Validators (any method matching "^validate*").

Validations are done via validatedSetValueForKey(), meaning that changes made to values by the validators will be updated via setValueForKey.

Subclasses needing to do interproperty validation should override the validateObject() method. If subclasses wish to block the default behavior of re-validating all properties with validators, then the subclass should not call the super method. Subclasses wishing to preserve this behavior should call parent::validateObject($errors).

NOTE: It's called validateObject right now instead of validate primarily because Propel already has a validate() method.

return: TRUE if valid; FALSE if not.
throws: object WFExecption

boolean validateObject (array &$errors)

array &$errors: An array, passed by reference, which will be populated with any errors encountered. Errors are grouped by key, ie $errors['key'] = array()

validateValueForKey (line 182)

Validate the given value for the given key.

Clients can normalize the value, and also report and error if the value is not valid.

If the value is valid without modificiation, return TRUE and do not alter $edited or $error. If the value is valid after being modified, return TRUE, and $edited to true. IF the value is not valid, do not alter $value or $edited, but fill out the $error object with desired information.

The default implementation (in WFObject) looks for a method named validate<key> and calls it, otherwise it returns TRUE.

Classes that wish to provide validators for keys should implement one validator per key, with the following prototype:

// parameters are the same as for the validateValueForKey function, minus the key name.
// function should return TRUE if valid, FALSE if not valid.
validate<KeyName>(&$value, &$edited, &$errors);
// clients wishing to add errors do so with:
$errors[] = new WFError('My error message'); // could also add an error code (string) parameter.

return: TRUE indicates a valid value, FALSE indicates an error.

boolean validateValueForKey (mixed &$value, string $key, boolean &$edited, array &$errors)

mixed &$value: A reference to value to check. Passed by reference so that the implementation can normalize the data.
string $key: The key for the value to validate.
boolean &$edited: A reference to a boolean. This value will always be FALSE when the method is called. If the implementation edits the $value, set to TRUE.
array &$errors: An array of WFError objects describing the error. The array is empty by default; you can add new error entries.

validateValueForKeyPath (line 152)

Validate the given value for the given keypath.

The default implementation (in WFObject) finds the target object based on the keypath and then calls the validateValueForKey method.

return: TRUE indicates a valid value, FALSE indicates an error.
see: WFKeyValueCoding::validateValueForKey()

boolean validateValueForKeyPath (mixed &$value, string $keyPath, boolean &$edited, array &$errors)

mixed &$value: A reference to value to check. Passed by reference so that the implementation can normalize the data.
string $keyPath: keyPath the keyPath for the value.
boolean &$edited: A reference to a boolean. This value will always be FALSE when the method is called. If the implementation edits the $value, set to TRUE.
array &$errors: An array of WFError objects describing the error.

valueForKey (line 53)

Get the value for the given key.

First tries to use a getter method (get<key>) then attempts access on class member.

return: The value for the given key.

mixed valueForKey (string $key)

string $key: The key to retrive the value for.

valueForKeyPath (line 103)

Get the value for the given key path.

valueForKeypath's default implementation is in WFObject.

The default implementation does some very special things...

Magic Arrays
Magic arrays are a way of returning an array of values calculated from an array of objects. For instance, let's say you have an array of Person objects, for instance in an addressBook application, and that each person has a unique ID. Now, you want an array containing the ID of every person, but you don't want to have to write a foreach loop to do it. You could use valueForKeypath's magic instead:
1. $arrayOfPersonIDs = $addressBook->valueForKeyPath("people.id")
And afterwards, arrayOfPersonIDs will have an array containing the ID for each person in the address book, in the same order that the Person objects appear in the array.
Array Operators, based on: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/Concepts/ArrayOperators.html

In a given keyPath, you can include an operator to perform a calculation on the keyPath to that point, provided that the result is an array: "transactions.@sum.amount"
Operators are preceeded by @:
count - Count of items specified by remainder of keypath.
first - Return the first item in the array, or NULL
sum - Sum of items specified by remainder of keypath.
max - Maximum value of items specified by remainder of keypath.
min - Minimum value of items specified by remainder of keypath.
avg - Average of items specified by remainder of keypath.
unionOfArrays - Union of all objects in the arrays specified by remainder of keypath.
unionOfObjects - Union of all items specified by remainder of keypath. Identical to normal magic, ie: books.author == books.@unionOfObjects.author
distinctUnionOfArrays - same as @unionOfArrays but with duplicate objects removed. Duplicates determined by PHP === operator.
distinctUnionOfObjects - same as @unionOfObjects but with duplicate objects removed. Duplicates determined by PHP === operator.

3. Static Method/Property access
If the first part of the keypath contains '::', then "static" mode will be enabled, which allows you to use KVC on an instance of an object to access static methods. Note that at present all static access must be done with valueForStaticKeyPath(). This may become more flexible in the future.

return: The value for the given keyPath.
see: WFKeyValueCoding::valueForKey()

mixed valueForKeyPath (string $keyPath)

string $keyPath: The keyPath to retrive the value for.

valueForUndefinedKey (line 227)

Called by valueForKey() if the key cannot be located through normal methods.

The default implementation raises as WFUndefinedKeyException. Subclasses can override this function to return an alternate value for the undefined key.

return: The value of the key.
throws: object WFUndefinedKeyException

mixed valueForUndefinedKey (string $key)

string $key: The key.

valuesForKeyPaths (line 129)

Creates an associative array with the set of passed keys and keyPaths and the corresponding values.

return: An associative array of the passed in keys, now with values from valueForKeyPath($theKeyPath).
throws: object WFUndefinedKeyException

array valuesForKeyPaths (array $keys)

array $keys: An array of key => keyPath. If a "key" is encountered without a value, uses the "key" as the "keyPath".

valuesForKeys (line 112)

Creates an associative array with the set of passed keys and the corresponding values

return: An associative array of the passed in keys, now with values from valueForKey($theKey).
throws: object WFUndefinedKeyException

array valuesForKeys (array $keys)

array $keys: An array of keys.

Documentation generated on Thu, 14 May 2009 16:20:08 -0400 by phpDocumentor 1.4.2