[HttpCachingBridgeAbstract] Create new page

HttpCachingBridgeAbstract.md

@@ -0,0 +1,78 @@
+`HttpCachingBridgeAbstract` extends [`BridgeAbstract`](BridgeAbstract) and adds functions to store contents into a local cache in order to reduce bandwidth requirements.
+
+**Usage example**: _Your bridge loads one page and collects a range of items. Optionally the full article can be included for each item. It is not recommended to always download ALL full articles. Instead full articles of already requested items can be stored in the local cache, so the next time the same request is processed, the full articles are loaded from cache rather than re-downloading them from the internet again._
+
+To create a new Bridge extending `HttpCachingBridgeAbstract` you must implement all required functions of [`BridgeAbstract`](BridgeAbstract). `HttpCachingBridgeAbstract` additionally provides following functions:
+
+* [`get_cached`](#the-get_cached-function)
+* [`get_cached_time`](#the-get_cached_time-function)
+* [`remove_from_cache`](#the-remove_from_cache-function)
+
+Find a [template](#template) at the end of this file.
+
+## The `get_cached` function
+
+This function receives the contents of a given URL from cache or, in case the contents have not yet been cached, from the internet.
+
+```PHP
+$this->get_cached('your URL');
+```
+
+or if you require the HTML DOM:
+
+```PHP
+$html = str_get_html($this->get_cached('your URL');
+```
+
+## The `get_cached_time` function
+
+This function returns the time stamp of the cached file for a given URL.
+
+```PHP
+$timestamp = $this->get_cached_time('your URL');
+```
+
+**Notice:** This function will download the contents, if the cache file for the given URL does not yet exist!
+
+## The `remove_from_cache` function
+
+**Important notice:** This function is not yet fully implemented (file is not actually removed from cache)!
+
+This function removes the cached file for a given URL from the cache.
+
+```PHP
+$this->remove_from_cache('your URL');
+```
+
+# Template
+
+This is the template for a new bridge:
+
+```PHP
+<?php
+class MySiteBridge extends HttpCachingBridgeAbstract{
+	public function loadMetadatas(){
+		$this->maintainer = 'No maintainer';
+		$this->name = 'Unnamed bridge';
+		$this->uri = '';
+		$this->description = 'No description provided';
+		$this->parameters = array();
+		$this->update = ``;
+	}
+
+	public function collectData(array $params){
+		// Implement your bridge here!
+
+		// Example for caching a page with automatic removal after 12 hours
+		$url = ''; // Insert your URL here!
+		$timestamp = $this->get_cached_time($url);
+
+		if($timestamp <= strtotime('-12 hours')){ // Cached file is too old (might have changed)
+			$this->remove_from_cache($url);
+		}
+
+		$html = str_get_html($this->get_cached($url));
+	}
+}
+// Imaginary empty line!
+```