From 57d9a5e92571694e9e3d498a4a1c9b7b56f86e3a Mon Sep 17 00:00:00 2001 From: Andrew Dolgov Date: Thu, 18 Nov 2021 20:51:11 +0300 Subject: [PATCH] config: use phpdoc comments for global options, etc --- classes/config.php | 170 +++++++++++++++++++++++++-------------------- 1 file changed, 93 insertions(+), 77 deletions(-) diff --git a/classes/config.php b/classes/config.php index 6832846a2..322d2209a 100644 --- a/classes/config.php +++ b/classes/config.php @@ -8,172 +8,188 @@ class Config { const SCHEMA_VERSION = 145; - /* 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. + /** override default values, defined below in _DEFAULTS[], prefixing with _ENVVAR_PREFIX: + * + * DB_TYPE becomes: + * + * .env (docker environment): + * + * TTRSS_DB_TYPE=pgsql + * + * or config.php: + * + * putenv('TTRSS_DB_TYPE=pgsql'); + * + * note lack of quotes and spaces before and after "=". + * */ + /** database type: pgsql or mysql */ const DB_TYPE = "DB_TYPE"; + + /** database server hostname */ const DB_HOST = "DB_HOST"; + + /** database user */ const DB_USER = "DB_USER"; + + /** database name */ const DB_NAME = "DB_NAME"; + + /** database password */ const DB_PASS = "DB_PASS"; + + /** database server port */ const DB_PORT = "DB_PORT"; - // database credentials + /** 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 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. + /** 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 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 + /** 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 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). + /** 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 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. + /** use this PHP CLI executable to start various tasks */ const PHP_EXECUTABLE = "PHP_EXECUTABLE"; - // use this PHP CLI executable to start various tasks + /** base directory for lockfiles (must be writable) */ const LOCK_DIRECTORY = "LOCK_DIRECTORY"; - // base directory for lockfiles (must be writable) + /** base directory for local cache (must be writable) */ const CACHE_DIR = "CACHE_DIR"; - // base directory for local cache (must be writable) + /** directory for feed favicons (directory must be writable) */ const ICONS_DIR = "ICONS_DIR"; + + /** URL for feed favicons */ const ICONS_URL = "ICONS_URL"; - // directory and URL for feed favicons (directory must be writable) + /** auto create users authenticated via external modules */ const AUTH_AUTO_CREATE = "AUTH_AUTO_CREATE"; - // auto create users authenticated via external modules + /** auto log in users authenticated via external modules i.e. auth_remote */ const AUTH_AUTO_LOGIN = "AUTH_AUTO_LOGIN"; - // auto log in users authenticated via external modules i.e. auth_remote + /** unconditinally purge all articles older than this amount, in days + * overrides user-controlled purge interval */ const FORCE_ARTICLE_PURGE = "FORCE_ARTICLE_PURGE"; - // unconditinally purge all articles older than this amount, in days - // overrides user-controlled purge interval + /** default lifetime of a session (e.g. login) cookie. In seconds, + * 0 means cookie will be deleted when browser closes. */ 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. + /** send email using this name */ const SMTP_FROM_NAME = "SMTP_FROM_NAME"; + + /** send email using this address */ const SMTP_FROM_ADDRESS = "SMTP_FROM_ADDRESS"; - // send email using this name and address + /** default subject for email digest */ const DIGEST_SUBJECT = "DIGEST_SUBJECT"; - // default subject for email digest + /** enable built-in update checker, both for core code and plugins (using git) */ const CHECK_FOR_UPDATES = "CHECK_FOR_UPDATES"; - // enable built-in update checker, both for core code and plugins (using git) + /** system plugins enabled for all users, comma separated list, no quotes + * keep at least one auth module in there (i.e. auth_internal) */ 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) + /** available options: sql (default, event log), syslog, stdout (for debugging) */ const LOG_DESTINATION = "LOG_DESTINATION"; - // available options: sql (default, event log), syslog, stdout (for debugging) + /** link this stylesheet on all pages (if it exists), should be placed in themes.local */ const LOCAL_OVERRIDE_STYLESHEET = "LOCAL_OVERRIDE_STYLESHEET"; - // link this stylesheet on all pages (if it exists), should be placed in themes.local + /** same but this javascript file (you can use that for polyfills), should be placed in themes.local */ const LOCAL_OVERRIDE_JS = "LOCAL_OVERRIDE_JS"; - // same but this javascript file (you can use that for polyfills), should be placed in themes.local + /** in seconds, terminate update tasks that ran longer than this interval */ const DAEMON_MAX_CHILD_RUNTIME = "DAEMON_MAX_CHILD_RUNTIME"; - // in seconds, terminate update tasks that ran longer than this interval + /** max concurrent update jobs forking update daemon starts */ const DAEMON_MAX_JOBS = "DAEMON_MAX_JOBS"; - // max concurrent update jobs forking update daemon starts + /** How long to wait for response when requesting feed from a site (seconds) */ const FEED_FETCH_TIMEOUT = "FEED_FETCH_TIMEOUT"; - // How long to wait for response when requesting feed from a site (seconds) + /** How long to wait for response when requesting uncached feed from a site (seconds) */ const FEED_FETCH_NO_CACHE_TIMEOUT = "FEED_FETCH_NO_CACHE_TIMEOUT"; - // Same but not cached + /** Default timeout when fetching files from remote sites */ const FILE_FETCH_TIMEOUT = "FILE_FETCH_TIMEOUT"; - // Default timeout when fetching files from remote sites + /** How long to wait for initial response from website when fetching remote files */ const FILE_FETCH_CONNECT_TIMEOUT = "FILE_FETCH_CONNECT_TIMEOUT"; - // How long to wait for initial response from website when fetching files from remote sites + /** stop updating feeds if user haven't logged in for X days */ const DAEMON_UPDATE_LOGIN_LIMIT = "DAEMON_UPDATE_LOGIN_LIMIT"; - // stop updating feeds if user haven't logged in for X days + /** how many feeds to update in one batch */ const DAEMON_FEED_LIMIT = "DAEMON_FEED_LIMIT"; - // how many feeds to update in one batch + /** default sleep interval between feed updates (sec) */ const DAEMON_SLEEP_INTERVAL = "DAEMON_SLEEP_INTERVAL"; - // default sleep interval between feed updates (sec) + /** do not cache files larger than that (bytes) */ const MAX_CACHE_FILE_SIZE = "MAX_CACHE_FILE_SIZE"; - // do not cache files larger than that (bytes) + /** do not download files larger than that (bytes) */ const MAX_DOWNLOAD_FILE_SIZE = "MAX_DOWNLOAD_FILE_SIZE"; - // do not download files larger than that (bytes) + /** max file size for downloaded favicons (bytes) */ const MAX_FAVICON_FILE_SIZE = "MAX_FAVICON_FILE_SIZE"; - // max file size for downloaded favicons (bytes) + /** max age in days for various automatically cached (temporary) files */ const CACHE_MAX_DAYS = "CACHE_MAX_DAYS"; - // max age in days for various automatically cached (temporary) files + /** max interval between forced unconditional updates for servers + * not complying with http if-modified-since (seconds) */ const MAX_CONDITIONAL_INTERVAL = "MAX_CONDITIONAL_INTERVAL"; - // max interval between forced unconditional updates for servers not complying with http if-modified-since (seconds) + /** automatically disable updates for feeds which failed to + * update for this amount of days; 0 disables */ 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 + /** log all sent emails in the event log */ const LOG_SENT_MAIL = "LOG_SENT_MAIL"; - // log all sent emails in the event log + /** use HTTP proxy for requests */ const HTTP_PROXY = "HTTP_PROXY"; - // use HTTP proxy for requests + /** prevent users from changing passwords */ const FORBID_PASSWORD_CHANGES = "FORBID_PASSWORD_CHANGES"; - // prevent users from changing passwords + /** default session cookie name */ const SESSION_NAME = "SESSION_NAME"; - // default session cookie name + /** enable plugin update checker (using git) */ const CHECK_FOR_PLUGIN_UPDATES = "CHECK_FOR_PLUGIN_UPDATES"; - // enable plugin update checker (using git) + /** allow installing first party plugins using plugin installer in prefs */ const ENABLE_PLUGIN_INSTALLER = "ENABLE_PLUGIN_INSTALLER"; - // allow installing first party plugins using plugin installer in prefs + /** minimum amount of seconds required between authentication attempts */ const AUTH_MIN_INTERVAL = "AUTH_MIN_INTERVAL"; - // minimum amount of seconds required between authentication attempts + /** http user agent (changing this is not recommended) */ const HTTP_USER_AGENT = "HTTP_USER_AGENT"; - // http user agent (changing this is not recommended) - // default values for all of the above: + /** default values for all global configuration options */ private const _DEFAULTS = [ Config::DB_TYPE => [ "pgsql", Config::T_STRING ], Config::DB_HOST => [ "db", Config::T_STRING ], @@ -268,11 +284,11 @@ class Config { } } - /* package maintainers who don't use git: if version_static.txt exists in tt-rss root - directory, its contents are displayed instead of git commit-based version, this could be generated - based on source git tree commit used when creating the package */ - - /** + /** determine tt-rss version (using git) + * + * package maintainers who don't use git: if version_static.txt exists in tt-rss root + * directory, its contents are displayed instead of git commit-based version, this could be generated + * based on source git tree commit used when creating the package * @return array|string */ static function get_version(bool $as_string = true) { @@ -456,7 +472,7 @@ class Config { /* sanity check stuff */ - /** + /** checks for mysql tables not using InnoDB (tt-rss is incompatible with MyISAM) * @return array> A list of entries identifying tt-rss tables with bad config */ private static function check_mysql_tables() {