<?php
/**
 * @version    $Id$
 * @package    In-Portal
 * @copyright    Copyright (C) 1997 - 2015 Intechnic. All rights reserved.
 * @license      GNU/GPL
 * In-Portal is Open Source software.
 * This means that this software may have been modified pursuant
 * the GNU General Public License, and as distributed it includes
 * or is derivative of works licensed under the GNU General Public License
 * or other free or open source software licenses.
 * See http://www.in-portal.org/license for copyright notices and details.
 */

defined('FULL_PATH') or die('restricted access!');

abstract class AbstractRouter extends kBase
{

	/**
	 * Include debugging url into build urls.
	 *
	 * @var boolean
	 */
	protected $debug = false;

	/**
	 * Prefix, that router uses for system integration. Could contain special.
	 *
	 * @var string
	 */
	protected $buildPrefix = '';

	/**
	 * Parameters, used during url building.
	 *
	 * @var array
	 */
	protected $buildParams = array();

	/**
	 * Router's default template.
	 *
	 * @var string
	 */
	protected $defaultTemplate = '';

	/**
	 * Include event from page url into links, generated on that page.
	 *
	 * @var boolean
	 */
	protected $keepEventFromUrl = false;

	/**
	 * Creates an instance of router
	 */
	public function __construct()
	{
		parent::__construct();

		$this->buildPrefix = $this->getPrefix();
		$this->debug = $this->Application->isDebugMode() && (defined('DBG_ROUTING') && DBG_ROUTING);
	}

	/**
	 * Add debug information to every returned url part.
	 *
	 * @param string|array $url_part Url part.
	 *
	 * @return array|string
	 */
	protected function debug($url_part)
	{
		if ( is_array($url_part) ) {
			return array_map(array($this, 'debug'), $url_part);
		}

		return '{' . $this->buildPrefix . ':' . $url_part . '}';
	}

	/**
	 * Returns unit config's prefix, that is associated with this router.
	 *
	 * @return string
	 */
	abstract public function getPrefix();

	/**
	 * Returns weight of this router among other routers.
	 *
	 * @return float|boolean Number - when order is important; false, when order isn't important.
	 */
	public function getWeight()
	{
		return false;
	}

	/**
	 * Wraps building part to hide internal implementation details.
	 *
	 * @param string  $prefix_special Prefix.
	 * @param array   $params         Params.
	 * @param boolean $keep_events    Keep events in url.
	 *
	 * @return mixed
	 */
	public final function buildWrapper($prefix_special, array &$params, $keep_events = false)
	{
		$this->buildPrefix = $prefix_special;
		$this->buildParams = $params;
		$this->keepEventFromUrl = $keep_events;

		$url_part = $this->build();
		$params = $this->buildParams;

		return $this->debug ? $this->debug($url_part) : $url_part;
	}

	/**
	 * Builds url part.
	 *
	 * @return boolean Return true to continue to next router; return false not to rewrite given prefix.
	 */
	abstract protected function build();

	/**
	 * Parses url part.
	 *
	 * @param array $url_parts Url parts to parse.
	 * @param array $params    Parameters, that are used for url building or created during url parsing.
	 *
	 * @return boolean Return true to continue to next router; return false to stop processing at this router.
	 */
	abstract public function parse(array &$url_parts, array &$params);

	/**
	 * Returns value of build parameter (would use global value, when not given directly).
	 *
	 * @param string $name    Name of parameter. Symbol "@" would be replaced to "prefix_special_".
	 * @param mixed  $default Default value.
	 *
	 * @return string|boolean
	 */
	protected function getBuildParam($name, $default = null)
	{
		$param_name = str_replace('@', $this->buildPrefix . '_', $name);

		if ( isset($this->buildParams[$param_name]) ) {
			return $this->buildParams[$param_name];
		}

		return isset($default) ? $default : $this->Application->GetVar($param_name);
	}

	/**
	 * Returns build template.
	 *
	 * @return string
	 */
	protected function getBuildTemplate()
	{
		return $this->Application->getPhysicalTemplate($this->getBuildParam('t'));
	}

	/**
	 * Sets new value of build parameter.
	 *
	 * @param string $name  Name of build parameter.
	 * @param string $value New build parameter value or NULL to remove it.
	 *
	 * @return void
	 */
	protected function setBuildParam($name, $value = null)
	{
		$param_name = str_replace('@', $this->buildPrefix . '_', $name);

		if ( isset($value) ) {
			$this->buildParams[$param_name] = $value;
		}
		else {
			unset($this->buildParams[$param_name]);
		}
	}

	/**
	 * Returns environment variable values for given prefix
	 * Uses directly given params, when available and removes them from build params afterwards.
	 *
	 * @return array
	 */
	protected function extractBuildParams()
	{
		list ($prefix) = explode('.', $this->buildPrefix);

		$query_vars = $this->Application->getUnitConfig($prefix)->getQueryString();

		if ( !$query_vars ) {
			// Given prefix doesn't use "env" variable to pass it's data.
			return false;
		}

		$event_key = array_search('event', $query_vars);

		if ( $event_key ) {
			// Pass through event of this prefix.
			unset($query_vars[$event_key]);
		}

		$event_name = $this->getBuildParam('@event', false);

		if ( ($event_name !== false && !$event_name) || ($event_name === false && !$this->keepEventFromUrl) ) {
			// If empty event passed, then remove it from url.
			// If keep event is off and event is not implicitly passed (to prevent global value).
			$this->setBuildParam('@event');
		}

		$ret = array();

		foreach ( $query_vars as $name ) {
			$ret[$this->buildPrefix . '_' . $name] = $this->getBuildParam('@' . $name);
			$this->setBuildParam('@' . $name);
		}

		return $ret;
	}

	/**
	 * Transforms event into form, that will survive in mod-rewritten url.
	 *
	 * @return void
	 */
	protected function keepEvent()
	{
		$event_name = $this->getBuildParam('@event');

		if ( $event_name ) {
			$this->setBuildParam('events[' . $this->buildPrefix . ']', $event_name);
			$this->setBuildParam('@event');
		}
	}

	/**
	 * Returns build parameters from given object (without changing it).
	 *
	 * @param kDBBase $object Object.
	 * @param array   $params Parameter set to use as base.
	 *
	 * @return array
	 */
	public function getBuildParams(kDBBase $object, array $params = array())
	{
		$params[$object->Prefix . '_id'] = $object->GetID();

		if ( !isset($params['pass']) ) {
			$params['pass'] = 'm,' . $object->Prefix;
		}

		return $params;
	}

	/**
	 * Marks url part as parsed.
	 *
	 * @param string $url_part        Url part.
	 * @param string $parse_direction Parse direction.
	 *
	 * @return void
	 */
	protected function partParsed($url_part, $parse_direction = 'ltr')
	{
		$this->getUrlProcessor()->partParsed($url_part, $parse_direction);
	}

	/**
	 * Determines if there is more to parse in url.
	 *
	 * @return boolean
	 */
	protected function moreToParse()
	{
		return $this->getUrlProcessor()->moreToParse();
	}

	/**
	 * Returns an instance of url processor in use.
	 *
	 * @return kRewriteUrlProcessor
	 */
	protected function getUrlProcessor()
	{
		return $this->Application->recallObject('kRewriteUrlProcessor');
	}

}