Getting Started with HuntFeed

Install and configure HuntFeed in minutes. Follow this step-by-step guide to start using the PHP RSS/Atom feed library with WebSub support.

Prerequisites

System Requirements

PHP 8.1+

Modern PHP features and performance

cURL Extension

For HTTP requests

SimpleXML

For XML feed parsing

JSON Extension

For JSON feed support

Installation

1

Install via Composer

HuntFeed is available via Packagist. Install it using Composer:

composer require hosseinhunta/huntfeed
2

Include Autoloader

Include Composer's autoloader in your PHP file:

require 'vendor/autoload.php';

use Hosseinhunta\Huntfeed\Hub\FeedManager;
use Hosseinhunta\Huntfeed\WebSub\WebSubManager;
3

Verify Installation

Run a quick test to verify HuntFeed is working correctly:

require 'vendor/autoload.php';

$manager = new \Hosseinhunta\Huntfeed\Hub\FeedManager();
echo "✓ HuntFeed installed successfully!";

Configuration

Note: For production deployment, use environment variables or a configuration file.

Basic Configuration

Configure HuntFeed with your specific settings:

$manager = new FeedManager();

// Set configuration options
$manager->setConfig('cache_ttl', 3600); // 1 hour cache
$manager->setConfig('user_agent', 'MyApp/1.0');
$manager->setConfig('timeout', 30); // 30 second timeout

// Enable debug mode (development only)
$manager->setConfig('debug', true);

Environment Variables

For production, use environment variables:

# HuntFeed Configuration
WEBSUB_ENABLED=true
WEBSUB_CALLBACK_URL=https://your-domain.com/websub-callback.php
WEBSUB_AUTO_SUBSCRIBE=true
WEBSUB_SECRET=${WEBSUB_SECRET_KEY}
HTTPS_REQUIRED=true
DEBUG_MODE=false

Basic Usage

Register Your First Feed

require 'vendor/autoload.php';

use Hosseinhunta\Huntfeed\Hub\FeedManager;

$manager = new FeedManager();

// Register a single feed
$manager->registerFeed(
    'hacker_news',
    'https://news.ycombinator.com/rss',
    [
        'category' => 'Technology',
        'interval' => 300, // Check every 5 minutes
        'description' => 'Hacker News RSS Feed'
    ]
);

// Or register multiple feeds at once
$manager->registerFeeds([
    'techcrunch' => [
        'url' => 'https://techcrunch.com/feed/',
        'category' => 'Technology',
        'interval' => 600
    ],
    'bbc_news' => [
        'url' => 'https://bbc.com/news/world/rss.xml',
        'category' => 'News',
        'interval' => 900
    ]
]);

Check for Updates

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

// Process new items
foreach ($updates as $feedId => $newItems) {
    echo "Feed: $feedId has " . count($newItems) . " new items\n";
    
    foreach ($newItems as $item) {
        echo "New item: " . $item->title . "\n";
        echo "Link: " . $item->link . "\n";
        echo "Published: " . $item->publishedAt->format('Y-m-d H:i') . "\n\n";
    }
}

Advanced Setup

WebSub Configuration

Enable real-time push notifications with WebSub:

use Hosseinhunta\Huntfeed\WebSub\WebSubManager;

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

// Configure WebSub settings
$webSubManager
    ->setAutoSubscribe(true)
    ->setFallbackToPolling(true)
    ->setLeaseSeconds(86400); // 24-hour subscription

// Register feeds with WebSub
$webSubManager->registerFeedWithWebSub(
    'tech_news',
    'https://example.com/feed.xml'
);
Important: Ensure your callback URL is publicly accessible and uses HTTPS in production.

Event Handlers

Set up event handlers for real-time notifications:

// Handle new items
$manager->on('item:new', function($data) {
    $item = $data['item'];
    $feedId = $data['feedId'];
    
    // Send notification
    sendNotification("New item in $feedId: " . $item->title);
    
    // Log to database
    logToDatabase($item);
});

// Handle feed updates
$manager->on('feed:updated', function($data) {
    echo "Feed {$data['feedId']} was updated\n";
});

// Handle subscription events
$manager->on('websub:subscribed', function($data) {
    echo "WebSub subscription successful for {$data['feedId']}\n";
});

Verification

Run Tests

Verify your installation by running the test suite:

# Run comprehensive tests
php vendor/bin/phpunit tests/

# Or run the quick start test
php tests/QuickStartTest.php

Quick Verification Script

Create a simple verification script:

require 'vendor/autoload.php';

try {
    $manager = new \Hosseinhunta\Huntfeed\Hub\FeedManager();
    
    // Test feed fetching
    $manager->registerFeed('test', 'https://news.ycombinator.com/rss');
    $updates = $manager->checkUpdates();
    
    echo "✓ HuntFeed is working correctly!\n";
    echo "✓ Feed registered successfully\n";
    echo "✓ " . count($updates) . " feeds checked\n";
    
    // Export test
    $json = $manager->export('json');
    echo "✓ JSON export working\n";
    
    echo "\nAll tests passed! 🎉\n";
    
} catch (Exception $e) {
    echo "✗ Error: " . $e->getMessage() . "\n";
}

Next Steps

Now that you have HuntFeed installed, check out the WebSub Guide for real-time push notifications or browse the Examples for practical use cases.