File Source for Formagic.php

<?php
/**
* Formagic
*
* LICENCE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at
* http://formagic.weasle.de/licence.txt
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to licence@weasle.de so we can send you a copy immediately.
*
* @category Formagic
* @package Formagic
* @author Florian Sonnenburg
* @copyright Copyright (c) 2007 Florian Sonnenburg
* @license http://formagic.weasle.de/licence.txt New BSD License
* @revision $Revision: 19 $
*/
require_once 'Item/Item.php';
require_once 'Renderer/Renderer.php';
/**
* Formagic main and interface class
*
* Highly extensible formgenerator with various rendering options, form
* validation and multipage support.
*
* @category Formagic
* @package Formagic
* @author Florian Sonnenburg
* @copyright Copyright (c) 2007 Florian Sonnenburg
* @version $Id: Formagic.php 19 2007-08-22 22:02:47Z meweasle $
***/
class Formagic
{
/**
* Form name, used for eg. form action tag in HTML renderer
* @var string
*/
public $name = 'undefined';
/**
* Form submission method (POST or GET)
* @var string
*/
public $method = 'post';
/**
* Item values that are not effected by POST/GET
* @var array
***/
public $constantValues = array();
/**
* Points to either $_POST or $_GET
* @var array
*/
public $submitValues;
/**
* Array of predefined values for this Formagic object
* @var array
*/
public $defaultValues;
/**
* Type of renderer used to display form
* @see Formagic::setRenderer()
* @var string
*/
private $_renderer = null;
/**
* Enables or disabled submission tracking. Contains string with variable
* name if enabled or FALSE if disabled
* @var mixed String or FALSE
*/
private $_trackSubmission = '__fm';
/**
* container item holding all items added to Formagic object
* @var object
*/
private $_itemHolder;
/**
* Array of directories custom classes are searched for
* @var array
*/
private $_pluginDir;
/**
* Caches result of method Formagic::validate()
* @var string
* @see Formagic::validate();
*/
private $_isValid = null;
/**
* Flag that defines if FormagicItems contained by Formagic object can be
* edited
* @var boolean
***/
private $_isBlocked = false;
/**
* Contains Formagic form messages (errors, notices, debugs)
* @var array
***/
private $_formMessages = array();
/**
* Valid callback to be executed when form is submitted
* @var mixed
***/
private $_executeCallback;
/**
* Name of currently active page
* @var string
* @see Formagic::addItem();
***/
private $_currentPage = 'default';
/**
* Action for form tag
* @var string
***/
private $_formAction = null;
const VERSION = '0.2.3b';
const API_VERSION = '1.2';
const PAGE_TRACKING_KEY = '__fm_rp';
const PAGE_REQUEST_KEY = '__fm_sw';
const ERROR = 1;
const NOTICE = 2;
const DEBUG = 3;
/**
* Consructor
*
* @param array $options
* @throws Formagic_Exception
* @return void
***/
public function __construct($name='formagic', $options = null)
{
// call event
$this->_execEvent('onCreate');
$this->name = $name;
// process options
if ($options) {
$this->setOption($options);
}
// set pointer to submission pool (GET or POST)
if ($this->method == 'post') {
$this->submitValues =& $_POST;
} elseif ($this->method == 'get') {
$this->submitValues =& $_GET;
} else {
throw new Formagic_Exception("Formagic submit method {$this->method} not " .
"supported");
}
// set item container of main Formagic object
$this->_itemHolder = $this->createItem('container', '__fm_itemholder');
// handle trackSubmission
if ($this->_trackSubmission) {
$this->_trackSubmission .= "_" . $this->name;
$tsi = $this->addItem('hidden',$this->_trackSubmission,array('default'=>1));
$tsi->isExecuteItem = false;
}
// // set saved values
// switch($this->_multipageStorage) {
// case 'hidden':
// if (isset($this->submitValues['__fm_sv'])) {
// $this->savedValues =& $this->submitValues['__fm_sv'];
// }
// break;
// case 'session':
// // $this->savedValues =& $_SESSION['__fmsv'];
// break;
// default:
// throw new Formagic_Exception("Storage engine {$this->storage} for " .
// "multipaged forms not supported");
// } // switch
}
/**
* Sets Formagic option $name to $value
*
* Triggers warning if option $name is not supported.
*
* @param string $name Formagic option name or array with name => value
* @param mixed $value value of option $name
* @throws Formagic_Exception
* @return boolean
*/
public function setOption($options, $value=null)
{
if (!is_array($options)) {
$options = array($options => $value);
}
foreach($options as $name => $value) {
switch($name) {
// set custom action
case 'action':
if (is_string($value)) {
$this->_formAction = $value;
} else {
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>('Action has to be string value');
}
break;
// set custom renderer
case 'renderer':
$this->setRenderer($value);
break;
// set plugin dir
case 'FormagicPluginDir':
$this->_pluginDir = (array)$value;
break;
// set submission method
case 'method':
$this->method = $value;
break;
// add hidden input for submission tracking if enabled
case 'trackSubmission':
$this->_trackSubmission = $value;
break;
// set default values
case 'defaultValues':
$this->setDefaultValues($value);
break;
// set storage engine for saved values
case 'multipageStorage':
$this->_multipageStorage = $value;
break;
case 'executeCallback':
$this->setExecuteCallback($value);
default:
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>("Option $name not supported");
} // switch
}
return true;
}
/**
* Defines renderer for current Formagic object
*
* @param string $renderer FormagicRenderer object or string with name of
* renderer class
* @return boolean
*/
public function setRenderer($renderer)
{
if ($renderer instanceOf Formagic_Renderer) {
$this->_renderer = $renderer;
return true;
}
$class = 'Formagic_Renderer_' . $renderer;
try {
$this->loadClass($class);
} catch (<a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a> $e) {
return false;
}
$this->_renderer = new $class();
return true;
}
/**
* Formagic::setDefaultValues()
*
* @param array $values
* @return array
*/
public function setDefaultValues($values)
{
$this->defaultValues = array_merge($this->defaultValues,$values);
return $this->defaultValues;
}
/**
* Set callback property
*
* $callback has to be a valid PHP callback variable.
*
* @param mixed $callback
* @return void
*/
public function setExecuteCallback($callback)
{
$this->_executeCallback = $callback;
}
/**
* Destructor
*
* Restores formerly manipulated include path.
*
* @return void
**/
public function __destruct()
{
$this->_execEvent('onDestruct');
}
/**
* Returns result for string casting of Formagic object
*
* @return string
**/
public function __toString()
{
$numItems = $this->countItems();
$submitted = (int)$this->isSubmitted();
$str = "Formagic [name: '{$this->name}']" .
"[items loaded: '$numItems'][isSubmitted: '$submitted']" .
"<br />";
// $str = "<pre>". print_r($this->_items,true) ."</pre>";
return $str;
}
// public function __call($method, $arguments)
// {
//
// }
/**
* Returns number of items added to Formagic object
*
* Counts total number of items recursively
*
* @return integer
*/
public function countItems()
{
return $this->_itemHolder->countItems();
}
/**
* Adds Formagic item object to array of first level form items
*
* Creates new item object and adds this or adds passed FormagicItem object
*
* @param mixed $type String with item type or FormagicItem object
* @param string $name String with item name. NULL if $type is FormagicItem
* object
* @param array $args Array with additional item information. NULL if $type
* is FormagicItem object
* @return object FormagicItem object
*/
public function addItem($type, $name, $args=null)
{
return $this->_itemHolder->addItem($type, $name, $args);
}
/**
* Creates and returns FormagicItem object
*
* Tries to load correct object class and creates new object. Returns object
* if successfull, false if not.
*
* @param string $type
* @param string $name
* @param array $args
* @return Formagic_Item
*/
public function &createItem($type, $name, $args=null)
{
$class = 'Formagic_Item_' . ucFirst($type);
$this->loadClass($class);
$obj = new $class($type, $name, $args, $this);
if ($obj->_execEvent('onCreate')) {
return $obj;
}
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>('Event onCreate of item object returned error');
}
/**
* Returns pointer to Formagic items array
*
* @return array
*/
public function &getItemHolder()
{
return $this->_itemHolder;
}
/**
* Returns current form action
*
* @return string
*/
public function getFormAction()
{
if (!$this->_formAction) {
$this->_formAction = $_SERVER['PHP_SELF'];
}
return $this->_formAction;
}
/**
* Checks if form is submitted and all rules apply
*
* Iterates through all items added to the form. If any rule is violated,
* iteration is stopped. Returns true if no rules are violated.
* The result of validate() is cached.
*
* @return boolean
*/
public function validate()
{
// return cached validation result if present
if (is_bool($this->_isValid)) {
return $this->_isValid;
}
// check event
if (!$this->_execEvent('onValidation')) {
return $this->_isValid = false;
}
// Assume that validation is negative if form is not submitted
if (!$this->isSubmitted()) {
return $this->_isValid = false;
}
$this->_isValid = true;
$items = $this->_itemHolder->getItems();
$messageWritten = false;
foreach($items as $item) {
$res = $item->validate();
if ($res instanceOf <a href="../Rule/Formagic_Rule.html">Formagic_Rule</a>) {
if (!$messageWritten) {
$this->setMessage('Bitte markierte Eingabefelder prüfen', self::ERROR);
$messageWritten = true;
}
$this->_isValid = false;
} elseif($res == false) {
$this->_isValid = false;
}
}
// check event
if (!$this->_execEvent('onValidationComplete')) {
return $this->_isValid = false;
}
return $this->_isValid;
}
/**
* Returns output generated by renderer
*
* Loads renderer class and calls renderer::fetch()
*
* @return string Renderer result
*/
public function fetch()
{
$this->_itemHolder->_execEvent('onFetch');
if (!($this->_renderer instanceOf <a href="../Renderer/Formagic_Renderer.html">Formagic_Renderer</a>)) {
$this->setRenderer('HTML');
}
return $this->_renderer->fetch($this);
}
/**
* Runs execute callback
*
* @throws Formagic_Exception
* @return void
*/
public function execute()
{
$arr = $this->getValues();
if (!isset($this->_executeCallback)) {
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>('No valid callback to execute');
}
if (
(is_string($this->_executeCallback) && !function_exists($this->_executeCallback))
|| (is_array($this->_executeCallback) &&
!method_exists($this->_executeCallback[0], $this->_executeCallback[1]))
) {
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>('Method or function does not exist');
}
call_user_func($this->_executeCallback, $arr);
}
/**
* Returns item value from Formagic value pool
*
* @param string $name
* @return mixed
*/
public function &getValue($name)
{
if (isset($this->constantValues[$name])) {
return $this->constantValues[$name];
}
if (isset($this->submitValues[$name])) {
return $this->submitValues[$name];
}
// if (isset($this->savedValues[$name])) {
// return $this->savedValues[$name];
// }
return $this->defaultValues[$name];
}
/**
* Returns array with values from all added items
*
* @return array
*/
public function getValues()
{
$items = $this->_itemHolder->getItems();
$values = array();
$this->_getValueFromItemRecursive($items, $values);
return $values;
}
/**
* Recursively iterates through $items and fills $values
*
* @param array $items
* @param array $values
* @return void
*/
private function _getValueFromItemRecursive($items, &$values)
{
foreach($items as $item) {
if ($item instanceOf <a href="../Item/Formagic_Item_Container.html">Formagic_Item_Container</a>) {
$this->_getValueFromItemRecursive($item->getItems(), $values);
} else {
if ($item->isPostItem && strpos($item->name, '__fm') === false) {
$values[$item->name] = $this->getValue($item->name);
}
}
}
}
/**
* Checks if HTML form is submitted
*
* Check result is true for following rules:
* - if submission tracking is enabled in Formagic options and the
* submission variable is present
* - if submission tracking is disabled, but either GET or POST values
* (dependent on chosen submission method) are present
*
* @return boolean
*/
public function isSubmitted()
{
// Return value of trackSubmission variable if tracking enabled
if ($this->_trackSubmission) {
return !empty($this->submitValues[$this->_trackSubmission]);
}
// If tracking disabled, guess submission status from $_POST/$_GET
if (count($this->submitValues)) {
return true;
}
return false;
}
/**
* Freezes form
*
* @return boolean
*/
public function block()
{
$this->_isBlocked = true;
$items =& $this->_itemHolder->getItems();
foreach($items as &$item) {
$item->block();
}
return true;
}
/**
* Adds $message to Formagic message stack
*
* Predefined $levels:
* - ERROR
* - NOTICE
* - DEBUG
*
* Other levels can be used if neccessary. Corresponding level has to be
* used in Formagic::getMessages()
*
* @see Formagic::getMessages()
* @param string $message
* @param string $level
* @return string
*/
public function setMessage($message, $level)
{
$this->_formMessages[$level][] = $message;
return $message;
}
/**
* Returns Formagic messages of level $level or empty array if no messages
* of that level.
*
* @param string $level
* @throws Formagic_Exception
* @return array
*/
public function getMessages($level=null)
{
if (!$level) {
return $this->_formMessages;
}
if (isset($this->_formMessages[$level])) {
return $this->_formMessages[$level];
} else {
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>('No such message level as "' . $level . '"');
}
}
/**
* Includes Formagic extension class
*
* Skipped if class is already loaded. loadClass() tries to load from any
* extension directories defined. Returns true if successful, false if not.
*
* @param string $class Class name. File name is $class.php
* @throws Formagic_Exception
* @return boolean
*/
public function loadClass($class)
{
if (class_exists($class)) {
return true;
}
$chunks = explode('_', $class);
$file = '.'.DIRECTORY_SEPARATOR.$chunks[1].DIRECTORY_SEPARATOR.$chunks[2].'.php';
if (!include($file)) {
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>("Formagic item class \"$class\" could not be loaded");
}
return true;
}
/**
* Formagic event dispatcher
*
* @param string $event Event to be triggered
* @return boolean
*/
protected function _execEvent($event)
{
switch($event) {
case 'onValidationComplete':
case 'onValidation':
case 'onCreate':
case 'onDestruct':
case 'onAddItem':
break;
default:
throw new <a href="../Formagic/Formagic_Exception.html">Formagic_Exception</a>("Event $event not supported");
} // switch
return true;
}
}
/**
* Generic Formagic Exception class
*
* @category Formagic
* @package Formagic
* @author Florian Sonnenburg
* @copyright Copyright (c) 2007 Florian Sonnenburg
* @version $Id: Formagic.php 19 2007-08-22 22:02:47Z meweasle $
*/
class Formagic_Exception extends Exception
{

Source for file Formagic.php