<?php
/* $Id$ */
namespace MCMS\Interfaces;

(defined('MCMS') && (basename(__FILE__) != basename($_SERVER['PHP_SELF']))) or die('ACCESS DENIED');

use \MCMS\User\iUser;
use \MCMS\Exception\ContextException;

/**
 * Interface of the System class and its childs.
 * All static methods (except init and getInstance) should have
 * a non-static equivalend with the same name, but starting with a _,
 * which should be protected. The static method is a link to the
 * protected method of the active instance.
 *
 * Custom implementations could extend the basic class with public methods.
 * this methods will be avaible by \MCMS\System::getInstance->customMethodName().
 *
 * @author Stefan Daurer <s.daurer@q-spot.org>
 * @package MCMS\System
 */
interface iSystem {
	const WEAVE_RUNNER = 'runner';
	const WEAVE_SYSTEM = 'system';
	const WEAVE_ROUTER = 'router';
	const WEAVE_LAYOUT = 'layout';
	
	/**
	 * Site-Id field key
	 */
	const TARGET_SITEID = 'siteId';
	/**
	 * Module instance field key
	 */
	const TARGET_INSTANCE = 'instance';
	/**
	 * Plugin instance field key
	 */
	const TARGET_PLUGIN = 'plugin';
	/**
	 * View field key
	 */
	const TARGET_VIEW = 'action';
	
	/**
	 * Request context in which the current processing is done
	 */
	const CTX_REQ = 'RequestContext';
	
	/**
	 * Cache context.
	 */
	const CTX_CACHE = 'CacheContext';
	
	/**
	 * Secrity context which provides authentication and authorization data
	 */
	const CTX_SECURITY = 'SecurityContext';
	
	/**
	 * Session context which provides data storages between requests
	 */
	const CTX_SESSION = 'SessionContext';

	/**
	 * Initializes the system and set the active instance to the MMSystem class.
	 * With that, the whole system can use modified implementions via the System class.
	 */
	static public function init(array $options = array());

	/**
	 * Checks if the system is initialized.
	 * 
	 * @return boolean true if an active system instance exists
	 */
	static public function isInitialized();

	/**
	 * Shut down the system class.
	 */
	static public function shutdown();

	/**
	 * Fetches the currently active iSystem instance.
	 *
	 * @return \MCMS\System the initialized system object
	 */
	static public function getInstance();

	/**
	 * Defines a context implementation
	 *
	 * @param string $type        	
	 * @param iContext $instance        	
	 * @param boolean $overwrite
	 *        	if NOT true, setting a already defined context will result in an
	 *        	exception
	 */
	public function initContext($type, iContext $instance, $overwrite = false);

	/**
	 * Checks if a context is defined
	 * @param string $type the context identifier
	 * @return boolean
	 */
	public function isContextSet($type);
	
	/**
	 * Fetches the matching context instance
	 *
	 * @param string $type
	 *        	the context identifier
	 * @throws ContextException if the context is undefined or unknown
	 * @return iContext the context object
	 */
	public static function getContext($type);

	/**
	 * Identifies the ident of the currently active website.
	 *
	 * @return int the id of website
	 */
	public function getSiteId();

	/**
	 *
	 * @return array the weaving configuration
	 */
	public function getWeaving();

	// #### user stuff ####
	/**
	 * Sets the user service instance.
	 * Can only be called once.
	 *
	 * @param string $pluginClass
	 *        	a plugin class name
	 * @param array $cfg
	 *        	an array of configuration settings
	 */
	public function initUserSvc($pluginClass, $cfg = array());

	/**
	 * Fetches the currently active user service instance.
	 *
	 * @return \MCMS\Plugin\iPlugInAuth the user service
	 */
	public function getUserSvc();

	/**
	 * checks if the user is allowed to access the administration panel
	 *
	 * @param iUser $user
	 *        	user object
	 * @return boolean if the user is privileged
	 */
	public function isUserSystemAdmin(iUser $user);
	
	// #### session stuff ####
	/**
	 * Fetches the active session object of this user
	 *
	 * @deprecated use System::getContext(iSystem::CTX_SESSION)
	 * @return \MCMS\Plugin\iPlugInSession active session instance
	 */
	public function getSession();
	
	// #### cache stuff ####
	/**
	 * Fetches the system cache object
	 *
	 * @return \MCMS\Plugin\iPluginCache the current cache implementation
	 */
	public function getCache();
	
	/**
	 * Private data storage
	 * @return \Mammut\Storage\VFS\iVFS
	 */
	public function getPrivateVFS();
	
	/**
	 * Public data storage
	 * @return \Mammut\Storage\VFS\iVFS
	 */
	public function getPublicVFS();
	/**
	 * Returns the current file cache location
	 *
	 * @param string $instance        	
	 * @param int $sideId        	
	 * @return \Mammut\IO\File the directory object
	 */
	public function getFileCacheDir($instance, $sideId = -1);

	/**
	 * Purges the file cache of an instance
	 *
	 * @param string $instance        	
	 * @param int $sideId        	
	 */
	public function purgeFileCacheDir($instance, $sideId = -1);

	/**
	 * Returns the current file cache location relative to the web root, useable as an url
	 *
	 * @param string $instance        	
	 * @param int $sideId        	
	 * @return string the path
	 */
	public function getFileCacheURL($instance, $sideId = -1);
	
	// #### file store stuff ####
	/**
	 * Creates a new file storage directory
	 * This method needs to be called if an module/plugin/...
	 * wants to store files. Most of the time
	 * this should be called in the module create instance hook.
	 *
	 * @since MCMS 1.0.1.0
	 * @param string $instance        	
	 * @param int $sideId        	
	 * @param boolean $public        	
	 * @return boolean true if created, false if exists already
	 * @throws \Mammut\IO\IOException on create errors
	 */
	public function createFileStoreDir($instance, $sideId = -1, $public = true);

	/**
	 *
	 * @param string $instance        	
	 * @param int $sideId        	
	 * @param boolean $public        	
	 */
	public function deleteFileStoreDir($instance, $sideId = -1, $public = true);

	/**
	 *
	 * @param string $instance        	
	 * @param int $sideId        	
	 * @param boolean $public        	
	 * @return boolean true if the storage exists
	 */
	public function fileStoreExists($instance, $sideId = -1, $public = true);

	/**
	 *
	 * @return \Mammut\IO\File the directory object
	 */
	public function getFileStoreDir($instance, $sideId = -1, $public = true);

	/**
	 *
	 * @param string $instance        	
	 * @param int $sideId        	
	 * @return string the path
	 */
	public function getFileStoreURL($instance, $sideId = -1); // no public param, cause there should be no access for private

	
	// #### database stuff ####
	/**
	 * creates a connection to the database
	 *
	 * @param $dsn string
	 *        	database descriptor
	 * @param $user string
	 *        	needed
	 * @param $password string
	 *        	of the user
	 * @param $options array        	
	 */
	public function initDB($dsn, $user, $password, array $options = array());
	
	// #### database stuff ####
	/**
	 * Add a named connection to an additional database
	 *
	 * @param $dsn string
	 *        	database descriptor
	 * @param $user string
	 *        	needed
	 * @param $password string
	 *        	of the user
	 * @param $options array        	
	 */
	public function addDB($name, $dsn, $user, $password, array $options = array());

	/**
	 * Disconnects the database
	 *
	 * @param $name string
	 *        	the database name, NULL (default) is the system database [optional]
	 */
	public function shutdownDB($name = NULL);

	/**
	 * Fetches an active database connection from the system.
	 * Those connections needs to be initialized first eigher by
	 * initDB() (system/default database) or addDB() (additional databases).
	 *
	 * @param $name string the name of the subdatabase, or NULL for the system database (default)
	 * @return \Mammut\DB\DB active database instance
	 * @throws \Mammut\Exception\IllegalStateException if the database has not been initialized
	 */
	public function getDB($name = NULL);

	/**
	 * Returns a list of all registered addon databases.
	 *
	 * @return array
	 */
	public function getDBXList();

	/**
	 *
	 * @return mixed the value of the system parameter (config files)
	 * @throws \InvalidArgumentException if the parameter is not defined
	 */
	public function getConfig($name);
	
	// site settings/component instance settings
	/**
	 * Fechtes a value from the global setting storage.
	 *
	 * @param integer $siteInst
	 *        	the site ID or NULL for global settings
	 * @param string $instance
	 *        	instance name of the element (modules,...)
	 * @param string $key
	 *        	the value key
	 * @param string $default
	 *        	a default value if none was found
	 * @return string the value
	 */
	public function getSiteParam($siteInst, $instance, $key, $default = NULL);

	/**
	 * Stores a value in the global setting storage.
	 *
	 * @param integer $siteInst
	 *        	The site ID or NULL for global settings
	 * @param string $instance
	 *        	Instance name of the element (modules,...)
	 * @param string $key
	 *        	The value key
	 * @param mixed $value
	 *        	The value to store
	 */
	public function setSiteParam($siteInst, $instance, $key, $value);

	
	/**
	 * Fetches the muliple language flag of the website
	 * @param int $siteId
	 * @return boolean true if multiple locales are enabled
	 */
	public function isMultiLocale($siteId = -1);
	
	/**
	 *
	 * @param
	 *        	int the id of the website, -1 for the current (optional)
	 * @return \Mammut\Locale\Locale the currently active locale
	 */
	public function getActiveLocale($siteId = -1);

	public function setUserLocale($locale, $siteId = -1);

	/**
	 *
	 * @return \DateTimeZone the active timezone
	 */
	public function getActiveTimezone();

	/**
	 *
	 * @return \Mammut\Locale\Locale[] the all avaible locales for the selected site
	 */
	public function getAllLocales($siteId = -1);

	/**
	 *
	 * @return \MCMS\Request an object which containts all parameter set by the request
	 */
	public function getRequest();

	/**
	 * returns the id of the currently active mammut cms target.
	 *
	 * @var $key string the target key (one of the iSystem::TARGET_* constants)
	 * @return mixed value
	 */
	public function getTarget($key);

	public function setTarget($key, $value);
	
	// #### form handling stuff ####
	public function setFormBuilderClass($class);

	/**
	 *
	 * @return string the form builder class
	 */
	public function getFormBuilderClass();

	public function setFormFetcherClass($class);

	/**
	 *
	 * @return string the form fetcher class
	 */
	public function getFormFetcherClass();

	/**
	 * Registers a datatype for forms
	 *
	 * @param $typename string
	 *        	datatype name
	 * @param $formEditorComponentClass string
	 *        	form element builder class
	 * @param $fetcherClass string
	 *        	the form value fetcher class
	 * @return void
	 */
	public function registerFormDatatype($typename, $formEditorComponentClass, $fetcherClass);

	/**
	 * removes a form type registration
	 *
	 * @param string $typename the of the type which should be removed
	 * @return void
	 */
	public function unregisterFormDatatype($typename);

	public function getFormDatatypeHandlers($type);

	/**
	 * creates a new form builder based on target
	 *
	 * @param $target mixed
	 *        	a class name or a model object
	 * @return \MCMS\_\Com\MCMS\Form\Builder
	 */
	public function createFormBuilder($target = false);

	/**
	 * creates a new form fetcher instance, based on target
	 *
	 * @param $target mixed
	 *        	a class name or a model object
	 * @param $ignore array
	 *        	fields which should be ignored
	 * @return \MCMS\_\Com\MCMS\Form\Fetcher
	 */
	public function createFormFetcher($target = false, array $ignore = array());
	
	// #### translation stuff ####
	/**
	 * Translates a text with the currently active translator and locale.
	 *
	 * All parameters excluding the first one can be in any order. They will be used:
	 * <ul>
	 * <li>string: to specify the gender (m,f,u)
	 * <li>integer: to specify the number of things
	 * <li>array: to specify parameter values (only one array parameter allowed)
	 * </ul>
	 *
	 * @param $text string
	 *        	text which should be translated
	 * @param $p1 mixed
	 *        	a integer or an string
	 */
	public function translate($text, $siteId = -1);

	/**
	 * System exception handler.
	 *
	 * @param $e \Exception        	
	 */
	public function onException(\Exception $e);
}