frando/fapi4/classes.inc

<?php
/**
 * BUGGY CONCEPT CODE!
 * 
 * This is code for a object oriented Forms and Rendering API in Drupal 7.
 */
 
/**
 * Register a callback for a $signal emitted by $class.
 *
 * @param $class The class to which you want to listen
 * @param $signal The signal (event) to which you want to react
 * @param $callback 
 *    The callback that is invoked when $signal is emitted. 
 *    Either a string containing the name of a function, an array of an object
 *    and a method name or an array of a class name and a method name
 */
function connect($class, $signal, $callback) {
  static $connections;
  
  // Return the stored connections. Only needed for the get_connections function
  if (is_null($class) && is_null($signal) && is_null($callback)) {
    return $connections;
  }
  
  if (is_string($class)) {
    $connections[$class][$signal][] = $callback;
  }
  elseif (is_object($class) && $class instanceof DrupalObject) {
    $class->addCallback($signal, $callback);
  }
}

/**
 * Get an array of registered connections for a class/signal combination.
 */
function get_connections($class, $signal = NULL) {
  $connections = connect(NULL, NULL, NULL);
  if (is_null($signal)) {
    return isset($connections[$class]) ? $connections[$class] : array();
  }
  else {
    return isset($connections[$class][$signal]) ? $connections[$class][$signal] : array();
  }
}

class Form {
  /**
   * Load a form.
   *
   * This first checks whether there is POST data for the given form.
   * If so, we load the built form from the cache.
   *
   * Otherwise, we check whether we have a cached, readily constructed skeleton cache
   * for the form. If not, we create a new one. 
   * Then, the 'build' signal is emitted both for cached skeletons and newly created objects, so
   * all dynamic actions should happen there instead of in __construct.
   *
   * @param $form_id
   *   The name of the form (class) to load.
   *
   * Additional arguments will be passed on to the build callback/method.
   */
  static function load() {
    $args = func_get_args();
    $form_id = array_shift($args);
    
    if (isset($_POST["$form_id/form_id"]) && $_POST["$form_id/form_id"] == $form_id
        && !empty($_POST["$form_id/form_build_id"])) {
      $cached = cache_get('form_build:'. $_POST["$form_id/form_build_id"]);
      $form = $cached->data;
      call_user_func_array(array($form, 'build'), $args);
      print 'build cached<br>';
    }

// UNCOMMENT THE FOLLOWING LINES TO ENABLE THE SKELETON CACHE!
// It works, but is disabled right now.

/*  elseif ($cached = cache_get("form_skeleton:$form_id")) {
      $form = $cached->data;
      call_user_func_array(array($form, 'build'), $args);
      print 'skeleton cached<br>';
    }
*/

    else {
      $form = new $form_id();
      cache_set("form_skeleton:$form_id", $form);
      call_user_func_array(array($form, 'build'), $args);
      print 'not cached<br>';
    }
    return $form;
  }
}

/**
 * The class DrupalObject provides functionality that is widely known as
 * the 'Observer' pattern or 'Signals and Slots'.
 *
 * Here, this is basically a simple callback mechanism that allows objects to talk
 * with each other.
 *
 * Objects can invoke callbacks whenever they want and without caring whether there are
 * actual callbacks registered for a certain signal. 
 *
 * Callbacks can be registered either by calling the addCallback method of an object, or
 * by using the connect() function, which allows to register callbacks for not yet instanced
 * classes.
 *
 * @author Franz Heinzmann (Frando), http://unbiskant.org
 * @see
 *      http://www.php.net/~helly/php/ext/spl/
 *      http://www.angrydonuts.com/what_if_fapi_were_oo
 */
abstract class DrupalObject {
  private $_callbacks = array();
  
  /**
   * Constructor
   */
  public function __construct() {
    
    // Add all callbacks that are defined for the object.
    foreach (get_connections(get_class($this)) as $signal => $callbacks) {
      foreach ($callbacks as $callback) {
        $this->addCallback($signal, $callback);
      }
    }
    
    return $this;
  }
  
  /**
   * Callback stuff
   */
   
  /**
   * Add a callback for a given signal.
   *
   * The callback can be anything callable (either a string containing the
   * name of a function, an array of an object and a method name or an array
   * of a class name and a method name).
   *
   * It will be called when $signal is emitted.
   */
  public function addCallback($signal, $callback) {
    $this->_callbacks[$signal][] = $callback;
  }
  
  public function removeCallback($signal, $callback = NULL) {
    if (is_null($callback)) {
      unset($this->_callbacks[$signal]);
    }
    else {
      foreach ($this->_callbacks[$signal] as $key => $current_slot) {
        if ($current_slot === $callback) {
          unset($this->_callbacks[$signal][$key]);
        }
      }
    }
  }
  
  /**
   * Invoke all callbacks that are defined for a given signal.
   *
   * @param $signal
   *   The name of the signal to emit (= the name of the callback to invoke)
   *
   * This first calls the method $signal in $this (if it exists). Then,
   * each additional callback that is registered for $signal is called.
   *  
   * Additional parameters will be passed on to the callbacks.
   *
   * Internal callback will just get the passed arguments as arguments.
   * External callbacks receive the object ($this) as the first argument, the name
   * of the signal as second argument and then the passed additional arguments.
   */
  public function invoke() {
    $func_args = func_get_args();
    $signal = array_shift($func_args);

    // Check if the methods is defined in the current object.
    if (method_exists($this, $signal)) {
      call_user_func_array(array($this, $signal), $func_args);
    }
    
    // Check if additional (external) callbacks are registered
    if (isset($this->_callbacks[$signal])) {
      $args = array(&$this, $signal);
      foreach ($func_args as $arg) {
        $args[] = $arg;
      }
      foreach ($this->_callbacks[$signal] as $callback) {
        if (is_callable($callback)) {
          call_user_func_array($callback, $args);
        }
      }
    }
  }
}

function q($object) {
  return new DrupalIterator($object);
}

/**
 * DrupalElement is a class to represent an element in a tree.
 *
 * A DrupalElement basically differentiates between children and properties.
 *
 * Children can be set and accessed with the -> syntax (i.e. by using the normal PHP 
 * object property syntax):
 * if it would be a regular PHP Array.
 * @code
 *    $object=>some_child = new ...; // Any class that is derived from DrupalElement
 * @endcode
 *
 * Properties can be set and accessed with the [] syntax (i.e. by treating a DrupalElement
 * object as if it would be a regular PHP Array).
 * @code
 *   $object['some_property'] = 'baz';
 * @endcode
 *
 * All children of a DrupalElement have to be an instance of a class that is based on 
 * DrupalElement, otherwise, an exception is raised.
 *
 * Internally, this behaviour is realized by implementing ArrayAccess,
 * an interface that is provided by the SPL and that allows to override the PHP array
 * access syntax for an object.
 *
 * The foreach language construct is also overloaded. Instead of iterating over all
 * public properties (default PHP behaviour when using an object with foreach), we
 * can customize over what we want to iterate. This is realized by implementing
 * the Iterator interface provided by the SPL.
 *
 * So, by default, foreach($object as $child_name => $child) iterates over all children
 * of $object. Note that in PHP5, objects are always passed by reference, so 
 * $object[$child_name]->foo = 'bar' is equal to $child->foo = 'bar'.
 *
 * Now, DrupalElement provides several methods that allow to manipulate over which
 * elements foreach iterates. 
 *
 * All of these methods (and even some more) return $this, which makes them chainable.
 * And yeah, this is similar to the jQuery way of doing things (jQuery was in fact a main
 * inspiration for this whole iteration/traversable thing).
 *
 * @author Franz Heinzmann (Frando), http://unbiskant.org
 * @see
 *      http://www.php.net/~helly/php/ext/spl/
 *      http://www.angrydonuts.com/what_if_fapi_were_oo
 */
abstract class DrupalElement extends DrupalObject implements ArrayAccess, Countable, IteratorAggregate {
  
  // Contains all properties. 
  protected $_properties = array();
  // Contains all children. 
  public $_children = array();
  
  // Contains all descendants (children and grandchildren and grandgrandchildren etc.)
  public $_descendants = array();
  
  
  /**
   * Constructor
   */
  public function __construct($properties = array()) {
    parent::__construct();
    $this->set($properties);

    $this['type']     = get_class($this);
    $this['name']     = isset($this['name']) ? $this['name'] : $this['type'];
    // By default, we're the only element, and thus the tree's root.
    $this['treeRoot'] = $this;
  // TODO  $this['built']    = FALSE;

    // Reset the selection.
//    $this->resetSelection();

    // Invoke 'construct'
    $this->invoke('construct');
    return $this;
  }
  
  /**
   * Implement ArrayAccess to be able to access the object with PHP's normal Array syntax,
   * which is used to access the element's properties.
   */
  public function offsetSet($name, $value) {
    $this->_properties[$name] = $value;
  }
  
  public function offsetGet($name) {
    return $this->_properties[$name];
  }
  
  public function offsetExists($name) {
    return isset($this->_properties[$name]);
  }

  public function offsetUnset($name) {
    unset($this->_properties[$name]);
  }

  /**
   * Magic methods to be able to access children with the -> syntax.
   * $object->foo = new bar() is equal to $object->addChild('foo', new bar())
   */
  public function __set($name, $value) {
    $this->addChild($name, $value);
  }
  
  public function __get($name) {
    return $this->_children[$name];
  }
  
  public function __isset($name) {
    return isset($this->_children[$name]);
  }
  
  public function __unset($name) {
    unset($this->_children[$name]);
  }
  
  /**
   * Implement Countable
   */
  public function count() {
    return count($this->_children);
  }
  
  /**
   * Implement IteratorAggregate
   */
  public function getIterator() {
    return new DrupalIterator($this);
  }
  
  /**
   * Children management
   */
  
  /**
   * Add a child to the current element.
   * All children must be an instance of a class that is based on DrupalElement,
   * otherwise, an Exception is thrown.
   * 
   * $object->addChild('foo', new bar()) is equal to $object['foo'] = new bar()
   */
  public function addChild($name, $child) {
    if (!$child instanceof DrupalElement) {
      throw new Exception('DrupalElement::addChild(): Argument #2 is not a DrupalElement');
    }
    // Add the element to the current element's children (remind that objects are always copied by reference)    
    $this->_children[$name] = $child;
    
    // Set basic properties for the child
    $child->set(array(
      'name' => $name,
      'inTree' => TRUE,
      'treeParent' => $this,
      'treeRoot' => $this['treeRoot'],
    ));

    // Add the element to the current element and its parents as a descendant
    $this->addDescendantRecursive($child);
    
    // Reset the current selection.
//    $this->resetSelection();
//    $child->resetSelection();
    
    // Emit the 'childAdded' signal of the current element and pass the child as argument
    $this->invoke('childAdded', $child);
    // Emit the 'addedAsChild' signal of the child
    $child->invoke('addedAsChild');
    
    // Return the child to make addChild chainable
    return $child;
  }
  
  protected function addDescendantRecursive($descendant) {
    $this->_descendants[] = $descendant;
    $this->invoke('descendantAdded', $descendant);
    if (!$this->isTreeRoot()) {
      $this->parent()->addDescendantRecursive($descendant);
    }
  }
  
  /**
   * Return the element's parent.
   */
  public function parent() {
    return $this['treeParent'];
  }
  
  /**
   * Return the root element of the tree in which the element is.
   */
  public function root() {
    return $this['treeRoot'];
  }
  
  /**
   * This adds $this plus it's parent plus it's parent's parent etc. to $selection, which is passed
   * from element to parent to parent recursively.
   */
  public function addParent(&$selection) {
    $selection[] = $this;
    if (!$this->isTreeRoot()) {
      $this->parent()->addParent($selection);
    }
  }
 
  /**
   * This creates a 'path' from $start to $stop.
   * With no args, it creates a path from the treeRoot to the current element,
   * seperated by '/'.
   *
   * This, together with findByPath, is used to create the POST 'name's for form elements
   * and then to assign the POST values to the correct elements.
   */
  public function createPath($start = NULL, $stop = NULL) {
    if (is_null($start)) {
      $start = $this['treeRoot'];
    }
    if (is_null($stop)) {
      $stop = $this;
    }
    $parents = array();
    foreach (q($stop)->parents() as $parent) {
      $parents[] = $parent['name'];
      if ($parent === $start) {
        break;
      }
    }
    $parents = array_reverse($parents);
    return implode('/', $parents) . '/' . $stop['name'];
  }
  
  /**
   * This returns the element that has the path $path from the current element.
   */
  public function findByPath($path) {
    $path = explode('/', $path);
    // TODO: this is ugly.
    if ($this['name'] == $path[0]) {
      array_shift($path);
    }
    return $this->findRecursively($path);
  }
  
  public function findRecursively($parts) {
    $name = array_shift($parts);
    if (!isset($this->$name)) {
      return FALSE;
    }
    if (count($parts)) {
      return $this->$name->findRecursively($parts);
    }
    else {
      return $this->$name;
    }
  }
  
  /**
   * Mixed functions
   */
  public function isTreeRoot() {
    return ($this['treeRoot'] === $this);
  }
  public function hasChildren() {
    return !empty($this->_children);
  }
  public function __toString() {
    return $this['type'] .' '. $this['name'];
  }
  
  /**
   * Pass in an array of key/value pairs to be set as object properties.
   */
  public function set($name, $value = NULL) {
    if (!is_array($name)) {
      $this[$name] = isset($value) ? $value : TRUE;
    }
    else {
      foreach ($name as $name => $value) {
        $this[$name] = $value;
      }
    }
    return $this;
  }
  
  public function get($name = NULL) {
    if (!isset($name)) {
      return $this->_properties;
    }
    else {
      return $this->_properties[$name];
    }
  }

}

class DrupalIterator implements Iterator, Countable {
  // Contains the current 'selection' of element over which foreach iterates
  public $selection = array();
  
  // Needed for the Iterator implentation.
  private $selectionValid;
    
  function __construct($object) {
    $this->selection = array($object);
    return $this;
  }
  
  public function __call($method, $args) {
    foreach ($this->selection as $item) {
      if (method_exists($item, $method)) {
        call_user_func_array(array($item, $method), $args);
      }
    }
    return $this;
  }
    /**
   * Implement Iterator to overload the foreach language construct.
   * 
   * When an instance of DrupalElement is used in a foreach loop, it iterates
   * over the internal, protected $selection property. By default, $selection contains
   * all children of the object. See the Traversing methods on how to manipulate $selection.
   */
    
  /* (The following is just the standard implentation of the Iterator interface) */
  /**
   * Return the array "pointer" to the first element
   * PHP's reset() returns false if the array has no elements
   */
  function rewind() {
    if (reset($this->selection) !== FALSE) {
      $this->selectionValid = TRUE;
    }
    else {
      $this->selectionValid = FALSE;
    }
    
  }
 
  /**
   * Return the current array element
   */
  function current() {
    return current($this->selection);
  }

   /**
   * Return the key of the current array element
   */
  function key() {
    return key($this->selection);
  }

   /**
   * Move forward by one
   * PHP's next() returns false if there are no more elements
   */
  function next() {
    if (next($this->selection) !== FALSE) {
      $this->selectionValid = TRUE;
    }
    else {
      $this->selectionValid = FALSE;
      // Reset the selection at the end of a foreach loop.
   //   $this->resetSelection();
    }
  }

   /**
   * Is the current element valid?
   */
  function valid(){
    return $this->selectionValid;
  } 
  
  /**
   * Implement Countable
   */
  public function count() {
    return count($this->selection);
  }
  
  /**
   * Traversing
   * 
   * Each of these functions sets the internal, private $selection property to some array
   * of children/parents/etc. 
   * The foreach language construct is overloaded and when used 
   * with a DrupalElement object, it iterates over the elements in $selection.
   *
   * As $this is returned, these functions are chainable (jQuery style).
   */
 
  public function selection() {
    return $this->selection;
  }
  
  public function add($element) {
    $this->selection[] = $element;
    return $this;
  }
  
  public function end() {
    return  $this->resetSelection();
  }
  
  public function resetSelection() {
    $this->selection = array($this);
    return $this;
  }
  
  /**
   * Select all children.
   */
  public function children($filter = NULL) {
    // TODO! This is just that everything basically works, but children() has to be chainable too
   // $this->selection = array_values($this->_children);
   // return $this;
    // TODO! We need to 'close' the selection if we want this to be chainable.
    $selection = array();
    foreach ($this->selection as $element) {
      $selection = array_merge($selection, array_values($element->_children));
    }
    array_unique($selection);
    $this->selection = $selection;
    
    if (isset($filter)) {
      $this->filter($filter);
    }
    return $this;
  }
 
 /**
  * Select all parents of the current element
  */
  public function parents($filter = NULL) {
    $selection = array();
    foreach ($this->selection as $element) {
      if (!$element->isTreeRoot()) {
        $element->parent()->addParent($selection);
      }
    }
    array_unique($selection);
    $this->selection = $selection;
    
    if (isset($filter)) {
      $this->filter($filter);
    }
    return $this;
  }

 /**
  * Select all siblings of the current element
  */
  public function siblings($filter = NULL) {
    $selection = array();
    foreach ($this->selection as $element) {
      $children = $element->parent()->_children;
      unset($children[$element['name']]);
      $selection = array_merge($selection, array_values($children));
//       foreach ($element->parent()->_children as $name => $child) {
//         if ($name != $element['name']) {
//           $selection[] = $child;
//         }
//       }
    }
    
    $this->selection = $selection;
    
    if (isset($filter)) {
      $this->filter($filter);
    }
    
    return $this;
  }
  
  /**
   * Select all descendants of the current element
   */
  public function descendants($filter = NULL) {
    $selection = array();
    foreach ($this->selection as $element) {
      $selection = array_merge($selection, $element->_descendants);
    }
    $this->selection = $selection;
    
    if (isset($filter)) {
      $this->filter($filter);
    }
    
    return $this;
  }
  
   /**
   * Select all descendants of the current element and the current element itself
   */
  public function all() {
    return $this->descendants()->add($this);
  }
  
  /**
   * Filter the current selection (dummy function, not working)
   */
  public function filter($expression) {
    $selection = array();
    // reg ex: 1
    if (!preg_match('!
        ([.#]{1})               # Either . for class names (types) or # for properties
        ([a-zA-Z_]+)            # $identifier
        (=([a-zA-Z_0-9]+))?     # optionally, =$value
        !', $expression, $matches)
      ) {
      return;
    }
    $identifier = $matches[2];
    switch ($matches[1]) {
      case '.':
        $type = 'type';
        break;
      case '#':
        $type = 'property';
        if (isset($matches[4])) {
          $value = $matches[4];
        }
    }
    foreach($this->selection as $element) {
      switch ($type) {
        case 'type':
          if ($element instanceof $identifier) {
            $selection[] = $element;
          }
        break;
        case 'property': 
          if (isset($element[$identifier])) {
            if ( (!isset($value) && $element[$identifier]) || (isset($value) && $element[$identifier] == $value)) {
              $selection[] = $element;
            }
          }
         break;
      }
    }
    $this->selection = $selection;
    return $this;
  }
  
  // This should just be part of filter and f with some syntax like .type
  public function filterByType($type) {
    $selection = array();
    foreach($this->selection as $element) {
      if ($element instanceof $type) { 
        $selection[] = $element;
      }
    }
    $this->selection = $selection;
    return $this;
  }
  
  /**
   * A query engine should live here. Imagine something like fQuery.
   * This should allow you to select elements with a CSS-like syntax
   * and then iterate over them with foreach.
   */
  public function f($query) {
  }

}