about summary refs log tree commit diff stats
path: root/docs/Config.md
diff options
context:
space:
mode:
authorAndrew Dolgov <fox@fakecake.org>2026-06-11 21:02:02 +0300
committerAndrew Dolgov <fox@fakecake.org>2026-06-11 21:02:02 +0300
commite4020e8dfefc7df71114b14195e331fb7fb5bf83 (patch)
tree48ef7b3d87b552bdcca966afaa6f5639eaf5e33d /docs/Config.md
parent24187f28d3d8f5af06a56b89a74e4be7a7b0573d (diff)
downloadthe-epube-e4020e8dfefc7df71114b14195e331fb7fb5bf83.tar.gz
the-epube-e4020e8dfefc7df71114b14195e331fb7fb5bf83.tar.xz
add cosmetic git-based version to the UI, set on build
Diffstat (limited to 'docs/Config.md')
-rw-r--r--docs/Config.md58
1 files changed, 58 insertions, 0 deletions
diff --git a/docs/Config.md b/docs/Config.md
new file mode 100644
index 0000000..9e62afb
--- /dev/null
+++ b/docs/Config.md
@@ -0,0 +1,58 @@
+# Config
+
+Singleton configuration manager. Loads settings from environment variables (prefixed with `EPUBE_`), falls back to built-in defaults, and provides runtime accessors.
+
+## Type system
+
+| Constant     | Value | Meaning   |
+|--------------|-------|-----------|
+| `T_BOOL`     | `1`   | Boolean   |
+| `T_STRING`   | `2`   | String    |
+| `T_INT`      | `3`   | Integer   |
+
+Values are cast on retrieval via `cast_to()`.
+
+## Configuration keys & defaults
+
+All keys are class constants. At runtime they are read from environment variables with the `EPUBE_` prefix (e.g. `EPUBE_DB_HOST`).
+
+| Key                | Default            | Type   |
+|--------------------|--------------------|--------|
+| `DB_TYPE`          | `sqlite`           | string |
+| `DB_HOST`          | `db`               | string |
+| `DB_USER`          | _(empty)_          | string |
+| `DB_NAME`          | _(empty)_          | string |
+| `DB_PASS`          | _(empty)_          | string |
+| `DB_PORT`          | `5432`             | string |
+| `SCRATCH_DB`       | `db/scratch.db`    | string |
+| `CALIBRE_DB`       | _(empty)_          | string |
+| `BOOKS_DIR`        | _(empty)_          | string |
+| `DICT_SERVER`      | _(empty)_          | string |
+| `SESSION_LIFETIME` | `2592000` (30 days)| int    |
+| `SESSION_NAME`     | `epube_sid`        | string |
+| `OIDC_NAME`        | `OIDC`             | string |
+| `OIDC_URL`         | _(empty)_          | string |
+| `OIDC_CLIENT_ID`   | _(empty)_          | string |
+| `OIDC_CLIENT_SECRET`| _(empty)_         | string |
+
+## Public API
+
+| Method                       | Returns            | Description                                   |
+|------------------------------|--------------------|-----------------------------------------------|
+| `get_instance()`             | `Config`           | Singleton accessor                            |
+| `get(string $param)`         | `int\|bool\|string`| Read a config value (cast to declared type)   |
+| `add(string $param, string $default, int $type_hint)` | `void` | Register a new config key at runtime        |
+| `set(string $key, mixed $value)` | `bool`         | Write a config value (**test-only**)          |
+| `reload()`                   | `void`             | Reload all values from environment            |
+| `get_migrations()`           | `Db_Migrations`    | Lazily initialised migration handler          |
+| `is_migration_needed()`      | `bool`             | Whether pending migrations exist              |
+| `get_schema_version()`       | `int`              | Current database schema version               |
+| `is_server_https()`          | `bool`             | Detect HTTPS via `$_SERVER`                   |
+| `get_self_url()`             | `string`           | Base URL of the current request (no trailing slash) |
+| `sanity_check()`             | `void`             | Validate runtime environment; halt with error page or CLI output on failure |
+
+## Internal notes
+
+- `__clone()` is private — the class is non-clonable.
+- `set()` emits an `E_USER_WARNING` and returns `false` outside test environments.
+- `sanity_check()` boots `Db::pdo()` eagerly so ORM-dependent checks work.