path: root/README.md

# rss_dot_php

A minimal configurable RSS/Atom reader in about 400 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].

## Features

- RSS/Atom autodetection
- Multiple feeds
- Caching
- Lives in just one file
- Renders post contents
- Renders media files

## 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]["media"]`: Whether or not to render media files in the feed. Boolean. Defaults to true.
- `$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.

The HTML tree looks like this:

```html
<main>
  <!-- if $feeds[feed]["mode"] is "no_title" -->
  <article data-source="<!-- the key in $feeds this post comes from -->">
    <div class="rss-content">
      <div><!-- text content of the entry --></div>
    </div>
    <span class="rss-source">
      <a href="<!-- $feeds[feed]['home'] -->">
        <!-- the key in $feeds this post comes from -->
      </a>
    </span>
    •
    <a href="<!-- post URL -->">Source</a>
    •
    <time datetime="<!-- post date -->"><!-- post date --></time>
  </article>

  <!-- otherwise -->
  <article data-source="<!-- the key in $feeds this post comes from -->">
    <div class="rss-content">
      <h1 class="rss-title"><a href="<!-- post URL -->"><!-- post title --></a></h1>
      <div><!-- text content of the entry, if set to render --></div>
    </div>
    <span class="rss-source">
      <a href="<!-- $feeds[feed]['home'] -->">
        <!-- the key in $feeds this post comes from -->
      </a>
    </span>
    •
    <time datetime="<!-- post date -->"><!-- post date --></time>
  </article>
</main>
```

## Support

rss_dot_php has been tested to work with...

- Youtube
- Status.Cafe
- Tumblr
- Dreamwidth
- Mastodon

If you use it with something other than these 5, and it works, let me know!  
If you use it with something other than these 5, and it breaks, let me know!

I can be contacted on Bluesky as [@aleteoryx.me][bsky] and on the Fediverse as [@aleteoryx@labyrinth.zone][fedi]

[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
[bsky]: https://bsky.app/profile/aleteoryx.me
[fedi]: https://labyrinth.zone/aleteoryx