src/lib/Feed.php

@@ -26,6 +26,10 @@ class Feed {
     /** @var string The XML namespace for XHTML */
     public const string XHTML_NS = 'http://www.w3.org/1999/xhtml';
 
+    /** @var string The user agent for Feed Reader Central's refresh requests */
+    private const string USER_AGENT =
+        'FeedReaderCentral/' . FRC_VERSION . ' +https://bitbadger.solutions/open-source/feed-reader-central';
+
     /**
      * When parsing XML into a DOMDocument, errors are presented as warnings; this creates an exception for them
      *
@@ -170,6 +174,7 @@ class Feed {
         curl_setopt($docReq, CURLOPT_RETURNTRANSFER, true);
         curl_setopt($docReq, CURLOPT_CONNECTTIMEOUT, 5);
         curl_setopt($docReq, CURLOPT_TIMEOUT,        15);
+        curl_setopt($docReq, CURLOPT_USERAGENT,      self::USER_AGENT);
 
         $result = [
             'content' => curl_exec($docReq),

src/public/docs/index.php

@@ -10,6 +10,7 @@ page_head('Documentation'); ?>
     <p><a href=./the-cli>About the CLI</a> provides orientation on Feed Reader Central&rsquo;s command line interface
     <p><a href=./security-modes>Configuring Security Modes</a> describes the three security modes and how to manage each
         of them
+    <p><a href=./refresh-feeds>Refresh Feeds</a> has instructions on how feeds can be refreshed on a schedule
 </article><?php
 page_foot();
 $db->close();

src/public/docs/refresh-feeds.php

@@ -0,0 +1,52 @@
+<?php
+include '../../start.php';
+
+$db = Data::getConnection();
+Security::verifyUser($db, redirectIfAnonymous: false);
+
+page_head('Refresh Feeds | Documentation'); ?>
+<h1>Refresh Feeds</h1>
+<p class=back-link><a href=./>&lang;&lang; Documentation Home</a>
+<article class=docs>
+    <h2>Manual Feed Refresh</h2>
+    <p>Next to the &ldquo;Your Unread Items&rdquo; heading on the main page, there is a link labeled &ldquo;Refresh All
+        Feeds&rdquo;. Clicking this link will reload the main page once the feeds have been refreshed. Depending on the
+        number and size of feeds, this may take a bit of time; each feed is refreshed individually.
+    <h2>Automatic Refreshing</h2>
+    <p>The <code>refresh</code> utility script will perform this refresh from the CLI. As it runs, it will list the
+        feeds as it processes them, and if it encounters any errors, that is noted as well. This process can be
+        automated via <code>cron</code> on Linux or Mac systems. This is most easily implemented by writing a small
+        shell script to provide some environment settings, then telling <code>cron</code> to run that script.
+    <pre class=item_content>
+#!/bin/bash
+exec 1> >(logger -t feed-reader-central) 2>&1
+cd /path/to/frc
+php-cli util/refresh.php all</pre>
+    <p>Save this (<code>frc-refresh.sh</code> might be a good name) and be sure it is executable
+        (<code>chmod +x ./frc-refresh.sh</code>). Before we put it in crontab, though, let&rsquo;s understand what each
+        line does:
+    <ul>
+        <li>Line 1 tells the operating system to use the <code>bash</code> shell.
+        <li>Line 2 directs all output to the system log (<code>/var/log/syslog</code>), labeling each entry with
+            <code>feed-reader-central</code>. This lets you review the output for its runs in a log that is already
+            maintained and rotated by the operating system.
+        <li>Line 3 changes the current directory to the one where Feed Reader Central is installed; modify it for where
+            you have installed it. Since we are setting up for a <a href=./the-cli>CLI execution</a>, this should place
+            us one directory up from <code>/public</code>.
+        <li>Line 4 executes the refresh script.
+    </ul>
+    <p>Finally, we are ready to add this to our crontab. Enter <code>crontab -e</code> to edit the file, then add a row
+        at the bottom that looks like this:
+    <pre class=item_content>
+0 */6 * * *  /path/to/job/frc-refresh.sh</pre>
+    <p>The items before the path specify when it should run. This example will run at the top of the hour every six
+        hours. Crontab schedules can be tricky to create; a full treatment is outside the scope of this documentation.
+        However, <a href=https://crontab.guru/#0_*/6_*_*_* target=_blank rel=noopener title="Crontab.guru">this site</a>
+        lets you put values in each position and it translates that to words; this lets you see if what you put is what
+        you meant.
+    <p>This should not require many resources; the majority of its time will be spent waiting for the websites to return
+        their feeds so it can process them. However, if you want it to yield to everything else happening on the server,
+        add <code>nice -n 1</code> (with a trailing space) before the path to the script.
+</article><?php
+page_foot();
+$db->close();