mirror of
https://github.com/RSS-Bridge/rss-bridge.git
synced 2025-08-05 08:07:33 +02:00
Updated BridgeAbstract (markdown)
LogMANOriginal
@@ -2,12 +2,12 @@
|
||||
|
||||
To create a new Bridge extending `BridgeAbstract` you must specify some [basic metadata](#basic-metadata) implement following functions:
|
||||
|
||||
- [`collectData`](#the-collectdata-function) (**required**)
|
||||
- [`collectData`](The-collectData-function) (**required**)
|
||||
- [`getDescription`](The-getDescription-function)
|
||||
- [`getMaintainer`](#the-getmaintainer-function)
|
||||
- [`getName`](#the-getname-function)
|
||||
- [`getURI`](#the-geturi-function)
|
||||
- [`getIcon`](#the-geticon-function)
|
||||
- [`getMaintainer`](The-getMaintainer-function)
|
||||
- [`getName`](The-getName-function)
|
||||
- [`getURI`](The-getURI-function)
|
||||
- [`getIcon`](The-getIcon-function)
|
||||
|
||||
Find a [template](#template) at the end of this file.
|
||||
|
||||
@@ -128,209 +128,6 @@ If a more complex organization is required to display the values, the above key/
|
||||
...
|
||||
```
|
||||
|
||||
## The `collectData` function
|
||||
|
||||
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[]`.
|
||||
|
||||
Each RSS element is an associative array that may contain arbitrary keys. Depending on the output format a range of keys is defined.
|
||||
|
||||
In order to receive a value for a parameter you specified in `const PARAMETERS`, make use of the `getInput` function:
|
||||
|
||||
```PHP
|
||||
$this->getInput('your input name here');
|
||||
```
|
||||
|
||||
## Items
|
||||
|
||||
The item array is used to store parameter that are collected in the [`collectData`](#the-collectdata-function) function. Following properties are supported by **RSS-Bridge** :
|
||||
|
||||
```PHP
|
||||
$item['uri'] // URI to reach the subject ("http://...")
|
||||
$item['title'] // Title 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
|
||||
$item['enclosures'] // Array of URIs to an attachments (pictures, files, etc...)
|
||||
$item['categories'] // Array of category names
|
||||
```
|
||||
|
||||
### Item usage
|
||||
|
||||
Which items are possible depends on the output format used. 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
|
||||
`title`|X|X|X
|
||||
`timestamp`|X|X|X
|
||||
`author`|X|X|X
|
||||
`content`|X|X|X
|
||||
`enclosures`|X|X|X
|
||||
`categories`|X|X|X
|
||||
|
||||
## The `getMaintainer` function
|
||||
|
||||
This function returns the maintainer name of a bridge.
|
||||
|
||||
**Notice:** **RSS-Bridge** will by default return `const MAINTAINER` which is defined in the bridge, so you only have to implement this function if you require different behavior!
|
||||
|
||||
```PHP
|
||||
public function getMaintainer(){
|
||||
return self::MAINTAINER;
|
||||
}
|
||||
```
|
||||
|
||||
## The `getName` function
|
||||
|
||||
This function returns the name of a bridge..
|
||||
|
||||
**Notice:** **RSS-Bridge** will by default return `const NAME` which is defined in the bridge, so you only have to implement this function if you require different behavior!
|
||||
|
||||
```PHP
|
||||
public function getName(){
|
||||
return self::NAME;
|
||||
}
|
||||
```
|
||||
|
||||
## The `getURI` function
|
||||
|
||||
This function returns the URI to the destination site of a bridge.
|
||||
|
||||
**Notice:** **RSS-Bridge** will by default return `const URI` which is defined in the bridge, so you only have to implement this function if you require different behavior!
|
||||
|
||||
```PHP
|
||||
public function getURI(){
|
||||
return self::URI;
|
||||
}
|
||||
```
|
||||
|
||||
## The `getIcon` function
|
||||
|
||||
This function returns the URI for an icon, used as favicon in the feeds. If no icon is specified by the bridge, RSS-Bridge will use the "default" location `static::URI . '/favicon.ico'` (i.e. "https://github.com/favicon.ico") which may or may not exist.
|
||||
|
||||
```PHP
|
||||
public function getIcon(){
|
||||
return self::URI . '/favicon.ico';
|
||||
}
|
||||
```
|
||||
|
||||
## Queried context
|
||||
|
||||
The queried context is defined via `PARAMETERS` and can be accessed via `$this->queriedContext`.
|
||||
It provides a way to identify which context the bridge is called with.
|
||||
|
||||
Example:
|
||||
|
||||
```PHP
|
||||
...
|
||||
const PARAMETERS = array(
|
||||
'By user name' => array(
|
||||
'u' => array('name' => 'Username')
|
||||
),
|
||||
'By user ID' => array(
|
||||
'id' => array('name' => 'User ID')
|
||||
)
|
||||
);
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
In this example `$this->queriedContext` will either return **By user name** or **By user ID**. The queried context might return no value, so the best way to handle it is by using a case-structure:
|
||||
|
||||
```PHP
|
||||
switch($this->queriedContext){
|
||||
case 'By user name':
|
||||
break;
|
||||
case 'By user ID':
|
||||
break;
|
||||
default: // Return default value
|
||||
}
|
||||
```
|
||||
|
||||
# Helper functions
|
||||
|
||||
Helper functions are independent functions that help you to manage specific events in your bridges.
|
||||
|
||||
* [`returnError`](#the-returnerror-function)
|
||||
* [`returnClientError`](#the-returnclienterror-function)
|
||||
* [`returnServerError`](#the-returnservererror-function)
|
||||
* [`getContents`](#the-getcontents-function)
|
||||
* [`getSimpleHTMLDOM`](#the-getSimpleHTMLDOM-function)
|
||||
* [`getSimpleHTMLDOMCached`](#the-getsimplehtmldomcached-function)
|
||||
|
||||
## The `returnError` function
|
||||
|
||||
**Notice:** Whenever possible make use of [`returnClientError`](#the-returnclienterror-function) or [`returnServerError`](#the-returnservererror-function)
|
||||
|
||||
This function aborts execution of the current bridge and returns the given error message with the provided error number :
|
||||
|
||||
```PHP
|
||||
$returnError('Your error message', 404)
|
||||
```
|
||||
|
||||
Check the [list of error codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for applicable error numbers.
|
||||
|
||||
## The `returnClientError` function
|
||||
|
||||
This function aborts execution of the current bridge and returns the given error message with error code **400**:
|
||||
|
||||
```PHP
|
||||
returnClientError('Your error message')
|
||||
```
|
||||
|
||||
Use this function when the user provided invalid parameter or a required parameter is missing.
|
||||
|
||||
## The `returnServerError` function
|
||||
|
||||
This function aborts execution of the current bridge and returns the given error message with error code **500**:
|
||||
|
||||
```PHP
|
||||
returnServerError('Your error message')
|
||||
```
|
||||
|
||||
Use this function when a problem occurs that has nothing to do with the parameters provided by the user. (like: Host service gone missing, empty data received, etc...)
|
||||
|
||||
## The `getContents` function
|
||||
|
||||
This function uses [cURL](https://secure.php.net/manual/en/book.curl.php) to acquire data from the specified URI while respecting the various settings defined at a global level by RSS-Bridge (i.e., proxy host, user agent, etc.). This function accepts a few parameters:
|
||||
|
||||
| Parameter | Type | Optional | Description
|
||||
| --------- | ------ | ---------- | ----------
|
||||
| `url` | string | *required* | The URL of the contents to acquire
|
||||
| `header` | array | *optional* | An array of HTTP header fields to set, in the format `array('Content-type: text/plain', 'Content-length: 100')`, see [CURLOPT_HTTPHEADER](https://secure.php.net/manual/en/function.curl-setopt.php)
|
||||
| `opts` | array | *optional* | An array of cURL options in the format `array(CURLOPT_POST => 1);`, see [curl_setopt](https://secure.php.net/manual/en/function.curl-setopt.php) for a complete list of options.
|
||||
|
||||
```PHP
|
||||
$header = array('Content-type:text/plain', 'Content-length: 100');
|
||||
$opts = array(CURLOPT_POST => 1);
|
||||
$html = getContents($url, $header, $opts);
|
||||
```
|
||||
|
||||
## The `getSimpleHTMLDOM` function
|
||||
|
||||
This function is a wrapper around the [simple_html_dom](http://simplehtmldom.sourceforge.net/) [file_get_html](http://simplehtmldom.sourceforge.net/manual_api.htm#api) function in order to provide context by design.
|
||||
|
||||
```PHP
|
||||
$html = getSimpleHTMLDOM('your URI');
|
||||
```
|
||||
|
||||
## The `getSimpleHTMLDOMCached` function
|
||||
|
||||
This function does the same as the [`getSimpleHTMLDOM`](#the-getsimplehtmldom-function) function, except that the content received for the given URI is stored in a cache and loaded from cache on the next request if the specified cache duration was not reached. Use this function for data that is very unlikely to change between consecutive requests to **RSS-Bridge**. This function allows to specify the cache duration with the second parameter (default is 24 hours / 86400 seconds).
|
||||
|
||||
```PHP
|
||||
$html = getSimpleHTMLDOMCached('your URI', 86400); // Duration 24h
|
||||
```
|
||||
|
||||
**Notice:** Due to the current implementation a value greater than 86400 seconds (24 hours) will not work as the cache is purged every 24 hours automatically.
|
||||
|
||||
# Template
|
||||
|
||||
This is the minimum template for a new bridge:
|
||||
|
||||
Reference in New Issue
Block a user