rss-bridge/CREATE_BRIDGE.md

Howto create a bridge

A bridge is an class that allows rss-bridge to create a RSS feed from a website. The bridge is a PHP file, located in the bridges/ folder.

Read the following chapters an make sure to read the Guidelines!

Specifications

A rss bridge must extend the BridgeAbstract class and implement the following functions :

• loadMetadatas (required)
• collectData (required)
• getName
• getURI
• getCacheDuration

Find a template at the end of this file.

The loadMetadatas function

This function is used by rss-bridge to determine the name, maintainer name, website, last updated date... of the bridge, and the user parameters.

Basic metadatas

The basic metadatas are :

$this->maintainer // Name of the maintainer
$this->name // Name of the bridge
$this->uri // URI to the target website of the bridge ("http://....")
$this->description // A brief description of the bridge
$this->update // Date of last change in format "yyyy-mm-dd"
$this->parameters // (optional) Definition of additional parameters

Find a description of $this->parameters below

The default values are :

$this->maintainer = 'No maintainer';
$this->name = "Unnamed bridge";
$this->uri = "";
$this->description = 'No description provided';
$this->parameters = array();

Parameters

Parameters are defined in a JSON-like format, which is parsed and transformed into a HTML <form> by rss-bridge.

These datas goes into the $this->parameters array, which is not mandatory if your bridge doesn't take any parameter.

Every possible usage of a bridge is an array element.

The array can be a key-based array, but it is not necessary. The following syntaxes are hereby correct :

$this->parameters[] = ...
$this->parameters['First usage of my bridge'] = ...

It is worth mentionning that you can also define a set of parameters that will be applied to every possible utilisation of your bridge. To do this, just create a parameter array with the global key :

$this->parameters['global'] = ...

Format specifications

Every $this->parameters element is a JSON array of cluster ([ ... ]) containing all input fields.

Following elements are supported :

Parameter Name	Required	Type	Supported values	Description
name	yes	Text		Input name as displayed to the user
identifier	yes	Text		Identifier, which will be the key in the $param array for the collectData function
type	no	Text	text, number, list, checkbox	Type of the input, default is text
required	no	Boolean	true, false	Set this if you want your attribute to be required
values	no	Text	[ {"name" : option1Name, "value" : "option1Value"}, ... ]	Values list, required with the 'list' type
title	no	Text		Will be shown as tooltip when mouse-hovering over the input

Hence, the most basic parameter definition is the following :

...
	$this->parameters[] =
	'[
		{
			"name" : "Username",
			"identifier" : "u"
		}
	]';
...

The collectData function

This function takes as a parameter an array called $param, that is automatically filled with values from the user, according to the values defined in the parameters array in loadMetadatas. This function is the place where all the website scrapping and the RSS feed generation process must be implemented.

RSS elements collected by this function must be stored in the class variable items[].

Every RSS element is an instance of the Item class.

Items

The Item class is used to store parameter that are collected in the collectData function. Following properties are supported by rss-bridge :

$item->uri // URI to reach the subject ("http://...")
$item->thumbnailUri // URI for the thumbnail ("http://...")
$item->title // Title of the item
$item->name // Name of the item
$item->timestamp // Timestamp of the item in numeric format (use strtotime)
$item->author // Name of the author
$item->content // Content in HTML format

In order to create a new item you'll have to escape the I in Item like this :

$item = new \Item();

Item usage

Which items are necessary depends on the output format. There are two formats that support literally any property in the $item:

• JSON
• Plaintext

The following list provides an overview of the parameters used by the other formats :

Parameter	ATOM	HTML	(M)RSS
uri	X	X	X
thumbnailUri		X
title	X	X	X
name	X
timestamp	X	X	X
author	X	X	X
content	X	X	X

The getName function

This function returns the name of the bridge as it will be displayed on the main page of rss-bridge or on top of the feed output (HTML, ATOM, etc...).

Notice: rss-bridge will by default return $this->name which is defined in the loadMetadatas function, so you only have to implement this function if you require different behavior!

	public function getName(){
		return $this->name;
	}

The getURI function

This function returns the URI to the destination site of the bridge. It will be used on the main page of rss-bridge when clicking your bridge name.

Notice: rss-bridge will by default return $this->uri which is defined in the loadMetadatas function, so you only have to implement this function if you require different behavior!

	public function getURI(){
		return $this->uri;
	}

The getCacheDuration function

This function returns the time in seconds during which rss-bridge will output cached values instead of re-generating a RSS feed.

Notice: rss-bridge will return 3600 seconds (1 hour) by default, so you only have to implement this function if you require different timing!

	public function getCacheDuration(){
		return 3600; // 1 hour
	}

Bridge Abstract functions

All bridges extend from BridgeAbstract and therefore are able to make use of functions defined in BridgeAbstract.

Following functions should be used for good practice and will support you with your bridge :

• returnError
• file_get_html

The returnError function

This function aborts execution of the current bridge and returns the given error message with the provided error number :

$this->returnError('Your error message', 404)

Check the list of error codes for applicable error numbers.

The file_get_html function

This function is a wrapper around the simple_html_dom file_get_html function in order to provide context by design. It is considered good practice to use this function.

$html = $this->file_get_html('your URI');

Guidelines

• scripts (eg. Javascript) must be stripped out. Make good use of strip_tags() and preg_replace()
• each bridge must present data within 8 seconds (adjust iterators accordingly)
• cache timeout must be fine-tuned so that each refresh can provide 1 or 2 new elements on busy periods
• <audio> and <video> must not autoplay. Seriously.
• do everything you can to extract valid timestamps. Translate formats, use API, exploit sitemap, whatever. Free the data!
• don't create duplicates. If the website runs on WordPress, use the generic WordPress bridge if possible.
• maintain efficient and well-commented code 😉

Template

This is the minimum template for a new bridge:

<?php
class MySiteBridge extends BridgeAbstract{
	public function loadMetadatas(){
		$this->maintainer = 'No maintainer';
		$this->name = 'Unnamed bridge';
		$this->uri = '';
		$this->description = 'No description provided';
		$this->parameters = array();
	}

	public function collectData(array $params){
		// Implement your bridge here!
	}
}