Download the PHP package justinholtweb/craft-airwave without Composer

Airwave

Read the web's feeds. Publish your own.

Airwave is an RSS, Atom and JSON Feed plugin for Craft CMS 5. It does both directions, and the halves share one data model — so a feed you pull in can be re-broadcast on a feed you publish, without writing a template.

• In. Subscribe to feeds, filter them, cache their items, render them on a page, and — on Pro — turn them into entries.
• Out. Publish RSS, Atom or JSON Feed from any element query, or from the items Airwave has collected.

If you have moved a site off WordPress and miss Feedzy's shortcode, {airwave:handle:render} pasted into any rich-text field renders a feed exactly where you put it.

Requirements

Craft CMS 5.3+ and PHP 8.2+.

Installation

Editions

A licence that lapses does not break anything. Airwave downgrades on the way out: full content serves as summaries, an Atom channel serves RSS, a merged stream serves its first feed. Stored configuration is untouched, so renewing restores exactly what was there.

Adding a feed

Airwave → Feeds → New feed. Paste a feed URL, or paste the site address and press Find the feed — Airwave reads the page and offers whatever it advertises.

RSS 2.0, RSS 1.0 (RDF), Atom 1.0 and JSON Feed all work, and Airwave sniffs the document rather than trusting the file extension or the Content-Type, because feeds are served as text/html more often than anyone would like.

Refreshing

Feeds refresh on their own interval (hourly by default). A feed that has never been fetched is read inline the first time something asks for it, so a template does not render an empty box; a feed that is merely stale queues a job, so a slow publisher can never become a slow page.

To drive it from cron instead, turn off Refresh on the front end in the settings and run:

--due fetches only the feeds whose own interval has elapsed, so the schedule stays per feed rather than becoming whatever the crontab says.

Putting a feed on a page

The one-liner:

Several feeds as one stream, newest first (Pro):

The items themselves, if you would rather write your own markup:

In rich text

Every feed has a reference tag. Paste it into a CKEditor, Redactor or plain HTML field:

Craft parses reference tags over every rich-text value before it reaches your template, so this works with no template changes and no per-editor integration.

With a field

Add a Feed field to an entry type and an author can choose which feeds appear on that page. Output it directly:

Styling

Airwave ships one small stylesheet that sets layout and nothing else — no colours, no fonts, so a feed looks like the page it is on. Override the custom properties:

Or take the markup over completely by putting your own at templates/_airwave/items.twig. Airwave finds it automatically and hands it items, options, source and meta. Start by copying src/templates/_render/items.twig out of the plugin.

Item properties

Publishing a feed

Airwave → Channels → New channel. A channel is a URI on your site plus enough configuration to answer it.

Broadcast your own content — pick a section, and Airwave works the rest out: the entry title, its URL, a summary or excerpt field, the author, and the first image field it finds. On Pro you can replace any of those with an object template:

Or broadcast the feeds Airwave has collected, which is how you publish a curated "best of the web" feed without writing anything at all.

In your <head>:

and anywhere else:

Published feeds are cached and send Cache-Control accordingly, so well-behaved readers stop asking. Aggregated items are purified on the way out as well as on the way in — a channel that re-broadcasts somebody else's markup is republishing it under your domain.

Importing items as entries (Pro)

On a feed's Import tab, choose a section and entry type, decide whether new entries arrive enabled or disabled, and map the parts of an item onto your fields.

Map with a token — summary, content, url, author, image, categories, guid, domain, publishedAt — or with a Twig template for anything else:

Categories map onto a Tags field by creating tags, and onto a Categories field by matching existing ones — an aggregator inventing branches in your category tree is not a favour.

Nothing is ever imported twice. Dedupe is by the row that records this item became that entry, not by title or URL, so it survives the entry being renamed, moved or edited. Deleting the entry does not invite the article back on the next refresh.

Runs are capped (25 items by default) and continue in the background, so a first import of a feed with 800 items in it is a chain of small jobs rather than one request that never ends. Press Show what would be imported first — it writes nothing.

The command line

airwave/feeds/test is the one to reach for when a feed is not behaving: it fetches, parses and prints what Airwave made of it, without touching the site.

Settings

Most settings are defaults a single feed can override. Two are deliberately site-wide, because they are safety rails rather than preferences:

• Allow private network fetches — off. A feed URL is user input in any site where a non-admin can add one, and http://169.254.169.254/… is the standard way that ends badly. Airwave resolves every host and refuses private and reserved addresses, and re-checks every hop of a redirect chain. Turn this on only for a feed on your own network.
• Clean incoming HTML — on. Every item goes through HTML Purifier before it can reach a page. Airwave's configuration allows images, links, headings, lists and video embeds, and blocks forms, style blocks, scripts and id attributes that would collide with your page. Point it at your own config/htmlpurifier/*.json if you want something else.

There is deliberately no password field for a private feed. Add a request header on the feed instead — header values are run through App::parseEnv():

so the token stays in .env rather than in the database and in every backup of it.

Permissions

Testing

Inside the plugin-testing harness:

Licence

Proprietary. © Justin Holt.