README

Generate a Atom/JSON/RSS-Feed and XML-Sitemap from Pages-Collection.

Installation

• unzip master.zip as folder site/plugins/kirby3-feed or
• git submodule add https://github.com/bnomei/kirby3-feed.git site/plugins/kirby3-feed or
• composer require bnomei/kirby3-feed

Usage Feed

You can use this in a template for a dedicated feed page, in a template controller or a route.

<?php
$options = [
    'title' => 'Latest articles',
    'description' => 'Read the latest news about our company',
    'link' => 'blog'
];
echo page('blog')->children()->listed()->flip()->limit(10)->feed($options);

options array defaults

If you use these defaults you need to provide the fields date (type: date) and text (type: text).

[
    'datefield' => 'date',
    'dateformat' => 'r',
    'description' => '',
    'feedurl' => site()->url() . '/feed/',
    'link' => site()->url(),
    'mime' => null,
    'modified' => time(),
    'snippet' => 'feed/rss', // 'feed/json', 'feed/atom'
    'sort' => true,
    'textfield' => 'text',
    'title' => 'Feed',
    'titlefield' => 'title',
    'url' => site()->url(),
    'urlfield' => 'url',
]

virtual page in site/config/config.php

return [
    'routes' => [
        [
            'pattern' => 'feed',
            'method' => 'GET',
            'action'  => function () {
                $options = [
                    'title' => 'Latest articles',
                    'description' => 'Read the latest news about our company',
                    'link' => 'blog',
                    'feedurl' => site()->url() . '/feed/', // matches pattern above
                ];
                
                // while this would be possible
                // return page('blog')->children()->listed()->flip()->limit(10)->feed($options);
                
                // using a closure allows for better performance on a cache hit
                return feed(fn() => page('blog')->children()->listed()->flip()->limit(10), $options);
            }
        ],
    ],
];

HTML head element

rss xml

<link rel="alternate" type="application/rss+xml" title="Latest articles" href="<?= site()->url() ?>/feed"/>

and/or rss json

<link rel="alternate" type="application/json" title="Latest articles" href="<?= site()->url() ?>/feed"/>

TIP: Having multiple feed links is still valid html. So you can have both rss and json if you want and setup the routes properly.

Sorting

The Plugin applies a default sorting for the pages by date/modified in descending order (newest first).

• If you do not want this you have to set the datefield setting to another Field name or PageMethod name.
• If you want to disable sorting by the plugin and add your own you can set the option sort to false.

Pitfalls when presorting by date and limit

Using sortBy('date', 'desc') will not yield expected results! In K3 sorting by date needs a callback.

$feed = page('blog')->children()->listed()->sortBy(function ($page) {
 return $page->date()->toDate();
}, 'desc')->limit(10)->feed($options);

Usage Sitemap

options array defaults

If you use these defaults you need to provide the fields date (type: date) and text (type: text).

[
    'dateformat' => 'c',
    'feedurl' => site()->url().'/sitemap.xml',
    'imagecaptionfield' => 'caption',
    'imagelicensefield' => 'license',
    'images' => false,
    'imagesfield' => 'images',
    'imagetitlefield' => 'title',
    'mime' => null,
    'modified' => time(),
    'snippet' => 'feed/sitemap',
    'sort' => true,
    'urlfield' => 'url',
    'videodescriptionfield' => 'description',
    'videos' => false,
    'videosfield' => 'videos',
    'videothumbnailfield' => 'thumbnail',
    'videotitlefield' => 'title',
    'videourlfield' => 'url',
    'xsl' => true,
]

virtual page in site/config.php

return [
    'routes' => [
        // ... other routes,
        [
            'pattern' => 'sitemap.xml',
            'method' => 'GET',
            'action'  => function () {
                // while this would be possible
                // return site()->index()->listed()->limit(50000)->sitemap();
                
                // using a closure allows for better performance on a cache hit
                return sitemap(fn() => site()->index()->listed()->limit(50000));
            }
        ],
        // (optional) Add stylesheet for human readable version of the xml file.
        // With that stylesheet visiting the xml in a browser will per-generate the images.
        // The images will NOT be pre-generated if the xml file is downloaded (by google).
        [
            'pattern' => 'sitemap.xsl',
            'method' => 'GET',
            'action'  => function () {
                snippet('feed/sitemapxsl');
                die;
            }
        ],
    ],
];

example for excluding pages from sitemap

see the official Kirby documentation: Filtering compendium

return sitemap(fn() => site()->index()->listed()
    ->filterBy('template', '!=', 'excludeme')
    ->limit(50000)
);

Settings

Cache

Warning

If the global debug option is set to true the plugin will automatically flush its own cache. The plugin will automatically in-validate the cache if any of the Page objects in given Pages-Collection were modified with the Panel.

If you need to flush the cache manually, like after automated deployments or transferring files via FTP, you can use the following code:

\Bnomei\Feed::flush();

Or simply delete the cache files/folder at site/cache/{{ HOST }}/plugins/bnomei/feed.

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.

License

MIT

It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.

Credits

based on K2 versions of

• https://github.com/getkirby-plugins/feed-plugin
• https://github.com/stefanzweifel/kirby-json-feed