PhpKVO
What is KVO Installation Usage API
What is KVO ?
KVO (Key Value Observing) is a design pattern which allows an object to get notified about changes.
It allow you keep your object synchronized each other without creating a hard link thanks to Subject/Observer design pattern.
KVC (Key Value Coding) and KVO (Key Value Observing) are heavily used in Cocoa Framework (Objective-C)
Installation
The simplest way to install the library is to use Composer:
composer require macfja/php-kvo
Usage
class Downloader extends AbstractObservable
{
protected $progress;
public function getProgress()
{
return $this->progress;
}
protected function receiveCallback($newProgress)
{
$this->setValueForKey('progress', $newProgress);
// ... do something with the data
}
public function download()
{
// ... start the download
}
}
class ProgressDisplay implements Listener
{
public function observeValueForKeyPath($keyPath, $object, $change, &$context)
{
if ($keyPath == 'progress') {
echo sprintf('Download in progress (%d%%)%s', $change[Observer::CHANGE_NEW], PHP_EOL);
}
}
}
$downloader = new Downloader();
$progress = new ProgressDisplay();
$downloader->addObserverForKey($progress, 'progress', Observer::OPTION_NEW|Observer::OPTION_INITIAL);
$downloader->download()
A complete examples can be found in the directory examples.
API
Observable
interface
API of Implemented in AbstractObservable
, Proxy
.
A trait for quick implementation is available: ObservableTrait
Observable::addObserverForKey
method
API of This method allow you to subscribe to key value changes notification.
Type | Variable | Description |
---|---|---|
Listener |
$listener |
The object that subscribe to the changes notification. |
string | $key |
The key to listen. |
int|0 |
$options optional |
The list of options. (More information below) |
mixed|null |
&$context optional |
The context: data to send with the notification. This value passed by reference. |
Observable::addObserverForKey
options list.
API, The -
Observer::OPTION_NEW
, Indicates that the change array should provide the new attribute value, if applicable. -
Observer::OPTION_OLD
, Indicates that the change array should contain the old attribute value, if applicable. -
Observer::OPTION_INITIAL
, If specified, a notification should be sent to the observer immediately, before the observer registration method even returns.The change array in the notification will always contain an
Observer::CHANGE_NEW
entry ifObserver::OPTION_NEW
is also specified but will never contain anObserver::CHANGE_OLD
orObserver::CHANGE_REQUESTED
entry.
(In an initial notification the current value of the observed property may be old, but it's new to the observer.) -
Observer::OPTION_PRIOR
, Whether separate notifications should be sent to the observer before and after each change, instead of a single notification after the change.The change array in a notification sent before a change always contains an
Observer::CHANGE_PRIOR
entry whose value istrue
, but never contains anObserver::CHANGE_NEW
entry. When this option is specified the change array in a notification sent after a change contains the same entries that it would contain if this option were not specified. You can use this option when the observer's own key-value observing-compliance requires it to invoke thewillChangeValueForKey
method for one of its own properties, and the value of that property depends on the value of the observed object's property.
Observable::willChangeValueForKey
method
API of This method trigger a notification for all Listener
that registered for a key with the option Observer::OPTION_PRIOR
.
This method should be call before the key value change.
Type | Variable | Description |
---|---|---|
string | $key |
The key that is changed. |
string | $source |
The source/type of change. (More information below). |
null|mixed | $oldValue optional |
The current value of the key. |
null|mixed | $requestedValue optional |
The requested new value of the key. |
Observable::didChangeValueForKey
method
API of This method trigger a notification for all Listener
that registered for a key without the option Observer::OPTION_PRIOR
.
This method should be call after the key value change.
Type | Variable | Description |
---|---|---|
string | $key |
The key that is changed. |
string | $source |
The source/type of change. (More information below). |
mixed|null |
$oldValue optional |
The value of the key before the change. |
mixed|null |
$requestedValue optional |
The requested new value of the key. |
mixed|null |
$newValue optional |
The current value of the key. |
Observer::setValueForKey
method
API of This method change the value of a key and handle the call of methods Observable::willChangeValueForKey
and Observable::didChangeValueForKey
.
Type | Variable | Description |
---|---|---|
string | $key |
The key to change. |
mixed | $value |
The new value. |
Observable::willChangeValueForKey
and Observable::didChangeValueForKey
source value
API, the Observer::SOURCE_SETTER
, If the value of the key was changed from a setter method. (Used byProxy
class)Observer::SOURCE_PROPERTY
, If the value of the key was changed from a direct property change (public class property). (Used byProxy
class)Observer::SOURCE_CUSTOM
, If the value was change without a setter, or from a direct property access.
Note: You can use your own source type, it's just a string.
Note: Observer::SOURCE_INITIAL
, If the Listener
has the option Observer::OPTION_INITIAL
, then when registered, this source is used
Listener
interface
API of Listener::observeValueForKeyPath
method
API of This method is call every time an observed key is modified.
Type | Variable | Description |
---|---|---|
string | $keyPath |
The modified key. |
object | $key |
The modified object. |
array | $change |
The changed data. (More information below) |
mixed | &$context |
The changed context (provided on subscription). |
Listener::observeValueForKeyPath
change array
API, The -
Observer::CHANGE_NEW
, If theObserver::OPTION_NEW
was specified when the observer was registered, the value of this key is the new value for the attribute. -
Observer::CHANGE_OLD
, If theObserver::OPTION_OLD
was specified when the observer was registered, the value of this key is the value before the attribute was changed. -
Observer::CHANGE_PRIOR
, If the optionObserver::OPTION_PRIOR
was specified when the observer was registered this notification is sent prior to a change.The change array contains an
Observer::CHANGE_PRIOR
entry whose value istrue
if the nofication is before the change, orfalse
if the notification is after.