observable

implementation of SplObserver + SplSubject with support for named events.

one, other, both

Depending on which interfaces are declared, unneeded methods will do nothing. For example:

• In a class which implements SplObserver, the update method will work normally, but attach, detach, and notify will do nothing at all.
• In a class which implements SplSubject, attach, detach, and notify will work, but update will do nothing.
• A class which implements SplObserver, SplSubject will have use for all methods.

events and event groups

observable supports subscriptions/notifications on named events. Event names are dot-delimited strings; a trailing dot will also match all sub-names. The default event is "all" —meaning "every|any event" (this is analagous to the "normal" usage that the SPL interfaces intended). Observe (no pun intended):

<?php
  # this code...                                 # subscribes observer to...
  #----------------------------------------------#-------------------------------------------
  $subject->attach( $observer1,"hello.world" );  # "hello.world"
  $subject->attach( $observer2,"hello.mom" );    # "hello.mom"
  $subject->attach( $observer3,"hello." );       # "hello" _and_ all sub-events
  $subject->attach( $observer4,"hello" );        # "hello"
  $subject->attach( $observer5 );                # _all_ events ("normal" SPL usage)

  # this code...                                 # triggers update() on...
  #----------------------------------------------#-------------------------------------------
  $subject->notify( "hello" );                   # $observer3, $observer4, $observer5
  $subject->notify( "hello.world" )              # $observer1, $observer3, $observer5
  $subject->notify( "hello.world.again" )        # $observer5
  $subject->notify();                            # _all_ observers ("normal" SPL usage)

mini-docs

for SplObserver:

• update()
  void update( \SplSubject $subject )
  see the SPL documentation.

  configurable uses update as an update dispatcher. The implementing class should define a "handler" method for each event it needs to support, and must also define a "catch-all" method for other event notifications. The naming convention/signature for handlers are as follows:
  void _update_{name of event}( \SplSubject $subject, $event )
void _update_all( \SplSubject $subject, $event )
  …where {name of event} is the full event name, with dot replaced with underscores.

for SplSubject:

• attach()
  void attach( \SplObserver $observer [, $event] )
  In addition to the SPL documentation, allows observers to subscribe to specific events or event groups.

  param $event
  The event (group) to subscribe to. If omitted, the observer will recieve notifications on _all_ events. Event names are arbitrary, dot-delimited PHP labels (i.e., /^[a-z][\w]*$/i). Event names may be organized as hierarchichal groups; a trailing dot will match all sub-named events. The special event name "all" will match _all_ events.

• detach
  void detach( \SplObserver $observer [, $event] )
  In addition to the SPL documentation, allows un-subscribing from specific events or event groups. If all of an observer's events are detached, the observer will be detached as well.

  param $event
  See the description for $event (above).

• notify
  void notify( [$event] )
  In addition to the SPL documentation, allows sending notifications for specific events.

  param $event
  See the description for $event (above).