BRJ organisation

A lightweight PHP library for fetching, parsing, and caching WordPress RSS feeds with automatic image handling.

The library provides a simple API to download blog posts from any WordPress RSS feed, automatically caches the content to minimize network requests, and handles image downloading and local storage for improved performance and reliability.

• Automatic RSS feed parsing - Extracts posts with title, description, link, date, author, and categories
• Smart caching system - Feed content is cached with configurable expiration time (default: 2 hours)
• Image management - Automatically downloads and stores post images locally
• Pagination support - Built-in limit and offset parameters for easy pagination
• Zero-config usage - Works out of the box without any dependencies when used standalone
• Nette Framework integration - Full DI container support with configurable extension
• Security-first image handling - Validates image types before saving to prevent malicious files

The library consists of four main components that work together to provide a complete feed management solution:

┌─────────────────────────────────────────────────────────────────────┐
│                        WordPress RSS Feed                           │
│                    (External WordPress Blog)                        │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                           Feed Service                              │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  • Downloads RSS feed via cURL                              │   │
│  │  • Parses XML using DOMDocument                             │   │
│  │  • Extracts post data (title, description, link, date...)   │   │
│  │  • Manages cache read/write operations                      │   │
│  │  • Extracts images from post descriptions                   │   │
│  └─────────────────────────────────────────────────────────────┘   │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
                ┌───────────────┴───────────────┐
                ▼                               ▼
┌───────────────────────────────┐ ┌───────────────────────────────────┐
│         Nette Cache           │ │         ImageStorage              │
│  ┌─────────────────────────┐  │ │  ┌─────────────────────────────┐  │
│  │ • FileStorage (default) │  │ │  │ • Downloads images via cURL │  │
│  │ • Configurable TTL      │  │ │  │ • Validates image types     │  │
│  │ • Auto-invalidation     │  │ │  │ • Stores to local disk      │  │
│  └─────────────────────────┘  │ │  │ • Generates URLs            │  │
└───────────────────────────────┘ │  └─────────────────────────────┘  │
                                  └───────────────────────────────────┘
                                                  │
                                                  ▼
                                  ┌───────────────────────────────────┐
                                  │           Post Entity             │
                                  │  ┌─────────────────────────────┐  │
                                  │  │ • title (string)            │  │
                                  │  │ • description (string)      │  │
                                  │  │ • link (string)             │  │
                                  │  │ • date (DateTimeImmutable)  │  │
                                  │  │ • creator (string|null)     │  │
                                  │  │ • categories (array)        │  │
                                  │  │ • mainImageUrl (string|null)│  │
                                  │  └─────────────────────────────┘  │
                                  └───────────────────────────────────┘

It's best to use Composer for installation, and you can also find the package on Packagist and GitHub.

To install, simply use the command:

$ composer require baraja-core/wordpress-post-feed

You can use the package manually by creating an instance of the internal classes, or register a DIC extension to link the services directly to the Nette Framework.

• PHP 8.0 or higher
• ext-curl extension
• Nette Caching component (installed automatically)

The library works out of the box without any configuration:

$feed = new \Baraja\WordPressPostFeed\Feed;

By default, the Feed service will:

• Create a temporary directory for caching in the system temp folder
• Set cache expiration to 2 hours
• Create an ImageStorage instance with default settings

If you are installing the package into the Nette Framework, register the extension in your configuration:

extensions:
    wordpressPostFeed: Baraja\WordPressPostFeed\WordpressPostFeedExtension

The extension supports the following configuration options:

wordpressPostFeed:
    # Cache expiration time (supports human-readable format)
    expirationTime: '2 hours'

    # Absolute path for image storage
    imageStoragePath: '%wwwDir%/assets/blog-images'

    # Relative path used in URLs (required when imageStoragePath is set)
    imageRelativeStoragePath: 'assets/blog-images'

$feed = new \Baraja\WordPressPostFeed\Feed;

$posts = $feed->load('https://blog.example.com/feed/');

foreach ($posts as $post) {
    echo $post->getTitle();
    echo $post->getDescription();
    echo $post->getLink();
    echo $post->getDate()->format('Y-m-d');
    echo $post->getCreator();
    echo json_encode($post->getCategories());
    echo $post->getMainImageUrl();
}

The feed will be downloaded automatically, then cached and further requests will be handled instantly straight from the cache.

If you only need to retrieve some posts from the feed, use the limit and offset arguments:

$posts = $feed->load(
    url: 'https://blog.example.com/feed/',
    limit: 3,
    offset: 1,
);

The Post entity provides the following methods:

Posts are automatically cached for the set period (default 2 hours). The caching system operates on two levels:

1. Raw feed caching - The downloaded XML feed is cached to avoid repeated HTTP requests
2. Parsed post caching - The parsed Post objects are cached separately for each limit/offset combination

When the cache expires, the next request will:

1. Download the fresh feed
2. Parse all posts
3. Store images locally
4. Update the cache

If you want to refresh the cache before expiration (e.g., via cron job):

$feed = new \Baraja\WordPressPostFeed\Feed;
$feed->updateCache('https://blog.example.com/feed/');

This is useful for ensuring all requests are served from cache instantly, even after expiration.

To completely clear the feed cache:

$feed = new \Baraja\WordPressPostFeed\Feed;
$feed->clearCache();

For production environments, it's recommended to set up a cron job that refreshes the cache periodically:

// cron.php - Run every hour
$feed = new \Baraja\WordPressPostFeed\Feed;

$feedUrls = [
    'https://blog.example.com/feed/',
    'https://another-blog.com/feed/',
];

foreach ($feedUrls as $url) {
    $feed->updateCache($url);
}

This ensures that user requests are always served from cache and never have to wait for feed downloads.

When downloading posts from the feed, images are automatically downloaded and copied to disk. The image storage is provided by the \Baraja\WordPressPostFeed\ImageStorage service, which is automatically registered by the library.

The default directory for storing images is wordpress-post-feed relative to your index.php (web root).

The service provides the following methods:

Working with images is also available directly from the Post entity:

foreach ($posts as $post) {
    // Original external URL (from WordPress)
    $externalUrl = $post->getMainImageUrl();

    // Local absolute URL (your domain)
    $absoluteUrl = $post->getAbsoluteInternalUrl();

    // Local relative URL (for use in templates)
    $relativeUrl = $post->getRelativeInternalUrl();
}

The library validates downloaded images and supports the following formats:

If a downloaded file is not a valid image of these types, a RuntimeException is thrown to prevent potential security issues.

Images are stored with a deterministic naming scheme to prevent collisions and ensure readability:

1. A 7-character MD5 hash prefix is generated from the URL
2. The original filename is sanitized (webalized) and truncated to 64 characters
3. Files are organized into subdirectories based on WordPress date structure (YYYY-MM) or URL hash

Example: https://blog.example.com/wp-content/uploads/2024/03/my-image.jpg becomes:

wordpress-post-feed/2024-03/a1b2c3d-my-image.jpg

You can provide your own cache storage implementation:

use Nette\Caching\Storages\MemcachedStorage;

$memcached = new Memcached;
$memcached->addServer('localhost', 11211);

$storage = new MemcachedStorage($memcached);
$feed = new \Baraja\WordPressPostFeed\Feed(storage: $storage);

$imageStorage = new \Baraja\WordPressPostFeed\ImageStorage(
    storagePath: '/var/www/html/assets/blog-images',
    relativeStoragePath: 'assets/blog-images',
);

$feed = new \Baraja\WordPressPostFeed\Feed(imageStorage: $imageStorage);

$feed = new \Baraja\WordPressPostFeed\Feed(
    expirationTime: '30 minutes',
);

Supported time formats include: '1 hour', '30 minutes', '2 days', etc.

When using the Nette Framework, you can inject the services directly:

final class BlogPresenter extends Nette\Application\UI\Presenter
{
    public function __construct(
        private \Baraja\WordPressPostFeed\Feed $feed,
    ) {
    }

    public function renderDefault(): void
    {
        $this->template->posts = $this->feed->load(
            url: 'https://blog.example.com/feed/',
            limit: 5,
        );
    }
}

The library handles errors gracefully:

• Empty feed response - Throws RuntimeException with descriptive message
• Invalid image format - Throws RuntimeException to prevent security issues
• Broken image URLs - Triggers a warning but continues processing
• Invalid feed URLs - Triggers a warning but continues processing
• Missing absolute URL in CLI - Throws LogicException with guidance

Example of handling errors:

try {
    $posts = $feed->load('https://blog.example.com/feed/');
} catch (\RuntimeException $e) {
    // Handle feed loading errors
    error_log('Feed error: ' . $e->getMessage());
}

Jan Barasek

• Website: https://baraja.cz
• GitHub: @janbarasek

baraja-core/wordpress-post-feed is licensed under the MIT license. See the LICENSE file for more details.