Bridges/CLAUDE.md

Bridge Documentation

This directory contains custom RSS-Bridge implementations. For detailed documentation on creating and working with bridges, refer to the comprehensive guides in the Bridge_Docs/ folder.

Creating a New Bridge File

File: Bridge_Docs/01_How_to_create_a_new_bridge.md

Basic guide for creating a new bridge file with proper structure. Covers the mandatory declare(strict_types=1); declaration and provides a minimal working example using getSimpleHTMLDOM() to scrape content.

BridgeAbstract - Standard Bridge Base Class

File: Bridge_Docs/02_BridgeAbstract.md

Complete reference for BridgeAbstract, the base class for standard bridges. This is your primary resource for understanding:

• Required constants (NAME, URI, DESCRIPTION, MAINTAINER)
• How to define PARAMETERS for user input (text, number, list, checkbox)
• The collectData() method and item structure (title, uri, content, timestamp, author, etc.)
• Context handling with $this->queriedContext
• Helper methods like saveCacheValue() and loadCacheValue()
• Optional methods to override (getName, getURI, getIcon, detectParameters)

Use this when: Creating any standard bridge that scrapes HTML content directly.

FeedExpander - RSS/Atom Feed Extension

File: Bridge_Docs/03_FeedExpander.md

Specialized class for bridges that consume existing RSS/Atom feeds and enhance or modify them. Extends BridgeAbstract with feed parsing capabilities.

Key features:

• Automatically parses RSS 1.0, RSS 2.0, and Atom 1.0 feeds
• Override parseItem() to modify individual feed items
• Call $this->collectExpandableDatas('feed_url') in collectData()
• Can limit number of items fetched

Use this when: Working with sites that already provide feeds but need enhancement (e.g., content modification, filtering, or expanding truncated content).

WebDriverAbstract - JavaScript/XHR-Heavy Sites

File: Bridge_Docs/04_WebDriverAbstract.md

For websites that heavily rely on JavaScript or XMLHttpRequest (XHR) to load content. Uses Selenium WebDriver with a real browser instance.

Important notes:

• Requires a running Selenium server (Docker image or local ChromeDriver)
• Very resource-intensive - only use when other methods fail
• Must explicitly wait for elements to appear after page loads or interactions
• Always call $this->cleanUp() in a finally block

Use this when: The target website loads content dynamically via JavaScript and cannot be scraped with standard HTML parsing methods.

XPathAbstract - XPath-Based Bridges

File: Bridge_Docs/05_XPathAbstract.md

Simplified bridge creation using XPath expressions. Ideal if you're familiar with XPath syntax.

Define these constants with XPath expressions:

• FEED_SOURCE_URL - The source webpage
• XPATH_EXPRESSION_ITEM - Selects each article/item container
• XPATH_EXPRESSION_ITEM_TITLE - Extracts title from item context
• XPATH_EXPRESSION_ITEM_CONTENT - Extracts content from item context
• XPATH_EXPRESSION_ITEM_URI - Extracts link URL
• Additional expressions for author, timestamp, enclosures, categories

Optional methods to override for formatting: formatItemTitle(), formatItemContent(), formatItemUri(), etc.

Use this when: You can identify the content you need using XPath expressions, making bridge creation declarative and concise.