Rss-Bridge/lib/BridgeInterface.php
Roliga 49da67cb33 core: Automatically select a bridge based on a URL (#928)
* core: Add bridge parameter auto detection

This adds a new 'detect' action which accepts a URL from which an
appropriate bridge is selected and relevant parameters are extracted.
The user is then automatically redirected to the selected bridge.

For example to get a feed from: https://twitter.com/search?q=%23rss-bridge
we could send a request to:
'/?action=detect&format=Atom&url=twitter.com/search%3Fq%3D%2523rss-bridge'
which would redirect to:
'/?action=display&q=%23rss-bridge&bridge=Twitter&format=Atom'.

This auto detection happens on a per-bridge basis, so a new function
'detectParameters' is added to BridgeInterface which bridges may implement.
It takes a URL for an argument and returns a list of parameters that were
extracted, or null if the URL isn't relevant for the bridge.

* [TwitterBridge] Add parameter auto detection

* [BridgeAbstract] Add generic parameter detection

This adds generic "paramater detection" for bridges that don't have any
parameters defined. If the queried URL matches the URI defined in the
bridge (ignoring https://, www. and trailing /) an emtpy list of parameters is
returned.
2018-11-26 18:05:40 +01:00

125 lines
2.9 KiB
PHP

<?php
/**
* This file is part of RSS-Bridge, a PHP project capable of generating RSS and
* Atom feeds for websites that don't have one.
*
* For the full license information, please view the UNLICENSE file distributed
* with this source code.
*
* @package Core
* @license http://unlicense.org/ UNLICENSE
* @link https://github.com/rss-bridge/rss-bridge
*/
/**
* The bridge interface
*
* A bridge is a class that is responsible for collecting and transforming data
* from one hosting provider into an internal representation of feed data, that
* can later be transformed into different feed formats (see {@see FormatInterface}).
*
* For this purpose, all bridges need to perform three common operations:
*
* 1. Collect data from a remote site.
* 2. Extract the required contents.
* 3. Add the contents to the internal data structure.
*
* Bridges can optionally specify parameters to customize bridge behavior based
* on user input. For example, a user could specify how many items to return in
* the feed and where to get them.
*
* In order to present a bridge on the home page, and for the purpose of bridge
* specific behaviour, additional information must be provided by the bridge:
*
* * **Name**
* The name of the bridge that can be displayed to users.
*
* * **Description**
* A brief description for the bridge that can be displayed to users.
*
* * **URI**
* A link to the hosting provider.
*
* * **Maintainer**
* The GitHub username of the bridge maintainer
*
* * **Parameters**
* A list of parameters for customization
*
* * **Icon**
* A link to the favicon of the hosting provider
*
* * **Cache timeout**
* The default cache timeout for the bridge.
*/
interface BridgeInterface {
/**
* Collects data from the site
*/
public function collectData();
/**
* Returns the description
*
* @return string Description
*/
public function getDescription();
/**
* Returns an array of collected items
*
* @return array Associative array of items
*/
public function getItems();
/**
* Returns the bridge maintainer
*
* @return string Bridge maintainer
*/
public function getMaintainer();
/**
* Returns the bridge name
*
* @return string Bridge name
*/
public function getName();
/**
* Returns the bridge icon
*
* @return string Bridge icon
*/
public function getIcon();
/**
* Returns the bridge parameters
*
* @return array Bridge parameters
*/
public function getParameters();
/**
* Returns the bridge URI
*
* @return string Bridge URI
*/
public function getURI();
/**
* Returns the cache timeout
*
* @return int Cache timeout
*/
public function getCacheTimeout();
/**
* Returns parameters from given URL or null if URL is not applicable
*
* @param string $url URL to extract parameters from
* @return array|null List of bridge parameters or null if detection failed.
*/
public function detectParameters($url);
}