From 889324e9eac3ea2cd037afbe0ed4103063274e94 Mon Sep 17 00:00:00 2001 From: IanM Date: Tue, 11 Aug 2026 07:51:56 +0100 Subject: [PATCH 1/3] Document configurable session lifetimes Adds a Sessions section covering the new session block in config.php, and fills in the 2.1 changes page with the access token extender. The example at the top of the config page said it was an overview of everything while leaving out safe_mode_extensions, the cookie options, session.driver, database.prefix_indexes and the announcements key. Checked each key against core rather than the existing block. --- docs/config.md | 81 +++++++++++++++++++++++++++++++++++++-- docs/extend/update-2_x.md | 33 ++++++++++++++++ 2 files changed, 110 insertions(+), 4 deletions(-) diff --git a/docs/config.md b/docs/config.md index 589ac070e..5f748a134 100644 --- a/docs/config.md +++ b/docs/config.md @@ -7,12 +7,15 @@ This file, though small, contains details that are crucial for your Flarum insta If the file exists, it tells Flarum that it has already been installed. It also provides Flarum with database info and more. -Here's a quick overview of what everything means with an example file: +Only `database`, `url` and `paths` are written by the installer and required. Everything else is optional — leaving a block out gives you the default shown here. + +Here is every option core reads, with what each one does: ```php false, // enables or disables debug mode, used to troubleshoot issues - 'offline' => false, // none, high, low or safe. + 'offline' => false, // none, high, low or safe. See "Maintenance modes" below + 'safe_mode_extensions' => null, // extensions to keep enabled in safe mode, e.g. array('flarum-tags') 'database' => array ( 'driver' => 'mysql', // the database driver, i.e. MySQL, MariaDB, PostgreSQL, SQLite @@ -23,6 +26,7 @@ Here's a quick overview of what everything means with an example file: 'charset' => 'utf8mb4', 'collation' => 'utf8mb4_unicode_ci', 'prefix' => '', // the prefix for the tables, useful if you are sharing the same database with another service + 'prefix_indexes' => true, // whether the prefix above also applies to index names 'port' => '3306', // the port of the connection, defaults to 3306 with MySQL 'strict' => false, ), @@ -34,15 +38,41 @@ Here's a quick overview of what everything means with an example file: ), 'queue' => array ( - 'driver' => 'sync', // Use the standard sync queue. Omitting this will entirely will have the same effect + 'driver' => 'sync', // Use the standard sync queue. Omitting this entirely will have the same effect + ), + 'session' => + array ( + 'driver' => 'file', // where sessions are stored; extensions can add drivers + 'lifetime' => 120, // how long a session may sit idle, in minutes + 'cookie_expires_on_close' => false, // sign people out when they close their browser + 'tokens' => + array ( + 'session' => 3600, // how long a normal sign-in lasts, in seconds + 'session_remember' => 157680000, // how long "remember me" lasts, in seconds + ), + ), + 'cookie' => + array ( + 'name' => 'flarum', // the prefix for cookie names + 'path' => '/', // defaults to the path of your forum URL + 'domain' => null, // set this to share cookies across subdomains + 'secure' => true, // defaults to true when your forum URL is https + 'samesite' => null, // lax, strict or none ), 'fontawesome' => array ( 'source' => 'local', // Use the bundled FontAwesome Free v7 icons. See below for other config options - ) + ), + 'flarum_announcements.disabled' => false, // hide the announcements widget on the admin dashboard ); ``` +:::tip + +Extensions may read their own keys from this file. Those are documented by the extension rather than here. + +::: + ### Configuration via environment variables Whilst the file based method described here is suitable for most Flarum installations, scaled Flarum instances or those deployed via CI/CD will probably benefit from being configured via the environment. Here's an example of how to do this: @@ -83,6 +113,49 @@ To disable it, add the following to your `config.php`: When disabled, the widget is hidden from the dashboard, no outbound requests are made to discuss.flarum.org, and the scheduled refresh task is not registered. +### Sessions + +How long people stay signed in is configurable, either from the admin panel under **Admin > Advanced**, or in `config.php`. + +Everything here is optional. A forum that configures nothing keeps the lengths Flarum has always used. + +```php +'session' => [ + // How long a session may sit idle before it is discarded, in minutes. + 'lifetime' => 120, + + // Sign people out when they close their browser. + 'cookie_expires_on_close' => false, + + // How long each type of sign-in lasts, in seconds. + 'tokens' => [ + 'session' => 3600, // 1 hour + 'session_remember' => 157680000, // 5 years + ], +], +``` + +#### Token types + +| Type | Default | Applies to | +| --- | --- | --- | +| `session` | 1 hour | Signing in without choosing "remember me" | +| `session_remember` | 5 years | Signing in with "remember me", **and all logins through another service** | + +Social logins are always remembered — there is no "remember me" checkbox on a *Sign in with…* button — so `session_remember` is what governs them. On a forum where most people sign in that way, it is the only value that matters. + +A lifetime of `0` means tokens of that type never expire. + +Extensions can add their own token types, which are configured the same way, keyed by the type they declare. + +#### Sessions and cookies are separate + +`lifetime` is how long the server keeps a session; `cookie_expires_on_close` is whether the browser keeps presenting it. Turning the latter on signs people out when they close the browser, which is useful on shared computers — the session itself is untouched. + +#### config.php takes precedence + +Anything set in `config.php` overrides the equivalent admin setting, and the admin panel shows those values read-only rather than letting them be changed. This is deliberate: it lets whoever runs the server pin session lengths where an administrator cannot loosen them. + ### Maintenance modes Flarum has a maintenance mode that can be enabled by setting the `offline` key in the `config.php` file to one of the following values: diff --git a/docs/extend/update-2_x.md b/docs/extend/update-2_x.md index c022749de..7aaaaf9a6 100644 --- a/docs/extend/update-2_x.md +++ b/docs/extend/update-2_x.md @@ -8,3 +8,36 @@ If you need help applying these changes or using new features, please start a di ## 2.1 Changes +### Access token types + +Token types are now registered with an extender rather than by calling `AccessToken::setModel()` from a service provider: + +```php +use Flarum\Extend; + +return [ + (new Extend\AccessToken()) + ->type(YourAccessToken::class), +]; +``` + +A registered type appears in the admin panel under **Admin > Advanced > Sessions**, where its lifetime can be changed — and can be pinned in `config.php` under `session.tokens.`. See [Configuration](../config.md#sessions). + +Read the resolved lifetime with `lifetime()` rather than the `$lifetime` property, which is only the default: + +```php +class YourAccessToken extends AccessToken +{ + public static string $type = 'your_type'; + + // The default, used when the site has configured nothing. + protected static int $lifetime = 3600; + + // Set this if the lifetime should not be changed by an administrator — + // for tokens meant to outlive a session, such as those issued to a script. + protected static bool $configurableLifetime = true; +} +``` + +`RememberAccessToken::rememberCookieLifeTime()` is deprecated in favour of `RememberAccessToken::lifetime()`, which answers the same question but takes into account what the site has configured. + From 21adf997d81f21621521e155095a45d1f1bb2091 Mon Sep 17 00:00:00 2001 From: IanM Date: Tue, 11 Aug 2026 08:03:33 +0100 Subject: [PATCH 2/3] Explain how environment variables reach config.php Which values env() converts, that numbers stay strings, and what to do for options expecting an array. --- docs/config.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/docs/config.md b/docs/config.md index 5f748a134..3a17a39f9 100644 --- a/docs/config.md +++ b/docs/config.md @@ -79,13 +79,59 @@ Whilst the file based method described here is suitable for most Flarum installa ```php env('DEBUG') - ... + 'debug' => env('DEBUG'), + 'url' => env('FLARUM_URL', 'https://flarum.localhost'), + 'database' => + array ( + 'host' => env('DB_HOST', 'localhost'), + 'database' => env('DB_NAME', 'flarum'), + 'username' => env('DB_USER', 'root'), + 'password' => env('DB_PASSWORD', ''), + ), + 'session' => + array ( + 'lifetime' => env('SESSION_LIFETIME', 120), + ), ); ``` This provides Flarum with the static configuration file it expects, but pulls variables from the environment at runtime. +`config.php` is an ordinary PHP file, so **every** option on this page can be set this way — there is no separate list of environment variables, and nothing needs to support it specially. The second argument to `env()` is the value used when the variable is not set. + +#### Value types + +Environment variables are always strings. `env()` converts a few of them for you: + +| Variable value | PHP value | +| --- | --- | +| `true`, `(true)` | `true` | +| `false`, `(false)` | `false` | +| `null`, `(null)` | `null` | +| `empty`, `(empty)` | `''` | +| anything else | the string, unchanged | + +Numbers therefore arrive as strings — `SESSION_LIFETIME=120` gives you `'120'`, not `120`. Flarum handles that for its own options, but if you write your own logic in `config.php`, cast it yourself: + +```php +'lifetime' => (int) env('SESSION_LIFETIME', 120), +``` + +For switches, prefer the literal words: + +```bash +DEBUG=true # becomes true +DEBUG=1 # stays the string "1" +``` + +`1` works for Flarum's own options, which read any truthy value, but `true` is unambiguous and is what `env()` is designed for. + +Options that expect an array, such as `safe_mode_extensions`, need building from the string yourself: + +```php +'safe_mode_extensions' => array_filter(explode(',', env('SAFE_MODE_EXTENSIONS', ''))), +``` + ### Queues Flarum ships with support for two queue drivers - `sync` and `database`. Many tasks, or 'jobs' can be offloaded to a separate process in order to improve response times and provide a better user experience. From 7699c36417547ccd3aa7990cdf76dc30db76f805 Mon Sep 17 00:00:00 2001 From: IanM Date: Tue, 11 Aug 2026 08:13:49 +0100 Subject: [PATCH 3/3] Move the access token changes to the 2.0 guide They ship in 2.0, not 2.1. --- docs/extend/update-2_0.md | 32 ++++++++++++++++++++++++++++++++ docs/extend/update-2_x.md | 34 ---------------------------------- 2 files changed, 32 insertions(+), 34 deletions(-) diff --git a/docs/extend/update-2_0.md b/docs/extend/update-2_0.md index 55e506540..a4fb47551 100644 --- a/docs/extend/update-2_0.md +++ b/docs/extend/update-2_0.md @@ -452,6 +452,38 @@ Routing a base or abstract class covers all of its subclasses (the most specific > The static was briefly renamed `$onQueue` on early 2.x development builds; either way, replace it with `Extend\Queue->route()`. +### Access Tokens + +Token types are now registered with an extender rather than by calling `AccessToken::setModel()` from a service provider: + +```php +use Flarum\Extend; + +return [ + (new Extend\AccessToken()) + ->type(YourAccessToken::class), +]; +``` + +A registered type appears in the admin panel under **Admin > Advanced > Sessions**, where its lifetime can be changed, and can be pinned in `config.php` under `session.tokens.`. See the [configuration documentation](../config.md#sessions). + +How long a token lasts is no longer fixed by the class. Read the resolved value with `lifetime()`; the `$lifetime` property is only the default used when the site has configured nothing: + +```php +class YourAccessToken extends AccessToken +{ + public static string $type = 'your_type'; + + protected static int $lifetime = 3600; + + // Set this to false for tokens meant to outlive a session, such as those + // issued to a script — an expiry set in the admin panel would break them. + protected static bool $configurableLifetime = true; +} +``` + +`RememberAccessToken::rememberCookieLifeTime()` is deprecated in favour of `RememberAccessToken::lifetime()`, which answers the same question but takes into account what the site has configured. + ### OAuth / Forum Auth ##### Breaking diff --git a/docs/extend/update-2_x.md b/docs/extend/update-2_x.md index 7aaaaf9a6..f5f74ee20 100644 --- a/docs/extend/update-2_x.md +++ b/docs/extend/update-2_x.md @@ -7,37 +7,3 @@ If you need help applying these changes or using new features, please start a di ::: ## 2.1 Changes - -### Access token types - -Token types are now registered with an extender rather than by calling `AccessToken::setModel()` from a service provider: - -```php -use Flarum\Extend; - -return [ - (new Extend\AccessToken()) - ->type(YourAccessToken::class), -]; -``` - -A registered type appears in the admin panel under **Admin > Advanced > Sessions**, where its lifetime can be changed — and can be pinned in `config.php` under `session.tokens.`. See [Configuration](../config.md#sessions). - -Read the resolved lifetime with `lifetime()` rather than the `$lifetime` property, which is only the default: - -```php -class YourAccessToken extends AccessToken -{ - public static string $type = 'your_type'; - - // The default, used when the site has configured nothing. - protected static int $lifetime = 3600; - - // Set this if the lifetime should not be changed by an administrator — - // for tokens meant to outlive a session, such as those issued to a script. - protected static bool $configurableLifetime = true; -} -``` - -`RememberAccessToken::rememberCookieLifeTime()` is deprecated in favour of `RememberAccessToken::lifetime()`, which answers the same question but takes into account what the site has configured. -