Docs For Class 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

void setValueForKey (mixed $value, string $key)

void setValueForKeyPath (mixed $value, string $keyPath)

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)

Methods

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 106)

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.

validateValueForKey (line 150)

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 120)

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 97)

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

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

mixed valueForKeyPath (string $keyPath)

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

Interface WFKeyValueCoding