<?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().
 *
 * @package MCMS
 * @subpackage Interfaces
 * @author Stefan Daurer (s.daurer@qdevzone.net)
 */
interface iSystem {
	
	/**
	 * site-id field key
	 */
	const TARGET_SITEID = 'siteId';
	/**
	 * module instance field key
	 */
	const TARGET_INSTANCE = 'instance';
	/**
	 * 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();

	/**
	 * 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);

	/**
	 * 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
	 */
	static public function getContext($type);

	/**
	 * Identifies the ident of the currently active website.
	 *
	 * @return int the id of website
	 */
	public function getSiteId();

	/**
	 * Creates a list of basic plugins, used by the base system.
	 *
	 * @return array a list of base plugins
	 */
	public function getBasePlugins();

	/**
	 * Creates a list of basic plugins for the administration interface, used by the base
	 * system.
	 *
	 * @return array an array of base plugins
	 */
	public function getBaseAdminPlugins();
	
	// #### 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
	 * 
	 * @deprecated use System::getContext(iSystem::CTX_CACHE)
	 * @return Mammut\Cache\iCache the current cache implementation
	 */
	public function getCache();

	/**
	 * 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 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 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 the
	 *        	name of the subdatabase, or NULL for the system database (default)
	 * @return \Mammut\DB\DB active database instance
	 * @throws InvalidStateException 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
	public function getSiteParam($siteInst, $comInst, $key, $default = NULL);

	public function setSiteParam($siteInst, $comInst, $key, $value);

	/**
	 *
	 * @param
	 *        	int the id of the website, -1 for the current (optional)
	 * @return 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 iTarget::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 $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);
	
	// #### error/logging stuff ####
	/**
	 * Add a new entry into the system logger.
	 *
	 * @param $level int
	 *        	an error constant
	 * @param $code int
	 *        	an error code
	 * @param $message string
	 *        	a text representing the error
	 */
	public function doLog($level, $code, $message);

	/**
	 * System exception handler.
	 *
	 * @param $e Exception        	
	 */
	public function onException(\Exception $e);
}