mirror of https://github.com/danoloan10/rss-bridge
[Documentation] Move all wiki pages into the repo and make it pretty (#2494)
This commit is contained in:
Bocki
GitHub
parent
16470e8119
commit
76f5de3d0f
|
|
@ -0,0 +1,27 @@
|
|||
name: Documentation
|
||||
|
||||
on:
|
||||
push:
|
||||
paths:
|
||||
- 'docs/**'
|
||||
|
||||
jobs:
|
||||
documentation:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Setup PHP
|
||||
uses: shivammathur/setup-php@2.17.1
|
||||
with:
|
||||
php-version: 8.0
|
||||
- name: Install dependencies
|
||||
run: composer global require daux/daux.io
|
||||
- name: Generate documentation
|
||||
run: daux generate
|
||||
- name: Deploy same repository 🚀
|
||||
uses: JamesIves/github-pages-deploy-action@v4.2.5
|
||||
with:
|
||||
folder: "static"
|
||||
branch: gh-pages
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
**RSS-Bridge** aims at sites that:
|
||||
|
||||
- don't provide public accessible Atom or RSS feeds
|
||||
- force their users to subscribe to e-mail notifications
|
||||
- force their users to use their own proprietary APIs
|
||||
- require their users to come back on a regular basis in order to check for new content
|
||||
|
||||
**RSS-Bridge** will generate feeds based on "bridges" that are developed for any site. Those bridges will collect data and extract all necessary information which is then converted into various feed formats like Atom or RSS.
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
There are many things you can do to contribute to **RSS-Bridge** as developer or as user without any knowledge in PHP or (web) development. Here are a few things:
|
||||
|
||||
- Share **RSS-Bridge** with your friends (Twitter, Facebook, ..._you name it_...)
|
||||
- Report broken bridges or bugs [here](https://github.com/RSS-Bridge/rss-bridge/issues)
|
||||
- Request new features or propose ideas (via [Issues](https://github.com/RSS-Bridge/rss-bridge/issues))
|
||||
- Discuss bugs, features, ideas or [issues](https://github.com/RSS-Bridge/rss-bridge/issues)
|
||||
- Add new bridges or improve the API
|
||||
- Improve this documentation
|
||||
- Host **RSS-Bridge**
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
**RSS-Bridge** requires either of the following:
|
||||
|
||||
## A Web server* with:
|
||||
|
||||
- PHP 7.1 (or higher)
|
||||
- [`openssl`](https://secure.php.net/manual/en/book.openssl.php) extension
|
||||
- [`libxml`](https://secure.php.net/manual/en/book.libxml.php) extension (enabled by default, see [PHP Manual](http://php.net/manual/en/libxml.installation.php))
|
||||
- [`mbstring`](https://secure.php.net/manual/en/book.mbstring.php) extension
|
||||
- [`simplexml`](https://secure.php.net/manual/en/book.simplexml.php) extension
|
||||
- [`curl`](https://secure.php.net/manual/en/book.curl.php) extension
|
||||
- [`json`](https://secure.php.net/manual/en/book.json.php) extension
|
||||
- [`filter`](https://secure.php.net/manual/en/book.filter.php) extension
|
||||
- [`sqlite3`](http://php.net/manual/en/book.sqlite3.php) extension (only when using SQLiteCache)
|
||||
|
||||
Enable extensions by un-commenting the corresponding line in your PHP configuration (`php.ini`).
|
||||
|
||||
|
||||
## A Linux server with:
|
||||
|
||||
- Docker server configured (Any recent version should do)
|
||||
- 100MB of disk space
|
||||
|
||||
To setup RSS Bridge using Docker, see the [Docker Guide](../03_For_Hosts/03_Docker_Installation.md) on installing RSS Bridge.
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
## Welcome screen:
|
||||
|
||||
|
||||
## rss-bridge hashtag (#rss-bridge) search on Twitter:
|
||||
_in Atom format (as displayed by Firefox)_
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
This page provides a collection of frequently asked questions and their answers. Please check this page before opening a new Issue :revolving_hearts:
|
||||
|
||||
* [Why doesn't my bridge show new contents?](#why-doesnt-my-bridge-show-new-contents)
|
||||
* [How can I make a bridge update more frequently?](#how-can-i-make-a-bridge-update-more-frequently)
|
||||
* [Firefox doesn't show feeds anymore, what can I do?](#firefox-doesnt-show-feeds-anymore-what-can-i-do)
|
||||
|
||||
## Why doesn't my bridge show new contents?
|
||||
|
||||
RSS-Bridge creates a cached version of your feed in order to reduce traffic and respond faster. The cached version is created on the first request and served for all subsequent requests. On every request RSS-Bridge checks if the cache timeout has elapsed. If the timeout has elapsed, it loads new contents and updates the cached version.
|
||||
|
||||
_Notice_: RSS-Bridge only updates feeds if you actively request it, for example by pressing F5 in your browser or using a feed reader.
|
||||
|
||||
The cache duration is bridge specific and can last anywhere between five minutes and 24 hours. You can specify a custom cache timeout for each bridge if [this option](#how-can-i-make-a-bridge-update-more-frequently) has been enabled on the server.
|
||||
|
||||
## How can I make a bridge update more frequently?
|
||||
|
||||
You can only do that if you are hosting the RSS-Bridge instance:
|
||||
- Enable [`custom_timeout`](../03_For_Hosts/08_Custom_Configuration.md#customtimeout)
|
||||
- Alternatively, change the default timeout for your bridge by modifying the `CACHE_TIMEOUT` constant in the relevant bridge file (e.g [here](https://github.com/RSS-Bridge/rss-bridge/blob/master/bridges/FilterBridge.php#L7) for the Filter Bridge).
|
||||
|
||||
## Firefox doesn't show feeds anymore, what can I do?
|
||||
|
||||
As of version 64, Firefox removed support for viewing Atom and RSS feeds in the browser. This results in the browser downloading the pages instead of showing contents.
|
||||
|
||||
Further reading:
|
||||
- https://support.mozilla.org/en-US/kb/feed-reader-replacements-firefox
|
||||
- https://bugzilla.mozilla.org/show_bug.cgi?id=1477667
|
||||
|
||||
To restore the original behavior in Firefox 64 or higher you can use following Add-on which attempts to recreate the original behavior (with some sugar on top):
|
||||
- https://addons.mozilla.org/en-US/firefox/addon/rsspreview/
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
| Flag | Host | Status | Contact | Comment |
|
||||
|:-----------------------------------------------------:|----------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|--------------------------------------------------|----------------------------------------------------------------------------|
|
||||
|  |  [rss-bridge.bb8.fun](https://rss-bridge.bb8.fun) |  | [@captn3m0](https://github.com/captn3m0) | Hosted in Bengaluru, India |
|
||||
|  |  [feed.eugenemolotov.ru](https://feed.eugenemolotov.ru) |  | [@em92](https://github.com/em92) | Hosted in Amsterdam, Netherlands |
|
||||
|  |  [bridge.suumitsu.eu](https://bridge.suumitsu.eu/) |  | [@mitsukarenai](https://github.com/mitsukarenai) | Hosted in Paris, France |
|
||||
|  |  [sebsauvage.net/rss-bridge](https://sebsauvage.net/rss-bridge/) |  | [@sebsauvage](https://github.com/sebsauvage/) | Hosted in France |
|
||||
|  |  [rss-bridge.snopyta.org](https://rss-bridge.snopyta.org) |  | [@Perflyst](https://github.com/Perflyst) | Hosted in Helsinki, Finland |
|
||||
|  |  [rss.nixnet.xyz](https://rss.nixnet.xyz/) |  | [@amolith](https://nixnet.xyz/contact) | Hosted in Wunstorf, Germany |
|
||||
|  |  [myrss4fun.xyz](https://myrss4fun.xyz) | | [@mrcoding](https://github.com/mrcoding/) | Latest GitHub Release |
|
||||
|  |  [bridge.easter.fr](https://bridge.easter.fr/) |  | [@chatainsim](https://github.com/chatainsim) | Hosted in Roubaix, France |
|
||||
|  |  [wtf.roflcopter.fr/rss-bridge](https://wtf.roflcopter.fr/rss-bridge/) |  | [roflcopter.fr](https://wtf.roflcopter.fr/) | Hosted in France |
|
||||
|  |  [rssbridge.fossdaily.xyz](https://rssbridge.fossdaily.xyz) |  | | Hosted in Vilnius, Lithuania |
|
||||
|  | https://rss-bridge.ggc-project.de |  | [@ggc-project.de](https://social.dev-wiki.de/@ggc_project) | Hosted in Steyr, Austria |
|
||||
|  | https://bridge.noisebridge.info |  | [Discuss Forum](https://discuss.noisebridge.info) | Hosted in United States |
|
||||
|  |  [feeds.proxeuse.com](https://feeds.proxeuse.com/) |  | [Proxeuse](https://www.proxeuse.com/en/contact-us) | Hosted in Germany |
|
||||
|  |  [ololbu.ru/rss-bridge/](https://ololbu.ru/rss-bridge) |  | [@Ololbu](https://github.com/Ololbu) | Hosted in Moscow, Russia |
|
||||
|  |  [tools.bheil.net/rss-bridge/](https://tools.bheil.net/rss-bridge/) |  | [@bheil](https://www.bheil.net) | Hosted in Germany |
|
||||
|  |  [rss-bridge.mediani.de](https://rss-bridge.mediani.de/) |  | [@sokai](https://github.com/sokai) | Hosted with Netcup, Germany |
|
||||
|  |  [rssbridge.boldair.dev](https://rssbridge.boldair.dev/) |  | [@Boldairdev](https://github.com/Boldairdev) | Latest Github release, Hosted on PHP 8.0 in Roubaix, France |
|
||||
|  |  [rss-bridge.esmailelbob.xyz](https://rss-bridge.esmailelbob.xyz/) | | [@esmaiellbobdev2](https://github.com/esmailelbobve2/) | Latest GitHub Release |
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
RSS-Bridge supports calls via CLI. You can use the same parameters as you would normally use via the URI. Example:
|
||||
|
||||
`php index.php action=display bridge=DansTonChat format=Json`
|
||||
|
||||
## Required parameters
|
||||
|
||||
RSS-Bridge requires a few parameters that must be specified on every call. Omitting these parameters will result in error messages:
|
||||
|
||||
### action
|
||||
|
||||
Defines how RSS-Bridge responds to the request.
|
||||
|
||||
Value | Description
|
||||
----- | -----------
|
||||
`action=list` | Returns a JSON formatted list of bridges. Other parameters are ignored.
|
||||
`action=display` | Returns (displays) a feed.
|
||||
|
||||
### bridge
|
||||
|
||||
This parameter specifies the name of the bridge RSS-Bridge should return feeds from. The name of the bridge equals the class name of the bridges in the ./bridges/ folder without the 'Bridge' prefix. For example: DansTonChatBridge => DansTonChat.
|
||||
|
||||
### format
|
||||
|
||||
This parameter specifies the format in which RSS-Bridge returns the contents. RSS-Bridge currently supports five formats: `Atom`, `Html`, `Json`, `Mrss`and `Plaintext`.
|
||||
|
||||
## Optional parameters
|
||||
|
||||
RSS-Bridge supports optional parameters. These parameters are only valid if the options have been enabled in the index.php script.
|
||||
|
||||
### _noproxy
|
||||
|
||||
This parameter is only available if a proxy server has been specified via `PROXY_URL` and 'PROXY_BYBRIDGE' has been enabled. This is a Boolean parameter that can be set to '1' (true) or '0' (false).
|
||||
|
||||
## Bridge parameters
|
||||
|
||||
Each bridge can specify its own set of parameters. As in the example above, some bridges don't specify any parameters or only optional parameters that can be neglected. For more details read the `PARAMETERS` definition for your bridge.
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
In order to install RSS-Bridge on your own web server* do as follows:
|
||||
|
||||
* Make sure your web server meets all [requirements](../01_General/03_Requirements.md)
|
||||
* Download the ZIP file of the [last stable release](https://github.com/RSS-Bridge/rss-bridge/releases)
|
||||
* Place all files on your web server
|
||||
|
||||
For linux hosts:
|
||||
* Grant read-write-access for `www-data` to the `./cache` directory (`chown -R www-data ./cache`)
|
||||
|
||||
You have successfully installed RSS-Bridge.
|
||||
|
||||
Instructions for Docker setups are at [Docker Installation](../03_For_Hosts/03_Docker_Installation.md)
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
Updating an existing installation is very simple, depending on your type of installation.
|
||||
|
||||
## Release Build
|
||||
|
||||
* Download latest version
|
||||
* Extract all files
|
||||
* Replace existing files
|
||||
|
||||
This will update all core files to the latest version. Your custom configuration and bridges are left untouched. Keep in mind that changes to any core file of RSS-Bridge will be replaced.
|
||||
|
||||
## Docker
|
||||
|
||||
Simply get the latest Docker build via `:latest` or specific builds via `:<tag-name>`.
|
||||
|
||||
## Heroku
|
||||
|
||||
### If you didn't fork the repo before
|
||||
|
||||
Fork the repo by clicking the `Fork` button at the top right of this page (must be on desktop site). Then on your Heroku account, go to the application. Click on the `Deploy` tab and connect the repo named `yourusername/rss-bridge`. Do a manual deploy of the `master` branch.
|
||||
|
||||
### If you forked the repo before
|
||||
|
||||
[Click here to create a new pull request to your fork](https://github.com/RSS-Bridge/rss-bridge/pull/new/master). Select `compare across forks`, make the base repository `yourusername/rss-bridge` and ensure the branch is set to master. Put any title you want and create the pull request. On the page that comes after this, merge the pull request.
|
||||
|
||||
You then want to go to your application in Heroku, connect your fork via the `Deploy` tab and deploy the `master` branch.
|
||||
|
||||
You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future.
|
||||
|
||||
## Git
|
||||
|
||||
To get the latest changes from the master branch
|
||||
|
||||
```
|
||||
git pull
|
||||
```
|
||||
|
||||
To use a specific tag
|
||||
|
||||
```
|
||||
git fetch --all
|
||||
git checkout tags/<tag-name>
|
||||
```
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
This guide is for people who want to run RSS Bridge using Docker. If you want to run it a simple PHP Webhost environment, see [Installation](../03_For_Hosts/01_Installation.md) instead.
|
||||
|
||||
## Setup
|
||||
|
||||
### Create the container
|
||||
|
||||
```bash
|
||||
docker create \
|
||||
--name=rss-bridge \
|
||||
--volume </local/custom/path>:/config \
|
||||
--publish 3000:80 \
|
||||
rssbridge/rss-bridge:latest
|
||||
```
|
||||
### Run it
|
||||
```bash
|
||||
docker start rss-bridge
|
||||
```
|
||||
|
||||
And access it using `http://IP_Address:3000`. If you'd like to run a specific version, you can run it by:
|
||||
|
||||
```bash
|
||||
docker create \
|
||||
--name=rss-bridge \
|
||||
--volume </local/custom/path>:/config \
|
||||
--publish 3000:80 \
|
||||
rssbridge/rss-bridge:$version
|
||||
```
|
||||
|
||||
Where you can get the versions published to Docker Hub at https://hub.docker.com/r/rssbridge/rss-bridge/tags/. The server runs on port 80 internally, and you can publish it on a different port (change 3000 to your choice).
|
||||
|
||||
You can run it using a `docker-compose.yml` as well:
|
||||
|
||||
```yml
|
||||
version: '2'
|
||||
services:
|
||||
rss-bridge:
|
||||
image: rssbridge/rss-bridge:latest
|
||||
volumes:
|
||||
- </local/custom/path>:/config
|
||||
ports:
|
||||
- 3000:80
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
# Container access and information
|
||||
|
||||
|Function|Command|
|
||||
|----|----|
|
||||
|Shell access (live container)|`docker exec -it rss-bridge /bin/sh`|
|
||||
|Realtime container logs|`docker logs -f rss-bridge`|
|
||||
|
||||
# Adding custom bridges and configurations
|
||||
If you want to add a bridge that is not part of [`/bridges`](https://github.com/RSS-Bridge/rss-bridge/tree/master/bridges), you can specify an additional folder to copy necessary files to the `rss-bridge` container.
|
||||
|
||||
_Here **root** is folder where `docker-compose.yml` resides._
|
||||
1. Create `custom` folder in root.
|
||||
2. Copy your [bridges files](../05_Bridge_API/01_How_to_create_a_new_bridge.md) to the `custom` folder. You can also add your custom [whitelist.txt](../03_For_Hosts/05_Whitelisting.md) file and your custom [config.ini.php](../03_For_Hosts/08_Custom_Configuration.md) to this folder.
|
||||
3. Run `docker-compose up` to recreate service.
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
This guide is for people who want to run RSS Bridge on [Heroku](https://heroku.com).
|
||||
|
||||
You can run it on Heroku for free, however make sure your RSS reader interval is not set to a fast rate, otherwise your Heroku hours will use up quicker. Heroku puts the app to sleep after 30 mins of no activity. When the app is asleep no Heroku hours are used. So choose an interval that won't make the app exceed the limit!
|
||||
|
||||
You can increase your Heroku hours to 1000 a month from 550 a month by simply verifying your account with a credit card.
|
||||
|
||||
## Deploy button
|
||||
You can simply press the button below to easily deploy RSS Bridge on Heroku and use the default bridges. Or you can follow the manual instructions given below.
|
||||
|
||||
[](https://heroku.com/deploy?template=https://github.com/RSS-Bridge/rss-bridge)
|
||||
|
||||
## Manual deploy
|
||||
1. Fork this repo by clicking the Fork button at the top right of this page (only on desktop site)
|
||||
|
||||
|
||||
|
||||
2. To customise what bridges can be used if need, create a `whitelist.txt` file in your fork and follow the instructions given [here](../03_For_Hosts/05_Whitelisting.md). You don’t need to do this if you’re fine with the default bridges.
|
||||
|
||||
3. [Log in to Heroku](https://dashboard.heroku.com) and create a new app. The app name will be the URL of the RSS Bridge (appname.herokuapp.com)
|
||||
|
||||
4. Go to Deploy, select the GitHub option and connect your GitHub account. Search for the repo named `yourusername/rss-bridge`
|
||||
|
||||
|
||||
|
||||
5. Deploy the master branch.
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
RSS-Bridge supports whitelists in order to limit the available bridges on your web server.
|
||||
|
||||
A default whitelist file (`whitelist.default.txt`) is shipped with RSS-Bridge. Please do not edit this file, as it gets replaced when upgrading RSS-Bridge!
|
||||
|
||||
You should, however, use this file as template to create your own whitelist (or leave it as is, to keep the default bridges). In order to create your own whitelist perform following actions:
|
||||
|
||||
* Copy the file `whitelist.default.txt` in the RSS-Bridge root folder
|
||||
* Rename the new file to `whitelist.txt`
|
||||
* Change the lines to satisfy your requirements
|
||||
|
||||
RSS-Bridge will automatically detect the `whitelist.txt` and use it. If the file doesn't exist it will default to `whitelist.default.txt` automatically.
|
||||
|
||||
# Specific whitelisting
|
||||
|
||||
In order to specifically whitelist bridges, open `whitelist.txt` and add one line for each bridge you want to show. Make sure you use normal [line-feeds](https://en.wikipedia.org/wiki/Newline "Line-feed") at the end of a line (LF not [CRLF](https://en.wikipedia.org/wiki/Carriage_return "Carriage-return line-feed")). The bridge name must match the filename of the bridge in the bridges folder (see [folder structure](../04_For_Developers/03_Folder_structure.md)). The name may or may not include the 'Bridge' part.
|
||||
|
||||
**Examples**:
|
||||
```TEXT
|
||||
FacebookBridge
|
||||
WikipediaBridge
|
||||
TwitterBridge
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```TEXT
|
||||
Facebook
|
||||
Wikipedia
|
||||
Twitter
|
||||
```
|
||||
|
||||
# Global whitelisting
|
||||
|
||||
In order to globally whitelist all bridges, open the `whitelist.txt` file, remove all contents and just write an asterisk `*` into the file (only this one character).
|
||||
|
||||
```TEXT
|
||||
*
|
||||
```
|
||||
|
|
@ -0,0 +1,101 @@
|
|||
Depending on your servers abilities you can choose between two types of authentication:
|
||||
|
||||
* [.htaccess](#htaccess)
|
||||
* [RSS-Bridge Authentication](#rss-bridge-authentication)
|
||||
|
||||
**General advice**:
|
||||
|
||||
- Make sure to use a strong password, no matter which solution you choose!
|
||||
- Enable HTTPS on your server to ensure your connection is encrypted and secure!
|
||||
|
||||
## .htaccess
|
||||
|
||||
.htaccess files are commonly used to restrict access to files on a web server. One of the features of .htaccess files is the ability to password protect specific (or all) directories. If setup correctly, a password is required to access the files.
|
||||
|
||||
The usage of .htaccess files requires three basic steps:
|
||||
|
||||
1) [Enable .htaccess](#enable-htaccess)
|
||||
2) [Create a .htpasswd file](#create-a-htpasswd-file)
|
||||
3) [Create a .htaccess file](#create-a-htaccess-file)
|
||||
|
||||
### Enable .htaccess
|
||||
|
||||
This process depends on the server you are using. Some providers may require you to change some settings, or place/change some file. Here are some helpful links for your server (please add your own if missing :sparkling_heart:)
|
||||
|
||||
- Apache: http://ask.xmodulo.com/enable-htaccess-apache.html
|
||||
|
||||
### Create a .htpasswd file
|
||||
|
||||
The `.htpasswd` file contains the user name and password used for login to your web server. Please notice that the password is stored in encrypted form, which requires you to encrypt your password before creating the `.htpasswd` file!
|
||||
|
||||
Here are three ways of creating your own `.htpasswd` file:
|
||||
|
||||
**1) Example file**
|
||||
|
||||
Example `.htpasswd` file (user name: "test", password: "test"):
|
||||
|
||||
```.htpasswd
|
||||
test:$apr1$a52u9ILP$XTNG8qMJiEXSm1zD0lQcR0
|
||||
```
|
||||
|
||||
Just copy and paste the contents to your `.htpasswd` file.
|
||||
|
||||
**2) Online generator (read warning!)**
|
||||
|
||||
You can create your own `.htpasswd` file online using a `.htpasswd` generator like this: https://www.htaccesstools.com/htpasswd-generator/
|
||||
|
||||
**WARNING!**
|
||||
- Never insert real passwords to an online generator!
|
||||
|
||||
**3) Generate your own password**
|
||||
|
||||
Another way to create your own `.htpasswd` file is to run this script on your server (it'll output the data for you, you just have to paste it int a `.htpasswd` file):
|
||||
|
||||
```PHP
|
||||
<?php
|
||||
// Password to be encrypted for a .htpasswd file
|
||||
$clearTextPassword = 'some password';
|
||||
|
||||
// Encrypt password
|
||||
$password = crypt($clearTextPassword, base64_encode($clearTextPassword));
|
||||
|
||||
// Print encrypted password
|
||||
echo $password;
|
||||
?>
|
||||
```
|
||||
|
||||
>source: https://www.htaccesstools.com/articles/create-password-for-htpasswd-file-using-php/
|
||||
|
||||
### Create a .htaccess file
|
||||
|
||||
The `.htaccess` file is used to specify which directories are password protected. For that purpose you should place the file in whatever directory you want to restrict access. If you want to restrict access to RSS-Bridge in general, you should place the file in the root directory (where `index.php` is located).
|
||||
|
||||
Two parameters must be specified in the `.htaccess` file:
|
||||
|
||||
* AuthName
|
||||
* AuthUserFile
|
||||
|
||||
`AuthName` specifies the name of the authentication (i.e. "RSS-Bridge"). `AuthUserFile` defines the **absolute** path to a `.htpasswd` file.
|
||||
|
||||
Here are two ways of creating your own `.htaccess` file:
|
||||
|
||||
**1) Example file**
|
||||
|
||||
```.htaccess
|
||||
AuthType Basic
|
||||
AuthName "My Protected Area"
|
||||
AuthUserFile /path/to/.htpasswd
|
||||
Require valid-user
|
||||
```
|
||||
|
||||
Notice: You must change the `AuthUserFile` location to fit your own server (i.e. `/var/www/html/rss-bridge/.htpasswd`)
|
||||
|
||||
**2) Online generator**
|
||||
|
||||
You can use an online generator to create the file for you and copy-paste it to your `.htaccess` file: https://www.htaccesstools.com/htaccess-authentication/
|
||||
|
||||
## RSS-Bridge Authentication
|
||||
|
||||
RSS-Bridge ships with an authentication module designed for single user environments. You can enable authentication and specify the username & password in the [configuration file](../03_For_Hosts/08_Custom_Configuration.md#authentication).
|
||||
|
||||
Please notice that the password is stored in plain text and thus is readable to anyone who can access the file. Make sure to restrict access to the file, so that it cannot be read remotely!
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
RSS-Bridge ships a few options the host may or may not activate. All options are currently defined in the [index.php](https://github.com/RSS-Bridge/rss-bridge/blob/master/index.php) file. This means they'll be reset after upgrading RSS-Bridge!
|
||||
|
||||
## Customizable cache timeout
|
||||
|
||||
Sometimes it is necessary to specify custom timeouts to update contents more frequently than the bridge maintainer intended. In these cases the client may specify a custom cache timeout to prevent loading contents from cache earlier (or later).
|
||||
|
||||
This option can be activated by setting the `CUSTOM_CACHE_TIMEOUT` to `true`. When enabled each bridge receives an additional parameter `Cache timeout in seconds` that can be set to any value between 1 and 86400 (24 hours). If the value is not within the limits the default settings apply (as specified by the bridge maintainer).
|
||||
|
||||
The cache timeout is send to RSS-Bridge using the `_cache_timeout` parameter. RSS-Bridge will return an error message if the parameter is received and the option is disabled.
|
||||
|
|
@ -0,0 +1,164 @@
|
|||
RSS-Bridge supports custom configurations for common parameters on the server side!
|
||||
|
||||
A default configuration file (`config.default.ini.php`) is shipped with RSS-Bridge. Please do not edit this file, as it gets replaced when upgrading RSS-Bridge!
|
||||
|
||||
You should, however, use this file as template to create your own configuration (or leave it as is, to keep the default settings). In order to create your own configuration perform following actions:
|
||||
|
||||
* Create the file `config.ini.php` in the RSS-Bridge root folder (next to `config.default.ini.php`)
|
||||
* Copy the contents from `config.default.ini.php` to your configuration file
|
||||
* Change the parameters to satisfy your requirements
|
||||
|
||||
RSS-Bridge will automatically detect the `config.ini.php` and use it. If the file doesn't exist it will default to `config.default.ini.php` automatically.
|
||||
|
||||
__Notice__: If a parameter is not specified in your `config.ini.php` RSS-Bridge will automatically use the default settings from `config.default.ini.php`.
|
||||
|
||||
# Available parameters
|
||||
|
||||
The configuration file is split into sections:
|
||||
|
||||
* [system](#system)
|
||||
* [cache](#cache)
|
||||
* [proxy](#proxy)
|
||||
* [authentication](#authentication)
|
||||
* [admin](#admin)
|
||||
* [error](#error)
|
||||
|
||||
_System_: This section specifies system specific parameters
|
||||
|
||||
_Cache_: This section is all about the caching behavior of RSS-Bridge
|
||||
|
||||
_Proxy_: This section can be used to specify a proxy server for RSS-Bridge to utilize for fetching contents
|
||||
|
||||
_Authentication_: This section defines parameters to require authentication to use RSS-Bridge
|
||||
|
||||
_Admin_: This section specifies parameters related to the administrator of your instance of RSS-Bridge
|
||||
|
||||
## System
|
||||
|
||||
This section provides following parameters:
|
||||
|
||||
- [timezone](#timezone)
|
||||
|
||||
### Timezone
|
||||
|
||||
Defines the timezone used by RSS-Bridge. This parameter can be set to any value of the values defined at https://www.php.net/manual/en/timezones.php
|
||||
|
||||
The default value is `UTC`.
|
||||
|
||||
## Cache
|
||||
|
||||
This section provides following parameters:
|
||||
|
||||
- [type](#type)
|
||||
- [custom_timeout](#custom_timeout)
|
||||
|
||||
### type
|
||||
|
||||
Defines the cache type used by RSS-Bridge.
|
||||
|
||||
| Type | Description
|
||||
| ------- | -----------
|
||||
|`file` | File based (default)
|
||||
|`sqlite` | SQLite database
|
||||
|`memcached` | Memcached service
|
||||
|
||||
### custom_timeout
|
||||
|
||||
Allow users to specify custom timeout for specific requests.
|
||||
|
||||
`true` = enabled
|
||||
|
||||
`false` = disabled (default)
|
||||
|
||||
## Proxy
|
||||
|
||||
This section provides following parameters:
|
||||
|
||||
- [url](#url)
|
||||
- [name](#name)
|
||||
- [by_bridge](#by_bridge)
|
||||
|
||||
### url
|
||||
|
||||
Sets the proxy url (i.e. "tcp://192.168.0.0:32")
|
||||
|
||||
`""` = Proxy disabled (default)
|
||||
|
||||
### name
|
||||
|
||||
Sets the proxy name that is shown on the bridge instead of the proxy url.
|
||||
|
||||
`""` = Show proxy url (default: "Hidden proxy name")
|
||||
|
||||
### by_bridge
|
||||
|
||||
Allow users to disable proxy usage for specific requests.
|
||||
|
||||
`true` = enabled
|
||||
|
||||
`false` = disabled (default)
|
||||
|
||||
## Authentication
|
||||
|
||||
This section provides following parameters:
|
||||
|
||||
- [enable](#enable)
|
||||
- [username](#username)
|
||||
- [password](#password)
|
||||
|
||||
### enable
|
||||
|
||||
Enables authentication for RSS-Bridge.
|
||||
|
||||
_Notice_: Login is required for all requests when enabled! Make sure to update feed subscriptions accordingly.
|
||||
|
||||
`true` = enabled
|
||||
|
||||
`false` = disabled (default)
|
||||
|
||||
### username
|
||||
|
||||
Defines the user name used for login.
|
||||
|
||||
### password
|
||||
|
||||
Defines the password used for login. Use a strong password to prevent others from guessing your login!
|
||||
|
||||
## Admin
|
||||
|
||||
This section provides following parameters:
|
||||
|
||||
- [email](#email)
|
||||
|
||||
### email
|
||||
|
||||
Advertises an email address where people can reach the administrator.
|
||||
|
||||
*Notice*: This address is displayed on the main page, visible to everyone!
|
||||
|
||||
`""` = Disabled (default)
|
||||
|
||||
Example: `email = "admin@instance.rss-bridge.com"`
|
||||
|
||||
## error
|
||||
|
||||
This section provides following parameters:
|
||||
|
||||
- [output](#output)
|
||||
- [report_limit](#report_limit)
|
||||
|
||||
### output
|
||||
|
||||
Defines how error messages are returned by RSS-Bridge
|
||||
|
||||
`feed`: As part of the feed (default)
|
||||
|
||||
`http`: As HTTP error message
|
||||
|
||||
`none`: No errors are reported
|
||||
|
||||
### report_limit
|
||||
|
||||
Defines how often an error must occur before it is reported to the user
|
||||
|
||||
`report_limit`: 1 (default)
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
This section is directed at **hosts** and **server administrators**.
|
||||
|
||||
To install RSS-Bridge, please follow the [installation instructions](../03_For_Hosts/01_Installation.md). You must have access to a web server with a working PHP environment!
|
||||
|
||||
RSS-Bridge comes with a large amount of bridges. Only few bridges are enabled by default. Unlock more bridges by adding them to the [whitelist](../03_For_Hosts/05_Whitelisting.md).
|
||||
|
||||
Some bridges could be implemented more efficiently by actually using proprietary APIs, but there are reasons against it:
|
||||
|
||||
- RSS-Bridge exists in the first place to NOT use APIs. See [the rant](https://github.com/RSS-Bridge/rss-bridge/blob/master/README.md#Rant)
|
||||
|
||||
- APIs require private keys that could be stored on servers running RSS-Bridge, which is a security concern, involves complex authorizations for inexperienced users and could cause harm (when using paid services for example). In a closed environment (a server only you use for yourself) however you might be interested in using them anyway. So, check [this](https://github.com/RSS-Bridge/rss-bridge/pull/478/files) possible implementation of an anti-captcha solution.
|
||||
|
|
@ -0,0 +1,766 @@
|
|||
This section explains the coding style policy for RSS-Bridge with examples and references to external resources. Please make sure your code is compliant before opening a pull request.
|
||||
|
||||
RSS-Bridge uses [Travis-CI](https://travis-ci.org/) to validate code quality. You will automatically be notified if issues were found in your pull request. You must fix those issues before the pull request will be merged. Refer to [phpcs.xml](https://github.com/RSS-Bridge/rss-bridge/blob/master/phpcs.xml) for a complete list of policies enforced by Travis-CI.
|
||||
|
||||
If you want to run the checks locally, make sure you have [`phpcs`](https://github.com/squizlabs/PHP_CodeSniffer) and [`phpunit`](https://phpunit.de/) installed on your machine and run following commands in the root directory of RSS-Bridge (tested on Debian):
|
||||
|
||||
```console
|
||||
phpcs . --standard=phpcs.xml --warning-severity=0 --extensions=php -p
|
||||
phpunit --configuration=phpunit.xml --include-path=lib/
|
||||
```
|
||||
|
||||
The following list provides an overview of all policies applied to RSS-Bridge.
|
||||
|
||||
# Whitespace
|
||||
|
||||
## Add a new line at the end of a file
|
||||
|
||||
Each PHP/CSS/HTML file must end with a new line at the end of a file.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
{
|
||||
// code here
|
||||
} // This is the end of the file
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
{
|
||||
// code here
|
||||
}
|
||||
// This is the end of the file
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`PSR2.Files.EndFileNewline`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PSR2/Sniffs/Files/EndFileNewlineSniff.php)
|
||||
|
||||
## Do not add a whitespace before a semicolon
|
||||
|
||||
A semicolon indicates the end of a line of code. Spaces before the semicolon is unnecessary and must be removed.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
echo 'Hello World!' ;
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
echo 'Hello World!';
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Squiz.WhiteSpace.SemicolonSpacing`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/WhiteSpace/SemicolonSpacingSniff.php)
|
||||
|
||||
## Do not add whitespace at start or end of a file or end of a line
|
||||
|
||||
Whitespace at the end of lines or at the start or end of a file is invisible to the reader and absolutely unnecessary. Thus it must be removed.
|
||||
|
||||
_Reference_: [`Squiz.WhiteSpace.SuperfluousWhitespace`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/WhiteSpace/SuperfluousWhitespaceSniff.php)
|
||||
|
||||
# Indentation
|
||||
## Use tabs for indentation
|
||||
|
||||
RSS-Bridge uses tabs for indentation on all PHP files in the repository (except files located in the `vendor` directory)
|
||||
|
||||
_Reference_: [`Generic.WhiteSpace.DisallowSpaceIndent`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/WhiteSpace/DisallowSpaceIndentSniff.php)
|
||||
|
||||
# Maximum Line Length
|
||||
|
||||
## The maximum line length should not exceed 80 characters
|
||||
|
||||
One line of code should have no more than **80 characters** (soft limit) and must never exceed **120 characters** (hard limit).
|
||||
|
||||
_Notice_: Travis-CI enforces the hard limit of 120 characters. Maintainers may ask you to indent lines longer than 80 characters before merging. This is generally done to keep the code as readable and maintainable as possible.
|
||||
|
||||
For long conditional statements, consider indenting the statement into multiple lines.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad** (the total length of the line is **94** characters)
|
||||
|
||||
```PHP
|
||||
if($time !== false && (time() - $duration < $time) && (!defined('DEBUG') || DEBUG !== true)) {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
**Good** (add line breaks)
|
||||
|
||||
```PHP
|
||||
if($time !== false
|
||||
&& (time() - $duration < $time)
|
||||
&& (!defined('DEBUG') || DEBUG !== true)) {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
For long text, either add line feeds, or make use of the [`heredoc`](http://php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc) syntax.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad** (the total length of the line is **340** characters - from [Lorem Ipsum](https://www.lipsum.com/feed/html))
|
||||
|
||||
```PHP
|
||||
$longtext = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse condimentum nec est eget posuere. Proin at sagittis risus. Fusce faucibus lectus leo, eu ornare velit tristique eu. Curabitur elementum facilisis ultricies. Praesent dictum fermentum lectus a rhoncus. Donec vitae justo metus. Sed molestie faucibus egestas.';
|
||||
```
|
||||
|
||||
**Good** (use `heredoc` syntax - this will add line-breaks)
|
||||
|
||||
```PHP
|
||||
$longtext = <<<EOD
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
|
||||
condimentum nec est eget posuere. Proin at sagittis risus. Fusce faucibus
|
||||
lectus leo, eu ornare velit tristique eu. Curabitur elementum facilisis
|
||||
ultricies. Praesent dictum fermentum lectus a rhoncus. Donec vitae justo metus.
|
||||
Sed molestie faucibus egestas.
|
||||
EOD;
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.Files.LineLength`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/Files/LineLengthSniff.php)
|
||||
|
||||
# Strings
|
||||
|
||||
## Whenever possible use single quote strings
|
||||
|
||||
PHP supports both single quote strings and double quote strings. For pure text you must use single quote strings for consistency. Double quote strings are only allowed for special characters (i.e. `"\n"`) or inlined variables (i.e. `"My name is {$name}"`);
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
echo "Hello World!";
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
echo 'Hello World!';
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Squiz.Strings.DoubleQuoteUsage`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/Strings/DoubleQuoteUsageSniff.php)
|
||||
|
||||
## Add spaces around the concatenation operator
|
||||
|
||||
The concatenation operator should have one space on both sides in order to improve readability.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$text = $greeting.' '.$name.'!';
|
||||
```
|
||||
|
||||
**Good** (add spaces)
|
||||
|
||||
```PHP
|
||||
$text = $greeting . ' ' . $name . '!';
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
You may break long lines into multiple lines using the concatenation operator. That way readability can improve considerable when combining lots of variables.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$text = $greeting.' '.$name.'!';
|
||||
```
|
||||
|
||||
**Good** (split into multiple lines)
|
||||
|
||||
```PHP
|
||||
$text = $greeting
|
||||
. ' '
|
||||
. $name
|
||||
. '!';
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Squiz.Strings.ConcatenationSpacing`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/Strings/ConcatenationSpacingSniff.php)
|
||||
|
||||
## Use a single string instead of concatenating
|
||||
|
||||
While concatenation is useful for combining variables with other variables or static text. It should not be used to combine two sets of static text. See also: [Maximum line length](#maximum-line-length)
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$text = 'This is' . 'a bad idea!';
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$text = 'This is a good idea!';
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.Strings.UnnecessaryStringConcat`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/Strings/UnnecessaryStringConcatSniff.php)
|
||||
|
||||
# Constants
|
||||
|
||||
## Use UPPERCASE for constants
|
||||
|
||||
As in most languages, constants should be written in UPPERCASE.
|
||||
|
||||
_Notice_: This does not apply to keywords!
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
const pi = 3.14;
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
const PI = 3.14;
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.NamingConventions.UpperCaseConstantName`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/NamingConventions/UpperCaseConstantNameSniff.php)
|
||||
|
||||
# Keywords
|
||||
## Use lowercase for `true`, `false` and `null`
|
||||
|
||||
`true`, `false` and `null` must be written in lower case letters.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
if($condition === TRUE && $error === FALSE) {
|
||||
return NULL;
|
||||
}
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
if($condition === true && $error === false) {
|
||||
return null;
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.PHP.LowerCaseConstant`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/PHP/LowerCaseConstantSniff.php)
|
||||
|
||||
# Operators
|
||||
## Operators must have a space around them
|
||||
|
||||
Operators must be readable and therefore should have spaces around them.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$text='Hello '.$name.'!';
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$text = 'Hello ' . $name . '!';
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Squiz.WhiteSpace.OperatorSpacing`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/WhiteSpace/OperatorSpacingSniff.php)
|
||||
|
||||
# Functions
|
||||
## Parameters with default values must appear last in functions
|
||||
|
||||
It is considered good practice to make parameters with default values last in function declarations.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
function showTitle($duration = 60000, $title) { ... }
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
function showTitle($title, $duration = 60000) { ... }
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`PEAR.Functions.ValidDefaultValue`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PEAR/Sniffs/Functions/ValidDefaultValueSniff.php)
|
||||
|
||||
## Calling functions
|
||||
|
||||
Function calls must follow a few rules in order to maintain readability throughout the project:
|
||||
|
||||
**Do not add whitespace before the opening parenthesis**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$result = my_function ($param);
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param);
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
**Do not add whitespace after the opening parenthesis**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$result = my_function( $param);
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param);
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
**Do not add a space before the closing parenthesis**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param );
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param);
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
**Do not add a space before a comma**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param1 ,$param2);
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param1, $param2);
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
**Add a space after a comma**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param1,$param2);
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$result = my_function($param1, $param2);
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.Functions.FunctionCallArgumentSpacing`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/Functions/FunctionCallArgumentSpacingSniff.php)
|
||||
|
||||
## Do not add spaces after opening or before closing bracket
|
||||
|
||||
Parenthesis must tightly enclose parameters.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
if( $condition ) { ... }
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
if($condition) { ... }
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`PSR2.ControlStructures.ControlStructureSpacing`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PSR2/Sniffs/ControlStructures/ControlStructureSpacingSniff.php)
|
||||
|
||||
# Structures
|
||||
## Structures must always be formatted as multi-line blocks
|
||||
|
||||
A structure should always be treated as if it contains a multi-line block.
|
||||
|
||||
**Add a space after closing parenthesis**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
if($condition){
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
if($condition) {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
**Add body into new line**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
if($condition){ ... }
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
if($condition) {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
**Close body in new line**
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
if($condition){
|
||||
... }
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
if($condition) {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Squiz.ControlStructures.ControlSignature`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/ControlStructures/ControlSignatureSniff.php)
|
||||
|
||||
# If-Statements
|
||||
## Use `elseif` instead of `else if`
|
||||
|
||||
For sake of consistency `else if` is considered bad practice.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
if($conditionA) {
|
||||
|
||||
} else if($conditionB) {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
if($conditionA) {
|
||||
|
||||
} elseif($conditionB) {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`PSR2.ControlStructures.ElseIfDeclaration`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PSR2/Sniffs/ControlStructures/ElseIfDeclarationSniff.php)
|
||||
|
||||
## Do not write empty statements
|
||||
|
||||
Empty statements are considered bad practice and must be avoided.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
if($condition) {
|
||||
// empty statement
|
||||
} else {
|
||||
// do something here
|
||||
}
|
||||
```
|
||||
|
||||
**Good** (invert condition)
|
||||
|
||||
```PHP
|
||||
if(!$condition) {
|
||||
// do something
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.CodeAnalysis.EmptyStatement`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/EmptyStatementSniff.php)
|
||||
|
||||
## Do not write unconditional if-statements
|
||||
|
||||
If-statements without conditions are considered bad practice and must be avoided.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
```PHP
|
||||
if(true) {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.CodeAnalysis.UnconditionalIfStatement`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UnconditionalIfStatementSniff.php)
|
||||
|
||||
# Classes
|
||||
## Use PascalCase for class names
|
||||
|
||||
Class names must be written in [PascalCase](http://wiki.c2.com/?PascalCase).
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
class mySUPERclass { ... }
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
class MySuperClass { ... }
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`PEAR.NamingConventions.ValidClassName`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PEAR/Sniffs/NamingConventions/ValidClassNameSniff.php)
|
||||
|
||||
## Do not use final statements inside final classes
|
||||
|
||||
Final classes cannot be extended, so it doesn't make sense to add the final keyword to class members.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
final class MyClass {
|
||||
final public function MyFunction() {
|
||||
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Good** (remove the final keyword from class members)
|
||||
|
||||
```PHP
|
||||
final class MyClass {
|
||||
public function MyFunction() {
|
||||
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.CodeAnalysis.UnnecessaryFinalModifier`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UnnecessaryFinalModifierSniff.php)
|
||||
|
||||
## Do not override methods to call their parent
|
||||
|
||||
It doesn't make sense to override a method only to call their parent. When overriding methods, make sure to add some functionality to it.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
class MyClass extends BaseClass {
|
||||
public function BaseFunction() {
|
||||
parent::BaseFunction();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Good** (don't override the function)
|
||||
|
||||
```PHP
|
||||
class MyClass extends BaseClass {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.CodeAnalysis.UselessOverridingMethod`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UselessOverridingMethodSniff.php)
|
||||
|
||||
## abstract and final declarations MUST precede the visibility declaration
|
||||
|
||||
When declaring `abstract` and `final` functions, the visibility (scope) must follow after `abstract` or `final`.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
class MyClass extends BaseClass {
|
||||
public abstract function AbstractFunction() { }
|
||||
public final function FinalFunction() { }
|
||||
}
|
||||
```
|
||||
|
||||
**Good** (`abstract` and `final` before `public`)
|
||||
|
||||
```PHP
|
||||
class MyClass extends BaseClass {
|
||||
abstract public function AbstractFunction() { }
|
||||
final public function FinalFunction() { }
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`PSR2.Methods.MethodDeclaration`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PSR2/Sniffs/Methods/MethodDeclarationSniff.php)
|
||||
|
||||
## static declaration MUST come after the visibility declaration
|
||||
|
||||
The `static` keyword must come after the visibility (scope) parameter.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
class MyClass extends BaseClass {
|
||||
static public function StaticFunction() { }
|
||||
}
|
||||
```
|
||||
|
||||
**Good** (`static` after `public`)
|
||||
|
||||
```PHP
|
||||
class MyClass extends BaseClass {
|
||||
public static function StaticFunction() { }
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`PSR2.Methods.MethodDeclaration`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PSR2/Sniffs/Methods/MethodDeclarationSniff.php)
|
||||
|
||||
# Casting
|
||||
## Do not add spaces when casting
|
||||
|
||||
The casting type should be put into parenthesis without spaces.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$text = ( string )$number;
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$text = (string)$number;
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Squiz.WhiteSpace.CastSpacing`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/WhiteSpace/CastSpacingSniff.php)
|
||||
|
||||
# Arrays
|
||||
## Always use the long array syntax
|
||||
|
||||
Arrays should be initialized using the long array syntax.
|
||||
|
||||
<details><summary>Example</summary><div><br>
|
||||
|
||||
**Bad**
|
||||
|
||||
```PHP
|
||||
$data = [ 'hello' => 'world' ];
|
||||
```
|
||||
|
||||
**Good**
|
||||
|
||||
```PHP
|
||||
$data = array('hello' => 'world');
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Reference_: [`Generic.Arrays.DisallowShortArraySyntax`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/Arrays/DisallowShortArraySyntaxSniff.php)
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
Pull requests allow you to improve RSS-Bridge. Maintainers will have to understand your changes before merging. In order to make this process as efficient as possible, please follow the policies explained below. Maintainers will merge your pull request much faster that way.
|
||||
|
||||
# Fix one issue per pull request
|
||||
|
||||
It is considered good practice to fix one specific (or a specific set of) error(s). You can open multiple pull requests if you need to address multiple subjects. The same applies to adding features to RSS-Bridge. Maintainers must be able to comprehend your pull request for it to be merged quickly.
|
||||
|
||||
# Respect the coding style policy
|
||||
|
||||
The [coding style policy](./01_Coding_style_policy.md) requires you to write your code in certain ways. If you plan to get it merged into RSS-Bridge, please make sure your code follows the policy. Maintainers will only merge pull requests that pass all tests.
|
||||
|
||||
# Properly name your commits
|
||||
|
||||
Commits are not only for show, they do help maintainers understand what you did in your pull request, just like a table of contents in a well formed book (or Wiki). Here are a few rules you should follow:
|
||||
|
||||
* When fixing a bridge (located in the `bridges` directory), write `[BridgeName] Feature` <br>(i.e. `[YoutubeBridge] Fix typo in video titles`).
|
||||
* When fixing other files, use `[FileName] Feature` <br>(i.e. `[index.php] Add multilingual support`).
|
||||
* When fixing a general problem that applies to multiple files, write `category: feature` <br>(i.e. `bridges: Fix various typos`).
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
The repository contains a few folders that make up **RSS-Bridge**. Here is a brief description of what you can expect to find where:
|
||||
|
||||
Folder | Description
|
||||
-------|------------
|
||||
[`bridges/`](https://github.com/RSS-Bridge/rss-bridge/tree/master/bridges) | Contains all bridges that are currently supported by **RSS-Bridge**. Each file represents one Bridge that is displayed on the [Welcome screen](../01_General/04_Screenshots.md#welcome-screen) of **RSS-Bridge**
|
||||
[`caches/`](https://github.com/RSS-Bridge/rss-bridge/tree/master/caches) | Contains all cache types for **RSS-Bridge**.
|
||||
[`css/`](https://github.com/RSS-Bridge/rss-bridge/tree/master/css) | Contains all [Cascading Style Sheets](https://en.wikipedia.org/wiki/Cascading_Style_Sheets) for **RSS-Bridge**
|
||||
[`formats/`](https://github.com/RSS-Bridge/rss-bridge/tree/master/formats) | Contains all export formats for **RSS-Bridge**.
|
||||
[`lib/`](https://github.com/RSS-Bridge/rss-bridge/tree/master/lib) | Contains the core API of **RSS-Bridge**.
|
||||
[`vendor/`](https://github.com/RSS-Bridge/rss-bridge/tree/master/vendor) | Contains vendor specific files to support **RSS-Bridge**. Development of all files in this folder must be done in the vendor specific repository (not part of **RSS-Bridge**)
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
RSS-Bridge currently supports three 'actions' which it can operate:
|
||||
|
||||
1) [Display](#display) (`?action=display`)
|
||||
2) [Detect](#detect) (`?action=detect`)
|
||||
3) [List](#list) (`?action=list`)
|
||||
|
||||
## Display
|
||||
|
||||
The `display` action returns feeds generated by [bridges](../05_Bridge_API/index.md). It requires additional parameter, some of which are specific to each bridge (see implementation details for your specific bridge). The following list contains mandatory parameter applicable to all bridges, excluding parameters that require [additional options](../03_For_Hosts/08_Custom_Configuration.md). Errors are returned for missing mandatory parameters:
|
||||
|
||||
Parameter | Required | Description
|
||||
----------|----------|------------
|
||||
`bridge` | yes | Specifies the name of the bridge to display. Possible values are determined from the bridges available to the current instance of RSS-Bridge and the [whitelist](../03_For_Hosts/05_Whitelisting.md).
|
||||
`format` | yes | Specifies the name of the format to use for displaying the feed. Possible values are determined from the formats available to the current instance of RSS-Bridge.
|
||||
|
||||
## Detect
|
||||
|
||||
The `detect` action attempts to redirect the user to an appropriate `display` action for a feed based on a supplied URL. As bridges have to individually implement this it may not work for every bridge.
|
||||
|
||||
If an appropriate bridge is found, a `301 Moved Permanently` HTTP status code is returned with a relative location for a `display` action. If no appropriate bridge is found or a required parameter is missing, a `400 Bad Request` status code is returned.
|
||||
|
||||
The parameters for this action are listed bellow:
|
||||
|
||||
Parameter | Required | Description
|
||||
----------|----------|------------
|
||||
`url` | yes | Specifies the URL to attempt to find a feed from. The value of this should be URL encoded.
|
||||
`format` | yes | Specifies the name of the format to use for displaying the feed. This is passed to the detected `display` action. Possible values are determined from the formats available to the current instance of RSS-Bridge.
|
||||
|
||||
## List
|
||||
|
||||
The `list` action returns a JSON formatted text containing information on all bridges available to the current instance of RSS-Bridge. Inactive bridges (not [whitelisted](../03_For_Hosts/05_Whitelisting.md)) are included as well. Broken bridges are also included, but with limited parameters (only `"status": "inactive"`).
|
||||
|
||||
This example shows JSON data for a single bridge:
|
||||
|
||||
```JSON
|
||||
{
|
||||
"bridges": {
|
||||
"ABCTabs": {
|
||||
"status": "active",
|
||||
"uri": "https:\/\/www.abc-tabs.com\/",
|
||||
"name": "ABC Tabs Bridge",
|
||||
"parameters": [],
|
||||
"maintainer": "kranack",
|
||||
"description": "Returns 22 newest tabs"
|
||||
}
|
||||
},
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
The top-level JSON object contains two parameters:
|
||||
|
||||
* [`bridges`](#bridges): A collection of bridges
|
||||
* [`total`](#total): The total number of bridges
|
||||
|
||||
```JSON
|
||||
{
|
||||
"bridges": { },
|
||||
"total": 0
|
||||
}
|
||||
```
|
||||
|
||||
### `bridges`
|
||||
|
||||
The `bridges` parameter is a collection of bridge objects. The name of each object represents the name of the bridge as needed for the [`display` action](#display). Each object contains parameters, most of which are optional. The following table summarizes the parameters:
|
||||
|
||||
Parameter | Optional | Description
|
||||
--------------|----------|------------
|
||||
`status` | No | Indicates the status of the bridge. Possible values are '`active`' and '`inactive`'. Only `active` bridges can be used for the [`display` action](#display).
|
||||
`uri` | Yes | Returns the URI of the bridge, as returned by the [`getURI`](../05_Bridge_API/02_BridgeAbstract.md#geturi) function of the bridge.
|
||||
`name` | Yes | Returns the name of the bridge, as returned by the [`getName`](../05_Bridge_API/02_BridgeAbstract.md#getname) function of the bridge.
|
||||
`parameters` | Yes | Returns the `PARAMETERS` object of the bridge
|
||||
`maintainer` | Yes | Returns the name(s) of maintainer(s) for the bridge
|
||||
`description` | Yes | Returns the description of the bridge
|
||||
|
||||
### `total`
|
||||
|
||||
This parameter represents the total number of bridges available to the current instance of RSS-Bridge.
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
<h1 align="center">Warning!</h1>
|
||||
|
||||
Enabling debug mode on a public server may result in malicious clients retrieving sensitive data about your server and possibly gaining access to it. Do not enable debug mode on a public server, unless you understand the implications of your doing!
|
||||
|
||||
***
|
||||
|
||||
Debug mode enables error reporting and prevents loading data from the cache (data is still written to the cache).
|
||||
To enable debug mode, create a file named 'DEBUG' in the root directory of RSS-Bridge (next to `index.php`). For further security, insert your IP address in the file. You can add multiple addresses, one per line.
|
||||
|
||||
_Notice_:
|
||||
|
||||
* An empty file enables debug mode for anyone!
|
||||
* The bridge whitelist still applies! (debug mode does **not** enable all bridges)
|
||||
|
||||
RSS-Bridge will give you a visual feedback when debug mode is enabled:
|
||||
|
||||
|
||||
|
||||
While debug mode is active, RSS-Bridge will write additional data to your servers `error.log`.
|
||||
|
||||
Debug mode is controlled by the static class `Debug`. It provides three core functions:
|
||||
|
||||
`Debug::isEnabled()`: Returns `true` if debug mode is enabled.
|
||||
`Debug::isSecure()`: Returns `true` if your client is on the debug whitelist.
|
||||
`Debug::log($message)`: Adds a message to `error.log`. It takes one parameter, which can be anything. For example: `Debug::log('Hello World!');`
|
||||
|
||||
**Notice**: `Debug::log($message)` calls `Debug::isEnabled()` internally. You don't have to do that manually.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
This area is intended for developers who decide to contribute to **RSS-Bridge** which is primarily written in [`PHP`](http://www.php.net/) with some aspects of [`HTML`](https://en.wikipedia.org/wiki/HTML) and [`CSS`](https://en.wikipedia.org/wiki/Cascading_Style_Sheets).
|
||||
|
||||
If you are new to **RSS-Bridge** you should make yourself familiar with some general aspects:
|
||||
- [Coding style policy](./01_Coding_style_policy.md)
|
||||
- [Folder structure](./03_Folder_structure.md)
|
||||
- [Debug mode](./05_Debug_mode.md)
|
||||
- [Bridge API](../05_Bridge_API/index.md)
|
||||
- [Cache API](../07_Cache_API/index.md)
|
||||
- [Format API](../08_Format_API/index.md)
|
||||
- [Technical recommendations](../09_Technical_recommendations/index.md)
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
Create a new file in the `bridges/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)).
|
||||
|
||||
The file name must be named according to following specification:
|
||||
* It starts with the full name of the site
|
||||
* All white-space must be removed
|
||||
* The first letter of a word is written in upper-case, unless the site name is specified otherwise (example: Freenews, not FreeNews, because the site is named 'Freenews')
|
||||
* The first character must be upper-case
|
||||
* The file name must end with 'Bridge'
|
||||
* The file type must be PHP, written in **small** letters (seriously!) ".php"
|
||||
|
||||
**Examples:**
|
||||
|
||||
Site | Filename
|
||||
-----|---------
|
||||
Wikipedia | **Wikipedia**Bridge.php
|
||||
Facebook | **Facebook**Bridge.php
|
||||
GitHub | **GitHub**Bridge.php
|
||||
Freenews | **Freenews**Bridge.php
|
||||
|
||||
The file must start with the PHP tags and end with an empty line. The closing tag `?>` is [omitted](http://php.net/basic-syntax.instruction-separation).
|
||||
|
||||
**Example:**
|
||||
|
||||
```php
|
||||
<?php
|
||||
// PHP code here
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
The next step is to extend one of the base classes. Refer to one of an base classes listed on the [Bridge API](../05_Bridge_API/index.md) page.
|
||||
|
|
@ -0,0 +1,456 @@
|
|||
`BridgeAbstract` is a base class for standard bridges. It implements the most common functions to simplify the process of adding new bridges.
|
||||
|
||||
***
|
||||
|
||||
# Creating a new bridge
|
||||
|
||||
You need four basic steps in order to create a new bridge:
|
||||
|
||||
[**Step 1**](#step-1---create-a-new-file) - Create a new file
|
||||
[**Step 2**](#step-2---add-a-class-extending-bridgeabstract) - Add a class, extending `BridgeAbstract`
|
||||
[**Step 3**](#step-3---add-general-constants-to-the-class) - Add general constants to the class
|
||||
[**Step 4**](#step-4---implement-a-function-to-collect-feed-data) - Implement a function to collect feed data
|
||||
|
||||
These steps are described in more detail below. At the end of this document you'll find a complete [template](#template) based on these instructions. The pictures below show an example based on these instructions:
|
||||
|
||||
<details><summary>Show pictures</summary><div>
|
||||
|
||||
|
||||
|
||||
***
|
||||
|
||||
|
||||
|
||||
</div></details><br>
|
||||
|
||||
Make sure to read these instructions carefully. Please don't hesitate to open an [Issue](https://github.com/RSS-Bridge/rss-bridge/issues) if you have further questions (or suggestions). Once your bridge is finished, please open a [Pull Request](https://github.com/RSS-Bridge/rss-bridge/pulls), in order to get your bridge merge into RSS-Bridge.
|
||||
|
||||
***
|
||||
|
||||
## Step 1 - Create a new file
|
||||
|
||||
Please read [these instructions](./01_How_to_create_a_new_bridge.md) on how to create a new file for RSS-Bridge.
|
||||
|
||||
## Step 2 - Add a class, extending `BridgeAbstract`
|
||||
|
||||
Your bridge needs to be a class, which extends `BridgeAbstract`. The class name must **exactly** match the name of the file, without the file extension.
|
||||
|
||||
For example: `MyBridge.php` => `MyBridge`
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
|
||||
}
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
</div></details>
|
||||
|
||||
## Step 3 - Add general constants to the class
|
||||
|
||||
In order to present your bridge on the front page, RSS-Bridge requires a few constants:
|
||||
|
||||
```PHP
|
||||
const NAME // Name of the Bridge (default: "Unnamed Bridge")
|
||||
const URI // URI to the target website of the bridge (default: empty)
|
||||
const DESCRIPTION // A brief description of the Bridge (default: "No description provided")
|
||||
const MAINTAINER // Name of the maintainer, i.e. your name on GitHub (default: "No maintainer")
|
||||
const PARAMETERS // (optional) Definition of additional parameters (default: empty)
|
||||
const CACHE_TIMEOUT // (optional) Defines the maximum duration for the cache in seconds (default: 3600)
|
||||
```
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
const NAME = 'My Bridge';
|
||||
const URI = 'https://github.com/RSS-Bridge/rss-bridge/wiki/BridgeAbstract';
|
||||
const DESCRIPTION = 'Returns "Hello World!"';
|
||||
const MAINTAINER = 'ghost';
|
||||
}
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
**Notice**: `const PARAMETERS` can be used to request information from the user. Refer to [these instructions](#parameters) for more information.
|
||||
|
||||
## Step 4 - Implement a function to collect feed data
|
||||
|
||||
In order for RSS-Bridge to collect data, you must implement the **public** function `collectData`. This function takes no arguments and returns nothing. It generates a list of feed elements, which must be placed into the variable `$this->items`.
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
const NAME = 'My Bridge';
|
||||
const URI = 'https://github.com/RSS-Bridge/rss-bridge/wiki/BridgeAbstract';
|
||||
const DESCRIPTION = 'Returns "Hello World!"';
|
||||
const MAINTAINER = 'ghost';
|
||||
|
||||
public function collectData() {
|
||||
$item = array(); // Create an empty item
|
||||
|
||||
$item['title'] = 'Hello World!';
|
||||
|
||||
$this->items[] = $item; // Add item to the list
|
||||
}
|
||||
}
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
For more details on the `collectData` function refer to [these instructions](#collectdata).
|
||||
|
||||
***
|
||||
|
||||
# Template
|
||||
|
||||
Use this template to create your own bridge. Please remove any unnecessary comments and parameters.
|
||||
|
||||
```php
|
||||
<?php
|
||||
class MyBridge extends BridgeAbstract {
|
||||
const NAME = 'Unnamed bridge';
|
||||
const URI = '';
|
||||
const DESCRIPTION = 'No description provided';
|
||||
const MAINTAINER = 'No maintainer';
|
||||
const PARAMETERS = array(); // Can be omitted!
|
||||
const CACHE_TIMEOUT = 3600; // Can be omitted!
|
||||
|
||||
public function collectData() {
|
||||
$item = array(); // Create an empty item
|
||||
|
||||
$item['title'] = 'Hello World!';
|
||||
|
||||
$this->items[] = $item; // Add item to the list
|
||||
}
|
||||
}
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
||||
# PARAMETERS
|
||||
|
||||
You can specify additional parameters in order to customize the bridge (i.e. to specify how many items to return). This document explains how to specify those parameters and which options are available to you.
|
||||
|
||||
For information on how to read parameter values during execution, please refer to the [getInput](../06_Helper_functions/index.md#getinput) function.
|
||||
|
||||
***
|
||||
|
||||
## Adding parameters to a bridge
|
||||
|
||||
Parameters are specified as part of the bridge class. An empty list of parameters is defined as `const PARAMETERS = array();`
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
<?PHP
|
||||
class MyBridge extends BridgeAbstract {
|
||||
/* ... */
|
||||
const PARAMETERS = array(); // Empty list of parameters (can be omitted)
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
Parameters are organized in two levels:
|
||||
|
||||
[**Level 1**](##level-1---context) - Context
|
||||
[**Level 2**](##level-2---parameter) - Parameter
|
||||
|
||||
## Level 1 - Context
|
||||
|
||||
A context is defined as a associative array of parameters. The name of a context is displayed by RSS-Bridge.
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const PARAMETERS = array(
|
||||
'My Context 1' => array(),
|
||||
'My Context 2' => array()
|
||||
);
|
||||
```
|
||||
|
||||
**Output**
|
||||
|
||||
|
||||
|
||||
</div></details><br>
|
||||
|
||||
_Notice_: The name of a context can be left empty if only one context is needed!
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const PARAMETERS = array(
|
||||
array()
|
||||
);
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
You can also define a set of parameters that will be applied to every possible context of your bridge. To do this, specify a context named `global`.
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const PARAMETERS = array(
|
||||
'global' => array() // Applies to all contexts!
|
||||
);
|
||||
```
|
||||
|
||||
</div></details>
|
||||
|
||||
## Level 2 - Parameter
|
||||
|
||||
Parameters are placed inside a context. They are defined as associative array of parameter specifications. Each parameter is defined by it's internal input name, a definition in the form `'n' => array();`, where `n` is the name with which the bridge can access the parameter during execution.
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const PARAMETERS = array(
|
||||
'My Context' => array(
|
||||
'n' => array()
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
|
||||
The parameter specification consists of various fields, listed in the table below.
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
const PARAMETERS = array(
|
||||
'My Context' => array(
|
||||
'n' => array(
|
||||
'name' => 'Limit',
|
||||
'type' => 'number',
|
||||
'required' => false,
|
||||
'title' => 'Maximum number of items to return',
|
||||
'defaultValue' => 10
|
||||
)
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
**Output**
|
||||
|
||||
|
||||
|
||||
</div></details>
|
||||
|
||||
***
|
||||
|
||||
Parameter Name | Required | Type | Supported values | Description
|
||||
---------------|----------|------|------------------| -----------
|
||||
`name` | **yes** | Text | | Input name as displayed to the user
|
||||
`type` | no | Text | `text`, `number`, `list`, `checkbox` | Type of the input (default: `text`)
|
||||
`required` | no | Boolean | `true`, `false` | Specifies if the parameter is required or not (default: `false`). Not supported for lists and checkboxes.
|
||||
[`values`](#list-values) | no | associative array | | name/value pairs used by the HTML option tag, required for type '`list`'
|
||||
`title` | no | Text | | Used as tool-tip when mouse-hovering over the input box
|
||||
`pattern` | no | Text | | Defines a pattern for an element of type `text`. The pattern should be mentioned in the `title` attribute!
|
||||
`exampleValue` | no | Text | | Defines an example value displayed for elements of type `text` and `number` when no data has been entered yet
|
||||
[`defaultValue`](#defaultvalue) | no | | | Defines the default value if left blank by the user
|
||||
|
||||
#### List values
|
||||
|
||||
List values are defined in an associative array where keys are the string displayed in the combo list of the **RSS-Bridge** web interface, and values are the content of the \<option\> HTML tag value attribute.
|
||||
|
||||
```PHP
|
||||
...
|
||||
'type' => 'list',
|
||||
'values' => array(
|
||||
'Item A' => 'itemA'
|
||||
'Item B' => 'itemB'
|
||||
)
|
||||
...
|
||||
```
|
||||
|
||||
If a more complex organization is required to display the values, the above key/value can be used to set a title as a key and another array as a value:
|
||||
```PHP
|
||||
...
|
||||
'type' => 'list',
|
||||
'values' => array(
|
||||
'Item A' => 'itemA',
|
||||
'List 1' => array(
|
||||
'Item C' => 'itemC',
|
||||
'Item D' => 'itemD'
|
||||
),
|
||||
'List 2' => array(
|
||||
'Item E' => 'itemE',
|
||||
'Item F' => 'itemF'
|
||||
),
|
||||
'Item B' => 'itemB'
|
||||
)
|
||||
...
|
||||
```
|
||||
|
||||
#### defaultValue
|
||||
|
||||
This attribute defines the default value for your parameter. Its behavior depends on the `type`:
|
||||
|
||||
- `text`: Allows any text
|
||||
- `number`: Allows any number
|
||||
- `list`: Must match either name or value of one element
|
||||
- `checkbox`: Must be "checked" to activate the checkbox
|
||||
|
||||
***
|
||||
|
||||
# queriedContext
|
||||
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
# collectData
|
||||
The `collectData` function is responsible for collecting data and adding items to generate feeds from. If you are unsure how to solve a specific problem, please don't hesitate to open an [Issue](https://github.com/RSS-Bridge/rss-bridge/issues) on GitHub. Existing bridges are also a good source to learn implementing your own bridge.
|
||||
|
||||
## Implementing the `collectData` function
|
||||
|
||||
Implementation for the `collectData` function is specific to each bridge. However, there are certain reoccurring elements, described below. RSS-Bridge also provides functions to simplify the process of collecting and parsing HTML data (see "Helper Functions" on the sidebar)
|
||||
|
||||
Elements collected by this function must be stored in `$this->items`. The `items` variable is an array of item elements, each of which is an associative array that may contain arbitrary keys. RSS-Bridge specifies common keys which are used to generate most common feed formats.
|
||||
|
||||
<details><summary>Show example</summary><div>
|
||||
|
||||
```PHP
|
||||
|
||||
$item = array(); // Create a new item
|
||||
|
||||
$item['title'] = 'Hello World!';
|
||||
|
||||
$this->items[] = $item; // Add item to the list
|
||||
|
||||
```
|
||||
|
||||
</div></details><br>
|
||||
Additional keys may be added for custom APIs (ignored by RSS-Bridge).
|
||||
|
||||
## Item parameters
|
||||
|
||||
The item array should provide as much information as possible for RSS-Bridge to generate feature rich feeds. Find below list of keys supported by RSS-Bridge.
|
||||
|
||||
```PHP
|
||||
$item['uri'] // URI to reach the subject ("https://...")
|
||||
$item['title'] // Title of the item
|
||||
$item['timestamp'] // Timestamp of the item in numeric or text format (compatible for strtotime())
|
||||
$item['author'] // Name of the author for this item
|
||||
$item['content'] // Content in HTML format
|
||||
$item['enclosures'] // Array of URIs to an attachments (pictures, files, etc...)
|
||||
$item['categories'] // Array of categories / tags / topics
|
||||
$item['uid'] // A unique ID to identify the current item
|
||||
```
|
||||
All formats support these parameters. The formats `Plaintext` and `JSON` also support custom parameters.
|
||||
|
||||
# getDescription
|
||||
|
||||
The `getDescription` function returns the description for a bridge.
|
||||
|
||||
**Notice:** By default **RSS-Bridge** returns the contents of `const DESCRIPTION`, so you only have to implement this function if you require different behavior!
|
||||
|
||||
```PHP
|
||||
public function getDescription(){
|
||||
return self::DESCRIPTION;
|
||||
}
|
||||
```
|
||||
|
||||
# getMaintainer
|
||||
|
||||
The `getMaintainer` function returns the name of the maintainer for a bridge.
|
||||
|
||||
**Notice:** By default **RSS-Bridge** returns `const MAINTAINER`, so you only have to implement this function if you require different behavior!
|
||||
|
||||
```PHP
|
||||
public function getMaintainer(){
|
||||
return self::MAINTAINER;
|
||||
}
|
||||
```
|
||||
|
||||
# getName
|
||||
The `getName` function returns the name of a bridge.
|
||||
|
||||
**Notice:** By default **RSS-Bridge** returns `const NAME`, so you only have to implement this function if you require different behavior!
|
||||
|
||||
```PHP
|
||||
public function getName(){
|
||||
return self::NAME;
|
||||
}
|
||||
```
|
||||
|
||||
# getURI
|
||||
The `getURI` function returns the base URI for a bridge.
|
||||
|
||||
**Notice:** By default **RSS-Bridge** returns `const URI`, so you only have to implement this function if you require different behavior!
|
||||
|
||||
```PHP
|
||||
public function getURI(){
|
||||
return self::URI;
|
||||
}
|
||||
```
|
||||
|
||||
# getIcon
|
||||
The `getIcon` function returns the URI for an icon, used as favicon in feeds.
|
||||
|
||||
If no icon is specified by the bridge, RSS-Bridge will use a default location: `static::URI . '/favicon.ico'` (i.e. "https://github.com/favicon.ico") which may or may not exist.
|
||||
|
||||
```PHP
|
||||
public function getIcon(){
|
||||
return static::URI . '/favicon.ico';
|
||||
}
|
||||
```
|
||||
# detectParameters
|
||||
The `detectParameters` function takes a URL and attempts to extract a valid set of parameters for the current bridge.
|
||||
|
||||
If the passed URL is valid for this bridge the function should return an array of parameter -> value pairs that can be used by this bridge, or an empty array if the bridge requires no parameters. If the URL is not relevant for this bridge the function should return `null`.
|
||||
|
||||
**Notice:** Implementing this function is optional. By default **RSS-Bridge** tries to match the supplied URL to the `URI` constant defined in the bridge which may be enough for bridges without any parameters defined.
|
||||
|
||||
```PHP
|
||||
public function detectParameters($url){
|
||||
$regex = '/^(https?:\/\/)?(www\.)?(.+?)(\/)?$/';
|
||||
if(empty(static::PARAMETERS)
|
||||
&& preg_match($regex, $url, $urlMatches) > 0
|
||||
&& preg_match($regex, static::URI, $bridgeUriMatches) > 0
|
||||
&& $urlMatches[3] === $bridgeUriMatches[3]) {
|
||||
return array();
|
||||
} else {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
`FeedExpander` extends [`BridgeAbstract`](./02_BridgeAbstract.md) and adds functions to collect data from existing feeds.
|
||||
|
||||
**Usage example**: _You have discovered a site that provides feeds which are hidden and inaccessible by normal means. You want your bridge to directly read the feeds and provide them via **RSS-Bridge**_
|
||||
|
||||
To create a new Bridge extending `FeedExpander` you must implement all required functions of [`BridgeAbstract`](./02_BridgeAbstract.md). `FeedExpander` additionally provides following functions:
|
||||
|
||||
* [`parseItem`](#the-parseitem-function)
|
||||
* [`getName`](#the-getname-function)
|
||||
* [`getURI`](#the-geturi-function)
|
||||
* [`getDescription`](#the-getdescription-function)
|
||||
|
||||
Find a [template](#template) at the end of this file.
|
||||
|
||||
**Notice:** For a standard feed only `collectData` need to be implemented. `collectData` should call `$this->collectExpandableDatas('your URI here');` to automatically load feed items and header data (will subsequently call `parseItem` for each item in the feed). You can limit the number of items to fetch by specifying an additional parameter for: `$this->collectExpandableDatas('your URI here', 10)` (limited to 10 items).
|
||||
|
||||
## The `parseItem` function
|
||||
|
||||
This function receives one item from the current feed and should return one **RSS-Bridge** item.
|
||||
The default function does all the work to get the item data from the feed, whether it is RSS 1.0,
|
||||
RSS 2.0 or Atom 1.0. If you have to redefine this function in your **RSS-Bridge** for whatever reason,
|
||||
you should first call the parent function to initialize the item, then apply the changes that you require.
|
||||
|
||||
**Notice:** The following code sample is just an example. Implementation depends on your requirements!
|
||||
|
||||
```PHP
|
||||
protected function parseItem($feedItem){
|
||||
$item = parent::parseItem($feedItem);
|
||||
$item['content'] = str_replace('rssbridge','RSS-Bridge',$feedItem->content);
|
||||
|
||||
return $item;
|
||||
}
|
||||
```
|
||||
|
||||
### Helper functions
|
||||
|
||||
The `FeedExpander` already provides a set of functions to parse RSS or Atom items based on the specifications. Where possible make use of these functions:
|
||||
|
||||
Function | Description
|
||||
---------|------------
|
||||
`parseATOMItem` | Parses an Atom 1.0 feed item
|
||||
`parseRSS_0_9_1_Item` | Parses an RSS 0.91 feed item
|
||||
`parseRSS_1_0_Item` | Parses an RSS 1.0 feed item
|
||||
`parseRSS_2_0_Item` | Parses an RSS 2.0 feed item
|
||||
|
||||
In the following list you'll find the feed tags assigned to the the **RSS-Bridge** item keys:
|
||||
|
||||
Function | uri | title | timestamp | author | content
|
||||
---------|-----|-------|-----------|--------|--------
|
||||
`parseATOMItem` | id | title | updated | author | content
|
||||
`parseRSS_0_9_1_Item` | link | title | | | description
|
||||
`parseRSS_1_0_Item` | link | title | dc:date | dc:creator | description
|
||||
`parseRSS_2_0_Item` | link, guid | title | pubDate, dc:date | author, dc:creator | description
|
||||
|
||||
## The `getName` function
|
||||
|
||||
Returns the name of the current feed.
|
||||
|
||||
```PHP
|
||||
return $this->name;
|
||||
```
|
||||
|
||||
**Notice:** Only implement this function if you require different behavior!
|
||||
|
||||
## The `getURI` function
|
||||
|
||||
Return the uri for the current feed.
|
||||
|
||||
```PHP
|
||||
return $this->uri;
|
||||
```
|
||||
|
||||
**Notice:** Only implement this function if you require different behavior!
|
||||
|
||||
## The `getDescription` function
|
||||
|
||||
Returns the description for the current bridge.
|
||||
|
||||
```PHP
|
||||
return $this->description;
|
||||
```
|
||||
|
||||
**Notice:** Only implement this function if you require different behavior!
|
||||
|
||||
# Template
|
||||
|
||||
This is the template for a new bridge:
|
||||
|
||||
```PHP
|
||||
<?php
|
||||
class MySiteBridge extends FeedExpander {
|
||||
|
||||
const MAINTAINER = 'No maintainer';
|
||||
const NAME = 'Unnamed bridge';
|
||||
const URI = '';
|
||||
const DESCRIPTION = 'No description provided';
|
||||
const PARAMETERS = array();
|
||||
const CACHE_TIMEOUT = 3600;
|
||||
|
||||
public function collectData(){
|
||||
$this->collectExpandableDatas('your feed URI');
|
||||
}
|
||||
}
|
||||
// Imaginary empty line!
|
||||
```
|
||||
|
|
@ -0,0 +1,157 @@
|
|||
`XPathAbstract` extends [`BridgeAbstract`](./02_BridgeAbstract.md) and adds functionality for generating feeds based on _XPath expressions_. It makes creation of new bridges easy and if you're familiar with XPath expressions this class is probably the right point for you to start with.
|
||||
|
||||
At the end of this document you'll find a complete [template](#template) based on these instructions.
|
||||
|
||||
***
|
||||
# Required constants
|
||||
To create a new Bridge based on `XPathAbstract` your inheriting class should specify a set of constants describing the feed and the XPath expressions.
|
||||
|
||||
It is advised to override constants inherited from [`BridgeAbstract`](./02_BridgeAbstract.md#step-3---add-general-constants-to-the-class) aswell.
|
||||
|
||||
## Class constant `FEED_SOURCE_URL`
|
||||
Source Web page URL (should provide either HTML or XML content). You can specify any website URL which serves data suited for display in RSS feeds
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_FEED_TITLE`
|
||||
XPath expression for extracting the feed title from the source page. If this is left blank or does not provide any data `BridgeAbstract::getName()` is used instead as the feed's title.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_FEED_ICON`
|
||||
XPath expression for extracting the feed favicon URL from the source page. If this is left blank or does not provide any data `BridgeAbstract::getIcon()` is used instead as the feed's favicon URL.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM`
|
||||
XPath expression for extracting the feed items from the source page. Enter an XPath expression matching a list of dom nodes, each node containing one feed article item in total (usually a surrounding `<div>` or `<span>` tag). This will be the context nodes for all of the following expressions. This expression usually starts with a single forward slash.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM_TITLE`
|
||||
XPath expression for extracting an item title from the item context. This expression should match a node contained within each article item node containing the article headline. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM_CONTENT`
|
||||
XPath expression for extracting an item's content from the item context. This expression should match a node contained within each article item node containing the article content or description. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM_URI`
|
||||
XPath expression for extracting an item link from the item context. This expression should match a node's attribute containing the article URL (usually the href attribute of an `<a>` tag). It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM_AUTHOR`
|
||||
XPath expression for extracting an item author from the item context. This expression should match a node contained within each article item node containing the article author's name. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM_TIMESTAMP`
|
||||
XPath expression for extracting an item timestamp from the item context. This expression should match a node or node's attribute containing the article timestamp or date (parsable by PHP's strtotime function). It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM_ENCLOSURES`
|
||||
XPath expression for extracting item enclosures (media content like images or movies) from the item context. This expression should match a node's attribute containing an article image URL (usually the src attribute of an <img> tag or a style attribute). It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
|
||||
|
||||
## Class constant `XPATH_EXPRESSION_ITEM_CATEGORIES`
|
||||
XPath expression for extracting an item category from the item context. This expression should match a node or node's attribute contained within each article item node containing the article category. This could be inside <div> or <span> tags or sometimes be hidden in a data attribute. It should start with a dot followed by two forward slashes, referring to any descendant nodes of the article item node. Attributes can be selected by prepending an `@` char before the attributes name.
|
||||
|
||||
## Class constant `SETTING_FIX_ENCODING`
|
||||
Turns on automatic fixing of encoding errors. Set this to true for fixing feed encoding by invoking PHP's `utf8_decode` function on all extracted texts. Try this in case you see "broken" or "weird" characters in your feed where you'd normally expect umlauts or any other non-ascii characters.
|
||||
|
||||
# Optional methods
|
||||
`XPathAbstract` offers a set of methods which can be overridden by derived classes for fine tuning and customization. This is optional. The methods provided for overriding can be grouped into three categories.
|
||||
|
||||
## Methods for providing XPath expressions
|
||||
Usually XPath expressions are defined in the class constants described above. By default the following base methods just return the value of its corresponding class constant. However deriving classed can override them in case if XPath expressions need to be formed dynamically or based on conditions. In case any of these methods is defined, the method's return value is used instead of the corresponding constant for providing the value.
|
||||
|
||||
### Method `getSourceUrl()`
|
||||
Should return the source Web page URL used as a base for applying the XPath expressions.
|
||||
|
||||
### Method `getExpressionTitle()`
|
||||
Should return the XPath expression for extracting the feed title from the source page.
|
||||
|
||||
### Method `getExpressionIcon()`
|
||||
Should return the XPath expression for extracting the feed favicon from the source page.
|
||||
|
||||
### Method `getExpressionItem()`
|
||||
Should return the XPath expression for extracting the feed items from the source page.
|
||||
|
||||
### Method `getExpressionItemTitle()`
|
||||
Should return the XPath expression for extracting an item title from the item context.
|
||||
|
||||
### Method `getExpressionItemContent()`
|
||||
Should return the XPath expression for extracting an item's content from the item context.
|
||||
|
||||
### Method `getExpressionItemUri()`
|
||||
Should return the XPath expression for extracting an item link from the item context.
|
||||
|
||||
### Method `getExpressionItemAuthor()`
|
||||
Should return the XPath expression for extracting an item author from the item context.
|
||||
|
||||
### Method `getExpressionItemTimestamp()`
|
||||
Should return the XPath expression for extracting an item timestamp from the item context.
|
||||
|
||||
### Method `getExpressionItemEnclosures()`
|
||||
Should return the XPath expression for extracting item enclosures (media content like images or movies) from the item context.
|
||||
|
||||
### Method `getExpressionItemCategories()`
|
||||
Should return the XPath expression for extracting an item category from the item context.
|
||||
|
||||
### Method `getSettingFixEncoding()`
|
||||
Should return the Fix encoding setting value (bool true or false).
|
||||
|
||||
## Methods for providing feed data
|
||||
Those methods are invoked for providing the HTML source as a base for applying the XPath expressions as well as feed meta data as the title and icon.
|
||||
|
||||
### Method `provideWebsiteContent()`
|
||||
This method should return the HTML source as a base for the XPath expressions. Usually it merely returns the HTML content of the URL specified in the constant `FEED_SOURCE_URL` retrieved by curl. Some sites however require user authentication mechanisms, the use of special cookies and/or headers, where the direct retrival using standard curl would not suffice. In that case this method should be overridden and take care of the page retrival.
|
||||
|
||||
### Method `provideFeedTitle()`
|
||||
This method should provide the feed title. Usually the XPath expression defined in `XPATH_EXPRESSION_FEED_TITLE` is used for extracting the title directly from the page source.
|
||||
|
||||
### Method `provideFeedIcon()`
|
||||
This method should provide the feed title. Usually the XPath expression defined in `XPATH_EXPRESSION_FEED_ICON` is used for extracting the title directly from the page source.
|
||||
|
||||
### Method `provideFeedItems()`
|
||||
This method should provide the feed items. Usually the XPath expression defined in `XPATH_EXPRESSION_ITEM` is used for extracting the items from the page source. All other XPath expressions are applied on a per-item basis, item by item, and only on the item's contents.
|
||||
|
||||
## Methods for formatting and filtering feed item attributes
|
||||
The following methods are invoked after extraction of the feed items from the source. Each of them expect one parameter, the value of the corresponding field, which then can be processed and transformed by the method. You can override these methods in order to format or filter parts of the feed output.
|
||||
|
||||
### Method `formatItemTitle()`
|
||||
Accepts the items title values as parameter, processes and returns it. Should return a string.
|
||||
|
||||
### Method `formatItemContent()`
|
||||
Accepts the items content as parameter, processes and returns it. Should return a string.
|
||||
|
||||
### Method `formatItemUri()`
|
||||
Accepts the items link URL as parameter, processes and returns it. Should return a string.
|
||||
|
||||
### Method `formatItemAuthor()`
|
||||
Accepts the items author as parameter, processes and returns it. Should return a string.
|
||||
|
||||
### Method `formatItemTimestamp()`
|
||||
Accepts the items creation timestamp as parameter, processes and returns it. Should return a unix timestamp as integer.
|
||||
|
||||
### Method `cleanImageUrl()`
|
||||
Method invoked for cleaning feed icon and item image URL's. Extracts the image URL from the passed parameter, stripping any additional content. Furthermore makes sure that relative image URL's get transformed to absolute ones.
|
||||
|
||||
### Method `fixEncoding()`
|
||||
Only invoked when class constant `SETTING_FIX_ENCODING` is set to true. It then passes all extracted string values through PHP's `utf8_decode` function.
|
||||
|
||||
### Method `generateItemId()`
|
||||
This method plays in important role for generating feed item ids for all extracted items. Every feed item needs an unique identifier (Uid), so that your feed reader updates the original item instead of adding a duplicate in case an items content is updated on the source site. Usually the items link URL is a good candidate the the Uid.
|
||||
|
||||
***
|
||||
|
||||
# Template
|
||||
|
||||
Use this template to create your own bridge. Please remove any unnecessary comments and parameters.
|
||||
|
||||
```PHP
|
||||
<?php
|
||||
|
||||
class TestBridge extends XPathAbstract {
|
||||
const NAME = 'Test';
|
||||
const URI = 'https://www.unbemerkt.eu/de/blog/';
|
||||
const DESCRIPTION = 'Test';
|
||||
const MAINTAINER = 'your name';
|
||||
const CACHE_TIMEOUT = 3600;
|
||||
|
||||
const FEED_SOURCE_URL = 'https://www.unbemerkt.eu/de/blog/';
|
||||
const XPATH_EXPRESSION_ITEM = '/html[1]/body[1]/section[1]/section[1]/div[1]/div[1]/div[1]/div[1]/div[1]/div[*]/article[1]';
|
||||
const XPATH_EXPRESSION_ITEM_TITLE = './/a[@target="_self"]';
|
||||
const XPATH_EXPRESSION_ITEM_CONTENT = './/div[@class="post-content"]';
|
||||
const XPATH_EXPRESSION_ITEM_URI = './/a[@class="more-btn"]/@href';
|
||||
const XPATH_EXPRESSION_ITEM_AUTHOR = '/html[1]/body[1]/section[1]/div[2]/div[1]/div[1]/h1[1]';
|
||||
const XPATH_EXPRESSION_ITEM_TIMESTAMP = './/time/@datetime';
|
||||
const XPATH_EXPRESSION_ITEM_ENCLOSURES = './/img/@data-src';
|
||||
const SETTING_FIX_ENCODING = false;
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
A _Bridge_ is an class that allows **RSS-Bridge** to create an RSS-feed from a website. A _Bridge_ represents one element on the [Welcome screen](../01_General/04_Screenshots.md) and covers one or more sites to return feeds for. It is developed in a PHP file located in the `bridges/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)) and extends one of the base classes of **RSS-Bridge**:
|
||||
|
||||
Base class | Description
|
||||
-----------|------------
|
||||
[`BridgeAbstract`](./02_BridgeAbstract.md) | This class is intended for standard _Bridges_ that need to filter HTML pages for content.
|
||||
[`FeedExpander`](./03_FeedExpander.md) | This class is an extension of `HttpCachingBridgeAbstract`, designed to load existing feeds into **RSS-Bridge**
|
||||
[`XPathAbstract`](./04_XPathAbstract.md) | This class is meant as an alternative base class for bridge implementations. It offers preliminary functionality for generating feeds based on _XPath expressions_.
|
||||
|
||||
For more information about how to create a new _Bridge_, read [How to create a new Bridge?](./01_How_to_create_a_new_bridge.md)
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
# getInput
|
||||
The `getInput` function is used to receive a value for a parameter, specified in `const PARAMETERS`
|
||||
|
||||
```PHP
|
||||
$this->getInput('your input name here');
|
||||
```
|
||||
|
||||
`getInput` will either return the value for your parameter or `null` if the parameter is unknown or not specified.
|
||||
|
||||
# getContents
|
||||
The `getContents` 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);
|
||||
```
|
||||
|
||||
# getSimpleHTMLDOM
|
||||
The `getSimpleHTMLDOM` function is a wrapper for 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');
|
||||
```
|
||||
# getSimpleHTMLDOMCached
|
||||
The `getSimpleHTMLDOMCached` function does the same as the [`getSimpleHTMLDOM`](#getsimplehtmldom) 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.
|
||||
|
||||
# returnError
|
||||
**Notice:** Whenever possible make use of [`returnClientError`](#returnclienterror) or [`returnServerError`](#returnservererror)
|
||||
|
||||
The `returnError` 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.
|
||||
|
||||
# returnClientError
|
||||
The `returnClientError` 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.
|
||||
|
||||
# returnServerError
|
||||
The `returnServerError` 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...)
|
||||
|
||||
# defaultLinkTo
|
||||
Automatically replaces any relative URL in a given string or DOM object (i.e. the one returned by [getSimpleHTMLDOM](#getsimplehtmldom)) with an absolute URL.
|
||||
|
||||
```php
|
||||
defaultLinkTo ( mixed $content, string $server ) : object
|
||||
```
|
||||
|
||||
Returns a DOM object (even if provided a string).
|
||||
|
||||
**Remarks**
|
||||
|
||||
* Only handles `<a>` and `<img>` tags.
|
||||
|
||||
**Example**
|
||||
|
||||
```php
|
||||
$html = '<img src="/blob/master/README.md">';
|
||||
|
||||
$html = defaultLinkTo($html, 'https://www.github.com/rss-bridge/rss-bridge'); // Using custom server
|
||||
$html = defaultLinkTo($html, $this->getURI()); // Using bridge URL
|
||||
|
||||
// Output
|
||||
// <img src="https://www.github.com/rss-bridge/rss-bridge/blob/master/README.md">
|
||||
```
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
Create a new file in the `caches/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)).
|
||||
|
||||
The file must be named according to following specification:
|
||||
|
||||
* It starts with the type
|
||||
* The file name must end with 'Cache'
|
||||
* The file type must be PHP, written in small letters (seriously!) ".php"
|
||||
|
||||
**Examples:**
|
||||
|
||||
Type | Filename
|
||||
-----|---------
|
||||
File | FileCache.php
|
||||
MySQL | MySQLCache.php
|
||||
|
||||
The file must start with the PHP tags and end with an empty line. The closing tag `?>` is [omitted](http://php.net/basic-syntax.instruction-separation).
|
||||
|
||||
Example:
|
||||
|
||||
```PHP
|
||||
<?PHP
|
||||
// PHP code here
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
The `CacheInterface` interface defines functions that need to be implemented. To create a new cache that implements `CacheInterface` you must implement following functions:
|
||||
|
||||
* [loadData](#the-loaddata-function)
|
||||
* [saveData](#the-savedata-function)
|
||||
* [getTime](#the-gettime-function)
|
||||
* [purgeCache](#the-purgecache-function)
|
||||
|
||||
Find a [template](#template) at the end of this file.
|
||||
|
||||
# Functions
|
||||
|
||||
## The `loadData` function
|
||||
|
||||
This function loads data from the cache and returns the data in the same format provided to the [saveData](#the-savedata-function) function.
|
||||
|
||||
```PHP
|
||||
loadData(): mixed
|
||||
```
|
||||
|
||||
## The `saveData` function
|
||||
|
||||
This function stores the given data into the cache and returns the object instance.
|
||||
|
||||
```PHP
|
||||
saveData(mixed $data): self
|
||||
```
|
||||
|
||||
## The `getTime` function
|
||||
|
||||
This function returns the last write time for the cache, or `false` if the cache does not yet exist. Please notice that 'cache' refers to one specific item in the cache repository and might require additional data to identify a specific item (introduce custom functions where necessary!).
|
||||
|
||||
```PHP
|
||||
getTime(): int, false
|
||||
```
|
||||
|
||||
## The `purgeCache` function
|
||||
|
||||
This function removes any data from the cache that is not within the given duration. The duration is specified in seconds and defines the period between now and the oldest item to keep.
|
||||
|
||||
```PHP
|
||||
purgeCache(int $duration): null
|
||||
```
|
||||
|
||||
# Template
|
||||
|
||||
This is the bare minimum template for a new cache:
|
||||
|
||||
```PHP
|
||||
<?php
|
||||
class MyTypeCache implements CacheInterface {
|
||||
public function loadData(){
|
||||
// Implement your algorithm here!
|
||||
return null;
|
||||
}
|
||||
|
||||
public function saveData($data){
|
||||
// Implement your algorithm here!
|
||||
|
||||
return $this;
|
||||
}
|
||||
|
||||
public function getTime(){
|
||||
// Implement your algorithm here!
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
public function purgeCache($duration){
|
||||
// Implement your algorithm here!
|
||||
}
|
||||
}
|
||||
// Imaginary empty line!
|
||||
```
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
A _Cache_ is a class that allows **RSS-Bridge** to store fetched data in a local storage area on the server. Cache imlementations are placed in the `caches/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)). A cache must implement the [`CacheInterface`](../07_Cache_API/02_CacheInterface.md) interface.
|
||||
|
||||
For more information about how to create a new `Cache`, read [How to create a new cache?](../07_Cache_API/01_How_to_create_a_new_cache.md)
|
||||
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
Create a new file in the `formats/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)).
|
||||
|
||||
The file must be named according to following specification:
|
||||
|
||||
* It starts with the type
|
||||
* The file name must end with 'Format'
|
||||
* The file type must be PHP, written in small letters (seriously!) ".php"
|
||||
|
||||
**Examples:**
|
||||
|
||||
Type | Filename
|
||||
-----|---------
|
||||
Atom | AtomFormat.php
|
||||
Html | HtmlFormat.php
|
||||
|
||||
The file must start with the PHP tags and end with an empty line. The closing tag `?>` is [omitted](http://php.net/basic-syntax.instruction-separation).
|
||||
|
||||
Example:
|
||||
|
||||
```PHP
|
||||
<?PHP
|
||||
// PHP code here
|
||||
// This line is empty (just imagine it!)
|
||||
```
|
||||
|
|
@ -0,0 +1,146 @@
|
|||
The `FormatInterface`interface defines functions that need to be implemented by all formats:
|
||||
|
||||
* [display](#the-display-function)
|
||||
* [stringify](#the-stringify-function)
|
||||
* [setItems](#the-setitems-function)
|
||||
* [getItems](#the-getitems-function)
|
||||
* [setCharset](#the-setcharset-function)
|
||||
* [getCharset](#the-getcharset-function)
|
||||
* [setExtraInfos](#the-setextrainfos-function)
|
||||
* [getExtraInfos](#the-getextrainfos-function)
|
||||
* [getMimeType](#the-getmimetype-function)
|
||||
|
||||
Find a [template](#template) at the end of this file
|
||||
|
||||
# Functions
|
||||
|
||||
## The `display` function
|
||||
|
||||
The `display` function shows the contents to the user and must return the object instance.
|
||||
|
||||
```PHP
|
||||
display(): self
|
||||
```
|
||||
|
||||
## The `stringify` function
|
||||
|
||||
The `stringify` function returns the items received by [`setItems`](#the-setitem-function) as string.
|
||||
|
||||
```PHP
|
||||
stringify(): string
|
||||
```
|
||||
|
||||
## The `setItems` function
|
||||
|
||||
The `setItems` function receives an array of items generated by the bridge and must return the object instance. Each item represents an entry in the feed. For more information refer to the [collectData](../05_Bridge_API/02_BridgeAbstract.md#collectdata) function.
|
||||
|
||||
```PHP
|
||||
setItems(array $items): self
|
||||
```
|
||||
|
||||
## The `getItems` function
|
||||
|
||||
The `getItems` function returns the items previously set by the [`setItems`](#the-setitems-function) function. If no items where set previously this function returns an error.
|
||||
|
||||
```PHP
|
||||
getItems(): array
|
||||
```
|
||||
|
||||
## The `setCharset` function
|
||||
|
||||
The `setCharset` function receives the character set value as string and returns the object instance.
|
||||
|
||||
```PHP
|
||||
setCharset(string): self
|
||||
```
|
||||
|
||||
## The `getCharset` function
|
||||
|
||||
The `getCharset` function returns the character set value.
|
||||
|
||||
```PHP
|
||||
getCharset(): string
|
||||
```
|
||||
|
||||
## The `setExtraInfos` function
|
||||
|
||||
The `setExtraInfos` function receives an array of elements with additional information to generate format outputs and must return the object instance.
|
||||
|
||||
```PHP
|
||||
setExtraInfos(array $infos): self
|
||||
```
|
||||
|
||||
Currently supported information are:
|
||||
|
||||
Name | Description
|
||||
-----|------------
|
||||
`name` | Defines the name as generated by the bridge
|
||||
`uri` | Defines the URI of the feed as generated by the bridge
|
||||
|
||||
## The `getExtraInfos` function
|
||||
|
||||
The `getExtraInfos` function returns the information previously set via the [`setExtraInfos`](#the-setextrainfos-function) function.
|
||||
|
||||
```PHP
|
||||
getExtraInfos(): array
|
||||
```
|
||||
|
||||
## The `getMimeType` function
|
||||
|
||||
The `getMimeType` function returns the expected [MIME type](https://en.wikipedia.org/wiki/Media_type#Common_examples) of the format's output.
|
||||
|
||||
```PHP
|
||||
getMimeType(): string
|
||||
```
|
||||
|
||||
# Template
|
||||
|
||||
This is a bare minimum template for a format:
|
||||
|
||||
```PHP
|
||||
<?php
|
||||
class MyTypeFormat implements FormatInterface {
|
||||
private $items;
|
||||
private $charset;
|
||||
private $extraInfos;
|
||||
|
||||
public function stringify(){
|
||||
// Implement your code here
|
||||
return ''; // Return items as string
|
||||
}
|
||||
|
||||
public function display(){
|
||||
// Implement your code here
|
||||
echo $this->stringify();
|
||||
return $this;
|
||||
}
|
||||
|
||||
public function setItems(array $items){
|
||||
$this->items = $items;
|
||||
return $this;
|
||||
}
|
||||
|
||||
public function getItems(){
|
||||
return $this->items;
|
||||
}
|
||||
|
||||
public function setCharset($charset){
|
||||
$this->charset = $charset;
|
||||
return $this;
|
||||
}
|
||||
|
||||
public function getCharset(){
|
||||
return $this->charset;
|
||||
}
|
||||
|
||||
public function setExtraInfos(array $infos){
|
||||
$this->extraInfos = $infos;
|
||||
return $this;
|
||||
}
|
||||
|
||||
public function getExtraInfos(){
|
||||
return $this->extraInfos;
|
||||
}
|
||||
}
|
||||
// Imaginary empty line!
|
||||
```
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
The `FormatAbstract` class implements the [`FormatInterface`](../08_Format_API/02_FormatInterface.md) interface with basic functional behavior and adds common helper functions for new formats:
|
||||
|
||||
* [setContentType](#the-setcontenttype-function)
|
||||
* [callContentType](#the-callcontenttype-function)
|
||||
* [sanitizeHtml](#the-sanitizehtml-function)
|
||||
* [array_trim](#the-array_trim-function)
|
||||
|
||||
# Functions
|
||||
|
||||
## The `setContentType` function
|
||||
|
||||
The `setContentType` function receives a string defining the content type for the HTML header and must return the object instance.
|
||||
|
||||
```PHP
|
||||
setContentType(string): self
|
||||
```
|
||||
|
||||
## The `callContentType` function
|
||||
|
||||
The `callContentType` function applies the content type to the header data and must return the object instance.
|
||||
|
||||
```PHP
|
||||
callContentType(): self
|
||||
```
|
||||
|
||||
## The `sanitizeHtml` function
|
||||
|
||||
The `sanitizeHtml` function receives an HTML formatted string and returns the string with disabled `<script>`, `<iframe>` and `<link>` tags.
|
||||
|
||||
```PHP
|
||||
sanitizeHtml(string $html): string
|
||||
```
|
||||
|
||||
## The `array_trim` function
|
||||
|
||||
The `array_trim` function receives an array of strings and returns the same array with all elements trimmed (like using the `trim` function on all elements)
|
||||
|
||||
```PHP
|
||||
array_trim(array $elements): array
|
||||
```
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
A _Format_ is an class that allows **RSS-Bridge** to turn items from a bridge into an RSS-feed format. It is developed in a PHP file located in the `formats/` folder (see [Folder structure](../04_For_Developers/03_Folder_structure.md)) and either implements the [FormatInterface](../08_Format_API/02_FormatInterface.md) interface or extends the [FormatAbstract](../08_Format_API/03_FormatAbstract.md) class.
|
||||
|
||||
For more information about how to create a new _Format_, read [How to create a new Format?](./01_How_to_create_a_new_format.md)
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
## General recommendations
|
||||
|
||||
* Use [HTTPS](https://en.wikipedia.org/wiki/HTTPS) (`https://...`) over [HTTP](https://en.wikipedia.org/wiki/HTTPS) (`http://...`) whenever possible
|
||||
|
||||
## Test a site before building a bridge
|
||||
|
||||
Some sites make use of anti-bot mechanisms (e.g.: by using JavaScript) in which case they work fine in regular browsers, but not in the PHP environment. To check if a site works with RSS-Bridge, create a new bridge using the [template](../05_Bridge_API/02_BridgeAbstract.md#template) and load a valid URL (not the base URL!).
|
||||
|
||||
**Example (using github.com)**
|
||||
|
||||
```PHP
|
||||
<?php
|
||||
class TestBridge extends BridgeAbstract {
|
||||
const NAME = 'Unnamed bridge';
|
||||
const URI = '';
|
||||
const DESCRIPTION = 'No description provided';
|
||||
const MAINTAINER = 'No maintainer';
|
||||
const PARAMETERS = array();
|
||||
const CACHE_TIMEOUT = 3600;
|
||||
|
||||
public function collectData(){
|
||||
$html = getSimpleHTMLDOM('https://github.com/rss-bridge/rss-bridge')
|
||||
or returnServerError('No contents received!');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This bridge should return an empty page (HTML format)
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
{
|
||||
"favicon": "<theme_url>img/favicon.png",
|
||||
"js": [
|
||||
"<theme_url>js/daux.min.js"
|
||||
],
|
||||
"css": [
|
||||
"<theme_url>css/theme.min.css"
|
||||
]
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,2 @@
|
|||
!function(){"use strict";function e(e){"loading"===document.readyState?document.addEventListener("DOMContentLoaded",e):e()}function t(e,t){for(var n=0;n<e.length;n++)e[n].classList.toggle("CodeToggler--hidden",t);try{localStorage.setItem("daux_code_blocks_hidden",t)}catch(e){}}function n(e,t){(null==t||t>e.length)&&(t=e.length);for(var n=0,r=new Array(t);n<t;n++)r[n]=e[n];return r}function r(e,t){var r;if("undefined"==typeof Symbol||null==e[Symbol.iterator]){if(Array.isArray(e)||(r=function(e,t){if(e){if("string"==typeof e)return n(e,t);var r=Object.prototype.toString.call(e).slice(8,-1);return"Object"===r&&e.constructor&&(r=e.constructor.name),"Map"===r||"Set"===r?Array.from(e):"Arguments"===r||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r)?n(e,t):void 0}}(e))||t&&e&&"number"==typeof e.length){r&&(e=r);var o=0,a=function(){};return{s:a,n:function(){return o>=e.length?{done:!0}:{done:!1,value:e[o++]}},e:function(e){throw e},f:a}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}var i,l=!0,c=!1;return{s:function(){r=e[Symbol.iterator]()},n:function(){var e=r.next();return l=e.done,e},e:function(e){c=!0,i=e},f:function(){try{l||null==r.return||r.return()}finally{if(c)throw i}}}}function o(e){var t=void 0!==e.preventDefault;t&&e.preventDefault();var n=function(e){for(var t=e;(t=t.parentNode)&&9!==t.nodeType;)if(1===t.nodeType&&t.classList.contains("Nav__item"))return t;throw new Error("Could not find a NavItem...")}(e.target),r=n.querySelector("ul.Nav");t&&n.classList.contains("Nav__item--open")?(r.style.height="".concat(r.scrollHeight,"px"),r.style.transitionDuration="150ms",r.style.height="0px",n.classList.remove("Nav__item--open")):t?(r.style.transitionDuration="150ms",r.addEventListener("transitionend",(function e(t){"0px"!==t.target.style.height&&(t.target.style.height="auto"),t.target.removeEventListener("transitionend",e)})),r.style.height="".concat(r.scrollHeight,"px"),n.classList.add("Nav__item--open")):r.style.height="auto"}e((function(){var e=document.querySelectorAll(".s-content pre"),n=document.querySelector(".CodeToggler");n&&(e.length?function(e,n){var r=e.querySelector(".CodeToggler__button--main");r.addEventListener("change",(function(e){t(n,!e.target.checked)}),!1);var o=!1;try{"false"===(o=localStorage.getItem("daux_code_blocks_hidden"))?o=!1:"true"===o&&(o=!0),o&&(t(n,!!o),r.checked=!o)}catch(e){}}(n,e):n.classList.add("CodeToggler--hidden"))})),e((function(){var e=document.querySelector(".Collapsible__trigger");if(e){var t=document.querySelector(".Collapsible__content");e.addEventListener("click",(function(n){t.classList.contains("Collapsible__content--open")?(t.style.height=0,t.classList.remove("Collapsible__content--open"),e.setAttribute("aria-expanded","false")):(e.setAttribute("aria-expanded","true"),t.style.transitionDuration="150ms",t.style.height="".concat(t.scrollHeight,"px"),t.classList.add("Collapsible__content--open"))}))}})),e((function(){var e=document.querySelectorAll("pre > code:not(.hljs)");if(e.length){var t=document.getElementsByTagName("head")[0],n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src="".concat(window.base_url,"daux_libraries/highlight.pack.js"),n.onload=function(t){[].forEach.call(e,window.hljs.highlightBlock)},t.appendChild(n)}})),e((function(){for(var e,t=document.querySelectorAll(".Nav__item.has-children i.Nav__arrow"),n=t.length-1;n>=0;n--)(e=t[n]).addEventListener("click",o),e.parentNode.parentNode.classList.contains("Nav__item--open")&&o({target:e});var a,i=r(document.querySelectorAll(".Nav__item__link--nopage"));try{for(i.s();!(a=i.n()).done;){a.value.addEventListener("click",o)}}catch(e){i.e(e)}finally{i.f()}}))}();
|
||||
//# sourceMappingURL=daux.min.js.map
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
{
|
||||
"title": "RSS-Bridge",
|
||||
"tagline": "The RSS feed for websites missing it",
|
||||
"author": "RSS-Bridge Contributors",
|
||||
"image": "./images/rssbridgelogo.png",
|
||||
"ignore": {
|
||||
"files": ["Work_In_Progress.md", "readme.md"],
|
||||
"folders": ["99_Theme"]
|
||||
},
|
||||
"live": {
|
||||
"clean_urls": true
|
||||
},
|
||||
"html": {
|
||||
"theme": "daux-blue",
|
||||
"breadcrumbs": true,
|
||||
"breadcrumb_separator": "Chevrons",
|
||||
"toggle_code": true,
|
||||
"date_modified": true,
|
||||
"inherit_index": true,
|
||||
|
||||
"repo": "RSS-Bridge/rss-bridge",
|
||||
"edit_on_github": "RSS-Bridge/rss-bridge/tree/master/docs",
|
||||
"google_analytics": false,
|
||||
"plausible_domain": false,
|
||||
"links": {
|
||||
"GitHub Repository": "https://github.com/RSS-Bridge/rss-bridge",
|
||||
"Help/Support/Bugs": "https://github.com/RSS-Bridge/rss-bridge/issues",
|
||||
"Docker Images": "https://github.com/RSS-Bridge/rss-bridge/pkgs/container/rss-bridge"
|
||||
},
|
||||
"powered_by": "Powered by Daux.io"
|
||||
}
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
|
|
@ -0,0 +1,19 @@
|
|||
**RSS-Bridge** is free and open source software for generating Atom or RSS feeds from websites which don't have one. It is written in PHP and intended to run on a Web server. See the [Screenshots](01_General/04_Screenshots.md) for a quick introduction to **RSS-Bridge**
|
||||
|
||||
- You want to know more about **RSS-Bridge**?
|
||||
Check out our **[project goals](01_General/01_Project-goals.md)**.
|
||||
|
||||
- You want to contribute and don't know how?
|
||||
Check out our **[How can I contribute?](01_General/02_Contribute.md)** section.
|
||||
|
||||
- You are a developer and searching for more details?
|
||||
Check out our **[For developers](04_For_Developers/index.md)** section.
|
||||
|
||||
- You want to know what is required to host **RSS-Bridge**?
|
||||
Check out the **[Requirements](01_General/03_Requirements.md)** section.
|
||||
|
||||
- You want to host **RSS-Bridge**?
|
||||
Check out the **[For hosts](03_For_Hosts/index.md)** section.
|
||||
|
||||
- You have questions?
|
||||
Check out the **[FAQ](01_General/05_FAQ.md)**.
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
# RSS-Bridge Documentation
|
||||
|
||||
This folder contains the RSS-Bridge documentation. It uses daux.io to compile the static website for gh pages.
|
||||
|
||||
See the language folders for the .md files
|
||||
|
||||
## Important links
|
||||
|
||||
Daux.io documentation : https://daux.io/Getting_Started.html
|
||||
Loading…
Reference in New Issue