Pluggable configuration backends: JSON-on-disk or a custom IBackend, with a schema-validated Store and a versioned migration runner.
Structured settings addressed by (group, key), where the group name may be flat (General) or dot-path (Snapping.Behavior.ZoneSpan), with typed values (bool, int, double, color, string, map, list), defaults, and validation. The library provides:
| Type | Purpose |
|---|---|
| PhosphorConfig::Store | Front-end API: read<T>(), readVariant(), write(), reset(), changed() signal |
| PhosphorConfig::IBackend | Abstract backend. Shipped: JsonBackend |
| PhosphorConfig::JsonBackend | JSON-on-disk, with the path chosen by the consumer (e.g. $XDG_CONFIG_HOME/<app>/config.json). setOverlay() lays read-only in-memory values over the file |
| PhosphorConfig::QSettingsBackend | Read-only reader for a legacy KConfig-style INI file, for migration onto JsonBackend |
| PhosphorConfig::Schema | Declarative struct: groups of KeyDef (default + expected type + validator), version, migration chain |
| PhosphorConfig::MigrationRunner | Runs the schema's MigrationStep chain, one step per schema bump |
| PhosphorConfig::IGroupPathResolver | Group-name to backend-key mapping |
| PhosphorConfig::HostDirectory | Which host's settings file a settings module edits, when several hosts can serve one API: their installed descriptors, the record the running host writes, and the choice between them |
#include <PhosphorConfig/Store.h>
#include <PhosphorConfig/JsonBackend.h>
#include <PhosphorConfig/Schema.h>
using namespace PhosphorConfig;
// The backend is borrowed: the caller keeps it alive for the store's lifetime.
auto backend = std::make_unique<JsonBackend>(configPath);
Store settings(backend.get(), myAppSchema()); // consumer builds its own Schema
// Read a declared key; the schema default applies when it is unset.
bool zoneSpanEnabled =
settings.read<bool>(QStringLiteral("Snapping.Behavior.ZoneSpan"),
QStringLiteral("enabled"));
// Write. The file is rewritten on the next sync() or commit(), not here.
settings.write(QStringLiteral("Snapping.Behavior.ZoneSpan"),
QStringLiteral("enabled"), true);
// React to a change. Store::write() and Store::reset() say when one is announced.
connect(&settings, &Store::changed,
this, [](const QString &group, const QString &key) {
qDebug() << "changed:" << group << key;
});Migrations are declared as MigrationStep entries on the Schema and run by MigrationRunner (one step per schema bump):
// Run once at startup, before opening the backend against the same path.
Schema schema = myAppSchema();
schema.version = 2;
schema.migrations.push_back(MigrationStep{
.fromVersion = 1,
.migrate = [](QJsonObject &root) {
// v1 had a single "snap.enabled" flag; v2 splits into per-edge flags.
bool was = root.take(QStringLiteral("snap.enabled")).toBool();
QJsonObject snap;
snap.insert(QStringLiteral("left"), was);
snap.insert(QStringLiteral("right"), was);
snap.insert(QStringLiteral("top"), was);
snap.insert(QStringLiteral("bottom"), was);
root.insert(QStringLiteral("snap"), snap);
root.insert(QStringLiteral("_version"), 2); // each step bumps the version
},
});
MigrationRunner(schema).runOnFile(configPath);Command-line style overrides go in an overlay rather than a rewritten file. The overlay has the document's shape, wins over the file for every read (nested objects merge key by key), survives reparseConfiguration(), and is never written back:
// afterglow -o Audio.enabled=false
backend->setOverlay(QJsonObject{
{QStringLiteral("Audio"), QJsonObject{{QStringLiteral("enabled"), false}}},
});
settings.read<bool>(QStringLiteral("Audio"), QStringLiteral("enabled")); // falseStore's writes, resets and imports decide against the file (IBackend::persistedGroup()), so writing a value equal to the overlay's still persists it.
A file that exists but does not parse, or whose root is not an object, is never overwritten. loadFailed() turns on, the backend reads as the last document it read or wrote cleanly (empty on a first load), and sync(), commit() and applyMigration() refuse rather than write over the user's file. A flush also re-checks the file's size and mtime against the backend's last read or write of it, so a file broken by hand after it was read is refused too. The overlay stays on top of the fallback document. A later reparseConfiguration() or reload() that reads the file cleanly clears the flag. reload() is the same reload for a caller that reports problems itself: it logs nothing and returns the reason the file could not be read. A file that holds only white space reads as an empty document, as a missing one does, and blankFile() tells it from a file that holds {}: an editor that saves in place empties the file before it writes. A caller that reloads at once constructs the backend with JsonBackend::Load::Deferred, so the file is read and reported one time. Until that first reload the backend is empty and refuses writes. A machine-written file with nothing worth keeping opts out with setOverwriteUnreadable(true).
Some settings can be served by more than one host, each keeping them in its own file. The placement settings are PlasmaZones' on KWin, and the Phosphor compositor is the intended second host, in its own session. A settings module edits the right file whether or not the host runs:
const PhosphorConfig::HostDirectory hosts(QStringLiteral("placement"));
const QList<PhosphorConfig::HostDescriptor> descriptors = hosts.descriptors();
// resolve() takes the pid of one owner, so the hosts of one API are expected
// to share a bus name and any descriptor's will do. The pid stays 0 when
// nothing owns the name, when no host is installed, or when there is no
// session bus to ask.
qint64 owner = 0;
QDBusConnectionInterface* bus = QDBusConnection::sessionBus().interface();
if (bus && !descriptors.isEmpty()) {
owner = bus->servicePid(descriptors.constFirst().busName).value();
}
const auto chosen = PhosphorConfig::HostDirectory::resolve(descriptors, hosts.record(), owner,
PhosphorConfig::HostDirectory::currentDesktops());