README

🔥 Real-Time RSS/Atom Feed Management with WebSub Support

HuntFeed is a production-ready, event-driven PHP library for consuming, normalizing, and distributing RSS, Atom, and WebSub feed updates with real-time push notifications. Perfect for feed aggregators, news readers, and content monitoring applications.

✨ Why Choose HuntFeed?

📊 Performance Benchmarks

🆚 HuntFeed vs SimplePie

🛡️ Trust & Production Ready

✅ Security Features

• HMAC-SHA1 Verification – All WebSub notifications are signed
• SSL/TLS Enforcement – HTTPS required in production
• Challenge Verification – Prevents unauthorized subscriptions
• No Data Leakage – Sensitive data never logged

✅ Enterprise-Grade

• 12+ Comprehensive Tests – All passing
• PSR-12 Compliant Code – Industry standards
• 2000+ Lines Documentation – Complete coverage
• Active Maintenance – Regular updates and security patches

📦 Quick Installation

Requirements

• PHP 8.1+ (Takes advantage of modern PHP features)
• cURL extension (For HTTP requests)
• SimpleXML extension (For XML parsing)
• JSON extension (For JSON handling)

No external dependencies for core functionality!

composer require hosseinhunta/huntfeed

Basic Usage - Get Started in 30 Seconds

<?php
require 'vendor/autoload.php';

use Hosseinhunta\Huntfeed\Hub\FeedManager;

$manager = new FeedManager();

// Register your feeds
$manager->registerFeeds([
    'tech' => [
        'url' => 'https://news.ycombinator.com/rss',
        'category' => 'Technology',
        'interval' => 300 // 5 minutes
    ]
]);

// Check for updates
$updates = $manager->checkUpdates();

// Export to any format
$json = $manager->export('json'); // Perfect for APIs
$rss = $manager->export('rss');   // For feed readers

🔧 Advanced Features

📡 Multi-Format Feed Support

• RSS 2.0 - Dublin Core, Media RSS, Content Encoded
• Atom 1.0 - Full specification support
• JSON Feed - Modern JSON-based format
• RDF/RSS 1.0 - Legacy format support
• GeoRSS - Geographic-aware feeds
• Auto-detection - Automatically identifies feed format

🔔 WebSub Implementation

use Hosseinhunta\Huntfeed\WebSub\WebSubManager;

$webSubManager = new WebSubManager(
    $manager,
    'https://your-domain.com/callback.php'
);

$webSubManager->setAutoSubscribe(true);
$webSubManager->registerFeedWithWebSub('tech', 'https://example.com/feed.xml');

📊 Smart Feed Management

• Duplicate prevention - 3 fingerprinting strategies
• Category organization - Multi-category support
• Advanced search - Search across titles, content, categories
• Event-driven architecture - Hook into feed updates
• Batch processing - Handle multiple feeds efficiently (Soon)

🎨 7 Export Formats

// Export to any format your application needs
$manager->export('json');      // API responses
$manager->export('rss');       // RSS feed generation
$manager->export('atom');      // Atom feed generation
$manager->export('jsonfeed');  // JSON Feed format
$manager->export('csv');       // Excel/database import
$manager->export('html');      // Web display
$manager->export('text');      // Plain text

🎯 Use Cases

🤖 Telegram Bots

$manager->on('item:new', function($data) {
    sendTelegramAlert($data['item']);
});

📱 Mobile App Backends

// API endpoint
$app->get('/api/feeds', function() use ($manager) {
    return $manager->export('json');
});

📰 News Aggregators

$manager->registerFeeds([
    'tech' => 'https://techcrunch.com/feed/',
    'news' => 'https://bbc.com/news/world/rss.xml',
    'sports' => 'https://espn.com/rss'
]);

🔍 Content Monitoring

Monitor competitors, keywords, or industry news with instant notifications.

🧪 Testing & Quality

# Run comprehensive test suite
php tests/QuickStartTest.php

# Run WebSub-specific tests
php tests/WebSubTest.php

# Run polling tests
php tests/poling-test.php

All 12+ tests pass - Production-ready code.

🔒 Security Features

✅ Enterprise-Grade Security

• HMAC-SHA1 Verification - All WebSub notifications are signed
• SSL/TLS Enforcement - HTTPS required in production
• Challenge Verification - Prevents unauthorized subscriptions
• Input Validation - All URLs and content validated
• XML Safety - XXE attack prevention
• No Data Leakage - Sensitive data never logged

🔐 Best Practices Included

// Production configuration
$manager->setConfig('https_required', true);
$manager->setConfig('verify_ssl', true);
$manager->setConfig('hmac_secret', getenv('WEBSUB_SECRET'));

📚 Documentation

Getting Started

• Quick Start Guide – 5-minute setup
• WebSub Implementation – Complete 2000+ line guide
• API Reference – Full method documentation

Production Deployment

• Security Policy – Enterprise security
• SSL Certificate Fix – Troubleshooting
• Architecture Overview – System design

👥 Community & Support

📞 Get Help

• GitHub Issues - Bug reports
• GitHub Discussions - Questions & ideas
• Email: hosseinhunta@gmail.com

🤝 Contributing

We welcome contributions! See our:

• Contributing Guide
• Code of Conduct

📊 Changelog & Roadmap

✅ Version 1.0.0 (Current)

• Complete feed management system
• Full WebSub implementation
• Multi-format export
• Production-ready security

🚧 Roadmap

• v1.1.0: Database persistence for subscriptions
• v1.2.0: Redis caching, batch processing
• v2.0.0: REST API, GraphQL, Dashboard UI

See full Changelog

📄 License

MIT License - Free for commercial and personal use.

🎯 Ready for Production?

# 1. Install
composer require hosseinhunta/huntfeed

# 2. Run tests
php tests/QuickStartTest.php

# 3. Check the examples
php examples/WebSubExample.php

Join hundreds of developers who trust HuntFeed for their feed management needs!

⭐ Star HuntFeed on GitHub ⭐

Need help? Check our complete documentation or open an issue!