Browse Source

Docblocks for Conf

- Improves #36
- Updated dependencies
J. King 1 year ago
parent
commit
fd1f23fd82
5 changed files with 3606 additions and 747 deletions
  1. 2
    2
      .gitignore
  2. 7
    6
      composer.json
  3. 3527
    738
      composer.lock
  4. 58
    1
      lib/Conf.php
  5. 12
    0
      phpdoc.dist.xml

+ 2
- 2
.gitignore View File

@@ -1,8 +1,8 @@
1 1
 #dependencies
2
-vendor
2
+vendor/
3 3
 
4 4
 #temp files
5
-cache/*
5
+documentation/
6 6
 arsse.db*
7 7
 
8 8
 # Windows image file caches

+ 7
- 6
composer.json View File

@@ -24,14 +24,15 @@
24 24
         "ext-hash": "*",
25 25
         "fguillot/picofeed": ">=0.1.31",
26 26
         "jkingweb/druuid": "^3.0.0",
27
-        "phpseclib/phpseclib": "^2.0.4",
28
-        "hosteurope/password-generator": "^1.0.1"
27
+        "phpseclib/phpseclib": "^2.0",
28
+        "hosteurope/password-generator": "^1.0"
29 29
     },
30 30
     "require-dev": {
31
-        "mikey179/vfsStream": "^1.6.4",
32
-        "webmozart/glob": "^4.1.0",
33
-        "phake/phake": "^2.3.2",
34
-        "phpunit/phpunit": "^6.0.5"
31
+        "mikey179/vfsStream": "^1.6",
32
+        "webmozart/glob": "^4.1",
33
+        "phake/phake": "^3.0",
34
+        "phpunit/phpunit": "^6.0",
35
+        "phpdocumentor/phpdocumentor": "2.*"
35 36
     },
36 37
     "autoload": {
37 38
         "psr-4": {

+ 3527
- 738
composer.lock
File diff suppressed because it is too large
View File


+ 58
- 1
lib/Conf.php View File

@@ -1,43 +1,86 @@
1 1
 <?php
2
+/** Conf class */
2 3
 declare(strict_types=1);
3 4
 namespace JKingWeb\Arsse;
4 5
 
6
+/** Class for loading, saving, and querying configuration
7
+* 
8
+* The Conf class serves both as a means of importing and querying configuration information, as well as a source for default parameters when a configuration file does not specify a value.
9
+* All public properties are configuration parameters that may be set by the server administrator.
10
+*/
5 11
 class Conf {
12
+    /** @var string Default language to use for logging and errors */
6 13
     public $lang                    = "en";
7 14
 
15
+    /** @var string Class of the database driver in use (SQLite3 by default) */
8 16
     public $dbDriver                = Db\SQLite3\Driver::class;
17
+    /** @var string Base path to database schema files */
9 18
     public $dbSchemaBase            = BASE.'sql';
19
+    /** @var boolean Whether to attempt to automatically update the database when updated to a new version with schema changes */
10 20
     public $dbAutoUpdate            = true;
21
+    /** @var string Full path and file name of SQLite database (if using SQLite) */
11 22
     public $dbSQLite3File           = BASE."arsse.db";
23
+    /** @var string Encryption key to use for SQLite database (if using a version of SQLite with SEE) */
12 24
     public $dbSQLite3Key            = "";
25
+    /** @var string Address of host name for PostgreSQL database server (if using PostgreSQL) */
13 26
     public $dbPostgreSQLHost        = "localhost";
27
+    /** @var string Log-in user name for PostgreSQL database server (if using PostgreSQL) */
14 28
     public $dbPostgreSQLUser        = "arsse";
29
+    /** @var string Log-in password for PostgreSQL database server (if using PostgreSQL) */
15 30
     public $dbPostgreSQLPass        = "";
31
+    /** @var integer Listening port for PostgreSQL database server (if using PostgreSQL) */
16 32
     public $dbPostgreSQLPort        = 5432;
33
+    /** @var string Database name on PostgreSQL database server (if using PostgreSQL) */
17 34
     public $dbPostgreSQLDb          = "arsse";
35
+    /** @var string Schema name on PostgreSQL database server (if using PostgreSQL) */
18 36
     public $dbPostgreSQLSchema      = "";
37
+    /** @var string Address of host name for MySQL/MariaDB database server (if using MySQL or MariaDB) */
19 38
     public $dbMySQLHost             = "localhost";
39
+    /** @var string Log-in user name for MySQL/MariaDB database server (if using MySQL or MariaDB) */
20 40
     public $dbMySQLUser             = "arsse";
41
+    /** @var string Log-in password for MySQL/MariaDB database server (if using MySQL or MariaDB) */
21 42
     public $dbMySQLPass             = "";
43
+    /** @var integer Listening port for MySQL/MariaDB database server (if using MySQL or MariaDB) */
22 44
     public $dbMySQLPort             = 3306;
45
+    /** @var string Database name on MySQL/MariaDB database server (if using MySQL or MariaDB) */
23 46
     public $dbMySQLDb               = "arsse";
24 47
 
48
+    /** @var string Class of the user management driver in use (Internal by default) */
25 49
     public $userDriver              = User\Internal\Driver::class;
50
+    /** @var boolean Whether users are already authenticated by the Web server before the application is executed */
26 51
     public $userPreAuth             = true;
52
+    /** @var boolean Whether to automatically append the hostname to form a user@host combination before performing authentication
53
+    * @deprecated */
27 54
     public $userComposeNames        = true;
55
+    /** @var integer Desired length of temporary user passwords */
28 56
     public $userTempPasswordLength  = 20;
29 57
 
58
+    /** @var string Class of the background feed update service driver in use (Forking by default) */
30 59
     public $serviceDriver           = Service\Internal\Driver::class;
60
+    /** @var string The interval between checks for new feeds, as an ISO 8601 duration
61
+    * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
62
+    */
31 63
     public $serviceFrequency        = "PT2M";
64
+    /** @var integer Number of concurrent feed updates to perform */
32 65
     public $serviceQueueWidth       = 5;
66
+    /** @var string The base server address (with scheme, host, port if necessary, and terminal slash) to connect to the server when performing feed updates using cURL */
33 67
     public $serviceCurlBase         = "http://localhost/";
68
+    /** @var string The user name to use when performing feed updates using cURL; if none is provided, a temporary name and password will be stored in the database (this is not compatible with pre-authentication) */
34 69
     public $serviceCurlUser         = null;
70
+    /** @var string The password to use when performing feed updates using cURL */
35 71
     public $serviceCurlPassword     = null;
36 72
     
73
+    /** @var integer Number of seconds to wait for data when fetching feeds from foreign servers */
37 74
     public $fetchTimeout            = 10;
75
+    /** @var integer Maximum size, in bytes, of data when fetching feeds from foreign servers */
38 76
     public $fetchSizeLimit          = 2 * 1024 * 1024;
77
+    /** @var string User-Agent string to use when fetching feeds from foreign servers */
39 78
     public $fetchUserAgentString;
40 79
 
80
+    /** Creates a new configuration object
81
+    * @param string $import_file Optional file to read configuration data from
82
+    * @see self::importFile() 
83
+    */
41 84
     public function __construct(string $import_file = "") {
42 85
         if($import_file != "") $this->importFile($import_file);
43 86
         if(is_null($this->fetchUserAgentString)) {
@@ -50,6 +93,10 @@ class Conf {
50 93
         }
51 94
     }
52 95
 
96
+    /** Layers configuration data from a file into an existing object 
97
+    *
98
+    * The file must be a PHP script which return an array with keys that match the properties of the Conf class. Malformed files will throw an exception; unknown keys are silently ignored. Files may be imported is succession, though this is not currently used.
99
+    * @param string $file Full path and file name for the file to import */
53 100
     public function importFile(string $file): self {
54 101
         if(!file_exists($file)) throw new Conf\Exception("fileMissing", $file);
55 102
         if(!is_readable($file)) throw new Conf\Exception("fileUnreadable", $file);
@@ -65,6 +112,10 @@ class Conf {
65 112
         return $this->import($arr);
66 113
     }
67 114
 
115
+    /** Layers configuration data from an associative array into an existing object 
116
+    *
117
+    * The input array must have keys that match the properties of the Conf class; unknown keys are silently ignored. Arrays may be imported is succession, though this is not currently used.
118
+    * @param mixed[] $arr Array of configuration parameters to export */
68 119
     public function import(array $arr): self {
69 120
         foreach($arr as $key => $value) {
70 121
             $this->$key = $value;
@@ -72,10 +123,16 @@ class Conf {
72 123
         return $this;
73 124
     }
74 125
 
126
+    /** Outputs non-default configuration settings as a string compatible with var_export()
127
+    *
128
+    * If provided a file name, will produce the text of a PHP script suitable for laterimport
129
+    * @param string $file Full path and file name for the file to export to */
75 130
     public function export(string $file = ""): string {
76
-        // TODO
131
+        // TODO: write export method
77 132
     }
78 133
 
134
+    /** Alias of export() method with no parameters
135
+    * @see self::export() */
79 136
     public function __toString(): string {
80 137
         return $this->export();
81 138
     }

+ 12
- 0
phpdoc.dist.xml View File

@@ -0,0 +1,12 @@
1
+<?xml version="1.0" encoding="UTF-8" ?>
2
+<phpdoc>
3
+  <parser>
4
+    <target>documentation</target>
5
+  </parser>
6
+  <transformer>
7
+    <target>documentation</target>
8
+  </transformer>
9
+  <files>
10
+    <directory>lib</directory>
11
+  </files>
12
+</phpdoc>

Loading…
Cancel
Save