path: root/README.md

# rss_dot_php

A minimal configurable RSS/Atom reader in about 200 lines of PHP.

This tool isn't intended for standalone reading, instead it's
intended to be used as an aggregator for personal feeds, that can be
embedded into a website via an <iframe>.

You can see it in action [on my homepage][me].

## Usage

To use this tool, just download the main [`rss.php`][php] file and edit it.
Each entry in the `$feeds` array corresponds to a feed that will be
displayed. The key of the entry is the name.

The following options are supported per-feed:

- `$feeds[feed]["url"]`: **REQUIRED**: The URL of the RSS/Atom feed.
- `$feeds[feed]["home"]`: An optional homepage for the feed. Will be linked under every entry from it.
- `$feeds[feed]["mode"]`: How to display the feed, one of:
    - `"title"`: The default. Shows the title as a link to the article.
    - `"content"`: Shows the title and content.
    - `"no_title"`: Hides the title, displays the content. A link to the source is put at the bottom.
- `$feeds[feed]["allow_html"]`: Whether or not to allow html in the content area, stripped. Boolean. Defaults to true.
- `$feeds[feed]["ttl"]`: How long to cache the feed for, in seconds. Defaults to 1 hour.
- `$feeds[feed]["linkrel"]`: For Atom, which `rel=` value to prefer when getting a link. Defaults to alternate.

The remaining config options are set on the `$config` array, and are documented inside
the file.

## Caching

The cache uses PHP's builtin `serialize`/`unserialize` functions, and stores entries at
`{$config["cache_dir"]}/{md5($feed["url"])}`. Only one cache file will ever exist for
a feed, and it is safe for multiple instances to share a cache directory, even if feed
URLs overlap.

## Styling

[`aleteoryx.css`][css] contains an example stylesheet.

[me]: https://aleteoryx.me
[php]: https://git.aleteoryx.me/cgit/rss_dot_php/tree/rss.php
[css]: https://git.aleteoryx.me/cgit/rss_dot_php/tree/aleteoryx.css