macfja / php-kvo
The KVO (Key Value Observing) design pattern in PHP
Requires
- php: >=5.4.0
- eloquent/pops: ^4.1
- macfja/value-provider: ^0.3.0
Requires (Dev)
- phpmd/phpmd: ^2.3
- phpunit/phpunit: ^5.2
- sebastian/phpcpd: ^2.0
- squizlabs/php_codesniffer: ^2.5
This package is auto-updated.
Last update: 2024-10-17 01:14:49 UTC
README
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
API of Observable
interface
Implemented in AbstractObservable
, Proxy
.
A trait for quick implementation is available: ObservableTrait
API of Observable::addObserverForKey
method
This method allow you to subscribe to key value changes notification.
API, The Observable::addObserverForKey
options list.
-
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.
API of Observable::willChangeValueForKey
method
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.
API of Observable::didChangeValueForKey
method
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.
API of Observer::setValueForKey
method
This method change the value of a key and handle the call of methods Observable::willChangeValueForKey
and Observable::didChangeValueForKey
.
API, the Observable::willChangeValueForKey
and Observable::didChangeValueForKey
source value
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
API of Listener
interface
API of Listener::observeValueForKeyPath
method
This method is call every time an observed key is modified.
API, The Listener::observeValueForKeyPath
change array
-
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.