# feed-rules: include, exclude and mapping rules for imports

[feed-rules](https://github.com/IndianOpinion/feed-rules) is a WordPress plugin for sites that import items from feeds. It holds the keep, drop and mapping rules for any importer in one place, with a test state and a test screen. It is MIT licensed, and v0.1.0 was released on 15 November 2026.

## The problem

A site that imports from feeds gets everything each feed carries: job listings, horoscopes, sponsored posts, sections it never wanted. Operators usually fix this with a keyword list inside each importer, and that has three failures.

- Every importer has its own list, syntax and blind spots. Changing importer means rewriting every rule.

- Word matching is written for English. A \b boundary treats a vowel sign in Devanagari or Tamil as a word break, so a keyword in those scripts either never matches or matches inside other words.

- Nobody can see what a rule will do before it is live, so one over-broad pattern can hold good articles with no warning.

## What it does

- Keeps or drops an item by keyword lists, regular expressions and URL prefixes, before the importer creates a post.

- Maps kept items to categories, tags and an author. Actions are exclude, include, keep, categorise, tag and author, with one to ten conditions per rule.

- Starts every new rule in a test state, where it is evaluated and logged and changes nothing.

- Shows on a test screen what a saved rule, an unsaved draft or the whole rule set would have done to the last hundred items, or to a pasted title and body.

- Works with any importer through two hooks, and ships one reference adapter built on fetch_feed() that creates drafts or pending posts only.

- Provides WP-CLI commands: list, status, test, export, import, run-feeds and reset-errors.

## How it works

An importer wraps its post insert with two calls:

$item = apply_filters('feed_rules_filter_item', [
'url' => $link, 'title' => $title, 'body' => $html, 'source_name' => 'Example Wire',
], 'my-importer');
if ($item === false) {
return; // Dropped by a rule.
}
$postId = wp_insert_post([...]);
do_action('feed_rules_apply_to_post', $postId, $item);

Text is normalised once. Scripts and styles are removed, tags are stripped with block boundaries kept as spaces, entities are decoded up to three times, bad UTF-8 is repaired, NFC is applied and whitespace is collapsed. The body is cut to a window, 2,000 characters by default.

Rules then run in list order with a fixed precedence:

- A live keep rule that matches keeps the item, whatever the other rules say.

- Otherwise the first live exclude rule that matches drops it.

- Otherwise, if any live include rule is in scope, one must match or the item is dropped.

- test rules are evaluated for every item and recorded as "would drop", "would keep" or "would map".

- A kept item collects categories, tags and an author from mapping rules and the mapping tables.

Whole words are found with Unicode letter, mark and number classes, never \b. A Hindi keyword does not match inside a longer Hindi word, and a Tamil keyword followed by a vowel sign does not match.

Each decision goes to a recent-items table (newest 100 per importer by default), to per-rule daily counters kept for 14 days, and, for kept posts, to one post meta key listing the live rules that matched. Test runs write none of this and never fire feed_rules_decided. Other hooks include feed_rules_item_text to strip importer boilerplate before matching, feed_rules_decision as a last chance to change a decision, and feed_rules_register_adapters.

## Guard rails

- It fails open. A regex that hits the PCRE backtrack limit counts as an error and the item is kept. An unreadable rule set keeps every item and shows an admin notice.

- New rules start in test. The global switch can turn the plugin off, and feed_rules_enabled filters it.

- User keywords are passed through preg_quote. User regexes are checked for delimiter and flags (only imsx, with u always added) and compiled on save.

- Every admin handler checks a capability (manage_options by default, filterable) and a nonce, and all output is escaped.

- The reference adapter never publishes. It skips URLs it has already imported or dropped.

- CSV export neutralises cells that start with formula characters, a tab or a carriage return.

## What review changed

- A live keep rule whose regex hit a PCRE limit, with no keep rule matching, let a later exclude rule drop the item, so an error removed an item. That item is now kept and the error is counted.

- When preg_replace() failed during normalisation, for example on a very large body, the failure was cast to an empty string and silently emptied the field. It now keeps the input.

- A source key longer than 191 characters, or an importer id longer than 40, made the recent-items insert fail under strict SQL modes and switched recording off for the request. Columns are now cut to width on a character boundary.

- The reference adapter's existing-post check left out trashed posts, so an item an editor trashed came back as a new draft on the next run. Trash is now included.

## Limits and what is next

- Rules never touch posts that already exist. The test screen is the way to see the effect on recent items.

- Only the first 2,000 characters of the body are matched by default.

- No language detection, duplicate detection or freshness checks, and no machine learning. Rules are deterministic.

- The reference adapter has no image handling or full-text extraction, and schedules hourly, twice daily or daily only.

- No adapter for any third-party importer ships. You write one against the interface.

- There are no open issues at the time of writing.

Test status: this is v0.1.0. The review reports 94 PHPUnit tests, PHPStan level 8 and phpcs clean on a local PHP 8.3, on stubs and mocks. The README gives about 0.7 ms for one item against 50 rules holding 5,000 keywords, from a benchmark script in the repo on synthetic data. CI has not run on GitHub yet, and the plugin has not run against a live importer. It was specified, built and reviewed in separate roles by language-model coding agents under the editor's direction.

## Install

It needs WordPress 6.4 or later and PHP 8.1 or later with mbstring and PCRE. intl is used for NFC normalisation when present.

composer require indianopinion/feed-rules

The package is not on Packagist yet, so add a Composer vcs repository entry for https://github.com/IndianOpinion/feed-rules first.

Without Composer, put the folder in wp-content/plugins/feed-rules and activate it.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [feed-rules on GitHub](https://github.com/IndianOpinion/feed-rules)

Canonical: https://indianopinion.org/blog/open-source/feed-rules/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
