describe global settings in classes/config.php

classes/config.php

@@ -8,7 +8,20 @@ class Config {
 
 	const SCHEMA_VERSION = 144;
 
-	// override defaults, defined below in _DEFAULTS[], via environment: DB_TYPE becomes TTRSS_DB_TYPE, etc
+	/* override defaults, defined below in _DEFAULTS[], prefixing with _ENVVAR_PREFIX:
+
+		DB_TYPE becomes:
+
+		.env:
+
+		TTRSS_DB_TYPE=pgsql
+
+		or config.php:
+
+		putenv('TTRSS_DB_TYPE=pgsql');
+
+		etc, etc.
+	*/
 
 	const DB_TYPE = "DB_TYPE";
 	const DB_HOST = "DB_HOST";
@@ -16,48 +29,142 @@ class Config {
 	const DB_NAME = "DB_NAME";
 	const DB_PASS = "DB_PASS";
 	const DB_PORT = "DB_PORT";
+	// database credentials
+
 	const MYSQL_CHARSET = "MYSQL_CHARSET";
+	// connection charset for MySQL. if you have a legacy database and/or experience
+	// garbage unicode characters with this option, try setting it to a blank string.
+
 	const SELF_URL_PATH = "SELF_URL_PATH";
+	// this should be set to a fully qualified URL used to access
+	// your tt-rss instance over the net, such as: https://example.com/tt-rss/
+	// if your tt-rss instance is behind a reverse proxy, use external URL.
+	// tt-rss will likely help you pick correct value for this on startup
+
 	const SINGLE_USER_MODE = "SINGLE_USER_MODE";
+	// operate in single user mode, disables all functionality related to
+	// multiple users and authentication. enabling this assumes you have
+	// your tt-rss directory protected by other means (e.g. http auth).
+
 	const SIMPLE_UPDATE_MODE = "SIMPLE_UPDATE_MODE";
+	// enables fallback update mode where tt-rss tries to update feeds in
+	// background while tt-rss is open in your browser.
+	// if you don't have a lot of feeds and don't want to or can't run
+	// background processes while not running tt-rss, this method is generally
+	// viable to keep your feeds up to date.
+
 	const PHP_EXECUTABLE = "PHP_EXECUTABLE";
+	// use this PHP CLI executable to start various tasks
+
 	const LOCK_DIRECTORY = "LOCK_DIRECTORY";
+	// base directory for lockfiles (must be writable)
+
 	const CACHE_DIR = "CACHE_DIR";
+	// base directory for local cache (must be writable)
+
 	const ICONS_DIR = "ICONS_DIR";
 	const ICONS_URL = "ICONS_URL";
+	// directory and URL for feed favicons (directory must be writable)
+
 	const AUTH_AUTO_CREATE = "AUTH_AUTO_CREATE";
+	// auto create users authenticated via external modules
+
 	const AUTH_AUTO_LOGIN = "AUTH_AUTO_LOGIN";
+	// auto log in users authenticated via external modules i.e. auth_remote
+
 	const FORCE_ARTICLE_PURGE = "FORCE_ARTICLE_PURGE";
+	// unconditinally purge all articles older than this amount, in days
+	// overrides user-controlled purge interval
+
 	const SESSION_COOKIE_LIFETIME = "SESSION_COOKIE_LIFETIME";
+	// default lifetime of a session (e.g. login) cookie. In seconds,
+	// 0 means cookie will be deleted when browser closes.
+
 	const SMTP_FROM_NAME = "SMTP_FROM_NAME";
 	const SMTP_FROM_ADDRESS = "SMTP_FROM_ADDRESS";
-	const DIGEST_SUBJECT = "DIGEST_SUBJECT";
+	// send email using this name and address
-	const CHECK_FOR_UPDATES = "CHECK_FOR_UPDATES";
-	const PLUGINS = "PLUGINS";
-	const LOG_DESTINATION = "LOG_DESTINATION";
-	const LOCAL_OVERRIDE_STYLESHEET = "LOCAL_OVERRIDE_STYLESHEET";
-	const DAEMON_MAX_CHILD_RUNTIME = "DAEMON_MAX_CHILD_RUNTIME";
-	const DAEMON_MAX_JOBS = "DAEMON_MAX_JOBS";
-	const FEED_FETCH_TIMEOUT = "FEED_FETCH_TIMEOUT";
-	const FEED_FETCH_NO_CACHE_TIMEOUT = "FEED_FETCH_NO_CACHE_TIMEOUT";
-	const FILE_FETCH_TIMEOUT = "FILE_FETCH_TIMEOUT";
-	const FILE_FETCH_CONNECT_TIMEOUT = "FILE_FETCH_CONNECT_TIMEOUT";
-	const DAEMON_UPDATE_LOGIN_LIMIT = "DAEMON_UPDATE_LOGIN_LIMIT";
-	const DAEMON_FEED_LIMIT = "DAEMON_FEED_LIMIT";
-	const DAEMON_SLEEP_INTERVAL = "DAEMON_SLEEP_INTERVAL";
-	const MAX_CACHE_FILE_SIZE = "MAX_CACHE_FILE_SIZE";
-	const MAX_DOWNLOAD_FILE_SIZE = "MAX_DOWNLOAD_FILE_SIZE";
-	const MAX_FAVICON_FILE_SIZE = "MAX_FAVICON_FILE_SIZE";
-	const CACHE_MAX_DAYS = "CACHE_MAX_DAYS";
-	const MAX_CONDITIONAL_INTERVAL = "MAX_CONDITIONAL_INTERVAL";
-	const DAEMON_UNSUCCESSFUL_DAYS_LIMIT = "DAEMON_UNSUCCESSFUL_DAYS_LIMIT";
-	const LOG_SENT_MAIL = "LOG_SENT_MAIL";
-	const HTTP_PROXY = "HTTP_PROXY";
-	const FORBID_PASSWORD_CHANGES = "FORBID_PASSWORD_CHANGES";
-	const SESSION_NAME = "SESSION_NAME";
-	const CHECK_FOR_PLUGIN_UPDATES = "CHECK_FOR_PLUGIN_UPDATES";
-	const ENABLE_PLUGIN_INSTALLER = "ENABLE_PLUGIN_INSTALLER";
 
+	const DIGEST_SUBJECT = "DIGEST_SUBJECT";
+	// default subject for email digest
+
+	const CHECK_FOR_UPDATES = "CHECK_FOR_UPDATES";
+	// enable built-in update checker, both for core code and plugins (using git)
+
+	const PLUGINS = "PLUGINS";
+	// system plugins enabled for all users, comma separated list, no quotes
+	// keep at least one auth module in there (i.e. auth_internal)
+
+	const LOG_DESTINATION = "LOG_DESTINATION";
+	// available options: sql (default, event log), syslog, stdout (for debugging)
+
+	const LOCAL_OVERRIDE_STYLESHEET = "LOCAL_OVERRIDE_STYLESHEET";
+	// link this stylesheet on all pages
+
+	const DAEMON_MAX_CHILD_RUNTIME = "DAEMON_MAX_CHILD_RUNTIME";
+	// in seconds, terminate update tasks that ran longer than this interval
+
+	const DAEMON_MAX_JOBS = "DAEMON_MAX_JOBS";
+	// max concurrent update jobs forking update daemon starts
+
+	const FEED_FETCH_TIMEOUT = "FEED_FETCH_TIMEOUT";
+	// How long to wait for response when requesting feed from a site (seconds)
+
+	const FEED_FETCH_NO_CACHE_TIMEOUT = "FEED_FETCH_NO_CACHE_TIMEOUT";
+	// Same but not cached
+
+	const FILE_FETCH_TIMEOUT = "FILE_FETCH_TIMEOUT";
+	// Default timeout when fetching files from remote sites
+
+	const FILE_FETCH_CONNECT_TIMEOUT = "FILE_FETCH_CONNECT_TIMEOUT";
+	// How long to wait for initial response from website when fetching files from remote sites
+
+	const DAEMON_UPDATE_LOGIN_LIMIT = "DAEMON_UPDATE_LOGIN_LIMIT";
+	// stop updating feeds if user haven't logged in for X days
+
+	const DAEMON_FEED_LIMIT = "DAEMON_FEED_LIMIT";
+	// how many feeds to update in one batch
+
+	const DAEMON_SLEEP_INTERVAL = "DAEMON_SLEEP_INTERVAL";
+	// default sleep interval between feed updates (sec)
+
+	const MAX_CACHE_FILE_SIZE = "MAX_CACHE_FILE_SIZE";
+	// do not cache files larger than that (bytes)
+
+	const MAX_DOWNLOAD_FILE_SIZE = "MAX_DOWNLOAD_FILE_SIZE";
+	// do not download files larger than that (bytes)
+
+	const MAX_FAVICON_FILE_SIZE = "MAX_FAVICON_FILE_SIZE";
+	// max file size for downloaded favicons (bytes)
+
+	const CACHE_MAX_DAYS = "CACHE_MAX_DAYS";
+	// max age in days for various automatically cached (temporary) files
+
+	const MAX_CONDITIONAL_INTERVAL = "MAX_CONDITIONAL_INTERVAL";
+	// max interval between forced unconditional updates for servers not complying with http if-modified-since (seconds)
+
+	const DAEMON_UNSUCCESSFUL_DAYS_LIMIT = "DAEMON_UNSUCCESSFUL_DAYS_LIMIT";
+	// automatically disable updates for feeds which failed to
+	// update for this amount of days; 0 disables
+
+	const LOG_SENT_MAIL = "LOG_SENT_MAIL";
+	// log all sent emails in the event log
+
+	const HTTP_PROXY = "HTTP_PROXY";
+	// use HTTP proxy for requests
+
+	const FORBID_PASSWORD_CHANGES = "FORBID_PASSWORD_CHANGES";
+	// prevent users from changing passwords
+
+	const SESSION_NAME = "SESSION_NAME";
+	// default session cookie name
+
+	const CHECK_FOR_PLUGIN_UPDATES = "CHECK_FOR_PLUGIN_UPDATES";
+	// enable plugin update checker (using git)
+
+	const ENABLE_PLUGIN_INSTALLER = "ENABLE_PLUGIN_INSTALLER";
+	// allow installing first party plugins using plugin installer in prefs
+
+	// default values for all of the above:
 	private const _DEFAULTS = [
 		Config::DB_TYPE => [ "pgsql", 									Config::T_STRING ],
 		Config::DB_HOST => [ "db", 										Config::T_STRING ],