about summary refs log tree commit diff stats
path: root/docs/Config.md
blob: 9e62afb4ab982d045d35f212d02fd1c1945cf9f8 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
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.