From c44fb25845437654b44d652bc49a1faa7b7dcea9 Mon Sep 17 00:00:00 2001
From: logmanoriginal <logmanoriginal@users.noreply.github.com>
Date: Mon, 13 Feb 2017 19:26:39 +0100
Subject: [PATCH] core: Improve documentation and style for BridgeAbstract and
 BridgeInterface

Public functions defined in BridgeAbstract also belong to BridgeInterface

getInput may only be used by this class or its children.
---
 lib/BridgeAbstract.php  | 47 ++++++++++++++++++++++++++++++++++-------
 lib/BridgeInterface.php | 44 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 8 deletions(-)

diff --git a/lib/BridgeAbstract.php b/lib/BridgeAbstract.php
index 6d35ba47..cc130442 100644
--- a/lib/BridgeAbstract.php
+++ b/lib/BridgeAbstract.php
@@ -20,7 +20,10 @@ abstract class BridgeAbstract implements BridgeInterface {
 	* @return mixed
 	*/
 	public function getCachable(){
-		return array("items" => $this->getItems(), "extraInfos" => $this->getExtraInfos());
+		return array(
+			'items' => $this->getItems(), 
+			'extraInfos' => $this->getExtraInfos()
+		);
 	}
 
 	/**
@@ -31,7 +34,13 @@ abstract class BridgeAbstract implements BridgeInterface {
 		return $this->items;
 	}
 
-
+	/**
+	 * Sets the input values for a given context. Existing values are 
+	 * overwritten.
+	 *
+	 * @param array $inputs Associative array of inputs
+	 * @param string $context The context name
+	 */
 	protected function setInputs(array $inputs, $queriedContext){
 		// Import and assign all inputs to their context
 		foreach($inputs as $name => $value){
@@ -89,7 +98,7 @@ abstract class BridgeAbstract implements BridgeInterface {
 			foreach(static::PARAMETERS['global'] as $name => $properties){
 				if(isset($inputs[$name])){
 					$value = $inputs[$name];
-				} elseif (isset($properties['value'])){
+				} elseif(isset($properties['value'])){
 					$value = $properties['value'];
 				} else {
 					continue;
@@ -106,10 +115,20 @@ abstract class BridgeAbstract implements BridgeInterface {
 		}
 	}
 
+	/**
+	 * Returns the name of the context matching the provided inputs
+	 *
+	 * @param array $inputs Associative array of inputs
+	 * @return mixed Returns the context name or null if no match was found
+	 */
 	protected function getQueriedContext(array $inputs){
 		$queriedContexts = array();
+
+		// Detect matching context
 		foreach(static::PARAMETERS as $context => $set){
 			$queriedContexts[$context] = null;
+
+			// Check if all parameters of the context are satisfied
 			foreach($set as $id => $properties){
 				if(isset($inputs[$id]) && !empty($inputs[$id])){
 					$queriedContexts[$context] = true;
@@ -119,8 +138,10 @@ abstract class BridgeAbstract implements BridgeInterface {
 					break;
 				}
 			}
+
 		}
 
+		// Abort if one of the globally required parameters is not satisfied
 		if(array_key_exists('global', static::PARAMETERS)
 		&& $queriedContexts['global'] === false){
 			return null;
@@ -128,14 +149,15 @@ abstract class BridgeAbstract implements BridgeInterface {
 		unset($queriedContexts['global']);
 
 		switch(array_sum($queriedContexts)){
-		case 0:
+		case 0: // Found no match, is there a context without parameters?
 			foreach($queriedContexts as $context => $queried){
-				if (is_null($queried)){
+				if(is_null($queried)){
 					return $context;
 				}
 			}
 			return null;
-		case 1: return array_search(true, $queriedContexts);
+		case 1: // Found unique match
+			return array_search(true, $queriedContexts);
 		default: return false;
 		}
 	}
@@ -193,7 +215,13 @@ abstract class BridgeAbstract implements BridgeInterface {
 		}
 	}
 
-	function getInput($input){
+	/**
+	 * Returns the value for the provided input
+	 *
+	 * @param string $input The input name
+	 * @return mixed Returns the input value or null if the input is not defined
+	 */
+	protected function getInput($input){
 		if(!isset($this->inputs[$this->queriedContext][$input]['value'])){
 			return null;
 		}
@@ -209,7 +237,10 @@ abstract class BridgeAbstract implements BridgeInterface {
 	}
 
 	public function getExtraInfos(){
-		return array("name" => $this->getName(), "uri" => $this->getURI());
+		return array(
+			'name' => $this->getName(), 
+			'uri' => $this->getURI()
+		);
 	}
 
 	public function setCache(\CacheInterface $cache){
diff --git a/lib/BridgeInterface.php b/lib/BridgeInterface.php
index a7932a87..fbb7a0f0 100644
--- a/lib/BridgeInterface.php
+++ b/lib/BridgeInterface.php
@@ -1,6 +1,50 @@
 <?php
 interface BridgeInterface {
+
+	/**
+	 * Collects data from the site
+	 */
 	public function collectData();
+
+	/**
+	 * Returns an array of cachable elements
+	 *
+	 * @return array Associative array of cachable elements
+	 */
+	public function getCachable();
+
+	/**
+	 * Return an array of extra information
+	 *
+	 * @return array Associative array of extra information
+	 */
+	public function getExtraInfos();
+
+	/**
+	 * Returns an array of collected items
+	 *
+	 * @return array Associative array of items
+	 */
+	public function getItems();
+
+	/**
+	 * Returns the bridge name
+	 *
+	 * @return string Bridge name
+	 */
 	public function getName();
+
+	/**
+	 * Returns the bridge URI
+	 *
+	 * @return string Bridge URI
+	 */
 	public function getURI();
+
+	/**
+	 * Sets the cache instance
+	 *
+	 * @param object CacheInterface The cache instance
+	 */
+	public function setCache(\CacheInterface $cache);
 }