From ced5dbda8b06e477ad805003be546e7e6fd577c7 Mon Sep 17 00:00:00 2001 From: Imani Manyara <19682005+imanimanyara@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:54:35 -0500 Subject: [PATCH] Correct 30 documentation statements found by checking each page against the code Four read-throughs of the README and all 55 docs pages, each finding verified against src, config, routes and the migration before changing it. Links (326), anchors, footers, class names, commands and config keys were also checked mechanically. --- CHANGELOG.md | 9 +++++++++ docs/architecture.md | 4 ++-- docs/installation.md | 6 +++--- docs/recipes/acting-as-a-user.md | 2 +- docs/recipes/auditing-a-change.md | 2 +- docs/recipes/building-a-preferences-screen.md | 10 +++++++--- docs/recipes/building-an-admin-ui-on-the-rest-api.md | 4 ++-- docs/recipes/calling-the-rest-api-with-sanctum.md | 2 +- docs/recipes/migrating-from-spatie-laravel-settings.md | 4 ++-- docs/recipes/moving-settings-between-environments.md | 2 +- docs/recipes/testing-with-the-fake.md | 2 ++ docs/tools/access-control.md | 2 +- docs/tools/audit-and-logging.md | 4 ++-- docs/tools/commands.md | 6 +++--- docs/tools/definitions.md | 2 +- docs/tools/events.md | 2 +- docs/tools/exceptions.md | 2 +- docs/tools/history.md | 2 +- docs/tools/models-and-factories.md | 2 +- docs/tools/owners.md | 2 +- docs/tools/rest-api-reference.md | 2 +- docs/tools/runtime-configuration.md | 2 +- docs/tools/runtime-overrides.md | 4 ++-- docs/tools/settings-api.md | 10 +++++----- docs/tools/tenancy.md | 2 +- src/Console/MakeStoreCommand.php | 2 +- 26 files changed, 54 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 383a0f1..f949e9f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- Documentation checked page by page against the code, and 30 statements corrected: stale counts + (18 commands, 29 `SettingsException` subclasses, six models), features described as unreleased + that ship (approvals, re-encryption, persisted configuration), global overrides reaching owners + only when the setting inherits, encrypted history payloads answered as `null`, recipe snippets + that missed a gate, an import or a `register()` call, and the stated reason SQL Server is not + supported. `make-store --connection`'s help now names every shared table it creates. + ## [0.1.0] - 2026-11-16 The first public release. `Added` describes the package; `Changed`, `Removed`, `Fixed` and diff --git a/docs/architecture.md b/docs/architecture.md index 5c2f538..956a631 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -208,7 +208,7 @@ The layering above names a service as a stateful collaborator that owns I/O or a but before 0.1 the services sat beside whatever they served: `SettingWriter` next to `Store` and `Layer`, `ValuePipeline` among the stateless helpers it is not one of. Reading a directory did not say which kind of class it held. Every service now lives under `Services\` (`Database`, `Stores`, `Resolution`, `Access`, -`Configuration`, `Definitions`, `Tenancy`, `Casting`, `Values`, `Drivers`, `Cache`), +`Configuration`, `Definitions`, `Tenancy`, `Casting`, `Values`, `Drivers`, `Cache`, `Transfer`), and the classes left in their old directories are value objects, contract implementations and entry points. @@ -321,7 +321,7 @@ database is the reason to choose one. `doctor` checks that every column the pack ## Why one migration? Every table the package uses is created by one migration file, in dependency order (categories, -definitions, each store's values, audit, history), with a `down()` that drops them in reverse. Four +definitions, each store's values, audit, history, change requests, stores), with a `down()` that drops them in reverse. Four migration stubs used to do this, each repeating the same connection and shape lookups, and a new store meant copying a stub. Nothing in the migration varies per application beyond table names and `tenancy.mode`, so it ships as a real PHP file. Its table definitions stay inline, diff --git a/docs/installation.md b/docs/installation.md index 7d2db3e..1505be5 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -92,8 +92,8 @@ Settings::store('settings')->asSystem('installer')->promoteWhenReady(); The values the installer writes go to the runtime file. When its `migrate` call finishes, the store is promoted in the same process. To keep doing this after the install, on every server, set -`'promote' => 'auto'` on the store or `LARANAIL_SETTINGS_PROMOTE=auto`; `promote.include` and -`promote.owners` limit what is moved (see [Configuration](configuration.md)). +`'promote' => 'auto'` on the store or `LARANAIL_SETTINGS_PROMOTE=auto`; the store's `promote.include` +and `promote.owners` limit what is moved (see [Configuration](configuration.md)). ## The REST API @@ -104,7 +104,7 @@ host's authentication middleware (`auth:sanctum` when laravel/sanctum is install ## Supported databases The package is tested on SQLite, MySQL 8.4 and PostgreSQL 17. SQL Server is not supported in -0.x: it allows one `NULL` per unique index, which breaks the `unique(uid)` index. +0.x: it is not in the test matrix, so nothing shows the migration and the queries work there. --- diff --git a/docs/recipes/acting-as-a-user.md b/docs/recipes/acting-as-a-user.md index c7a7f3f..7e413a0 100644 --- a/docs/recipes/acting-as-a-user.md +++ b/docs/recipes/acting-as-a-user.md @@ -20,7 +20,7 @@ use Simtabi\Laranail\Settings\Contracts\Settings; public function update(UpdateMailRequest $request, Settings $settings): RedirectResponse { $settings->asCurrentActor() - ->because($request->string('reason')) + ->because($request->string('reason')->toString()) ->set('mail.from.address', $request->validated('address')); return back(); diff --git a/docs/recipes/auditing-a-change.md b/docs/recipes/auditing-a-change.md index 87385a3..f9dedfd 100644 --- a/docs/recipes/auditing-a-change.md +++ b/docs/recipes/auditing-a-change.md @@ -42,7 +42,7 @@ GET /api/settings/v1/stores/settings/settings/mail.from.address/history ## Make every change carry a reason ```php -$settings->as($request->user())->because($request->input('ticket'))->set('mail.from.address', $address); +$settings->as($request->user())->because((string) $request->input('ticket'))->set('mail.from.address', $address); ``` Over HTTP send `"reason"` in the body. A reason costs nothing and is the first thing an auditor asks for. diff --git a/docs/recipes/building-a-preferences-screen.md b/docs/recipes/building-a-preferences-screen.md index b4dad69..fb191a4 100644 --- a/docs/recipes/building-a-preferences-screen.md +++ b/docs/recipes/building-a-preferences-screen.md @@ -47,11 +47,15 @@ public function update(UpdatePreferencesRequest $request, Settings $settings): R } ``` -Let users change only their own values with a gate that compares the owner: +Let users read and change only their own values with gates that compare the owner. An ability with no gate is denied (`authorization.undefined` is `deny`), so define each one the screen uses: `view` to read, `update` to save, `forget` to reset: ```php -Gate::define('laranail-settings.update', fn (User $user, Subject $subject) => - $subject->owner?->alias === 'user' && (string) $subject->owner->id === (string) $user->getKey()); +$ownValues = fn (User $user, Subject $subject): bool => + $subject->owner?->alias === 'user' && (string) $subject->owner->id === (string) $user->getKey(); + +foreach (['view', 'update', 'forget'] as $ability) { + Gate::define('laranail-settings.' . $ability, $ownValues); +} ``` ## Reset to the default diff --git a/docs/recipes/building-an-admin-ui-on-the-rest-api.md b/docs/recipes/building-an-admin-ui-on-the-rest-api.md index 5438f83..4442bf4 100644 --- a/docs/recipes/building-an-admin-ui-on-the-rest-api.md +++ b/docs/recipes/building-an-admin-ui-on-the-rest-api.md @@ -31,7 +31,7 @@ const api = (path, init = {}) => const [categories, definitions, values] = await Promise.all([ api('/stores/settings/categories').then((r) => r.json()), - api('/stores/settings/definitions?limit=200').then((r) => r.json()), + api('/stores/settings/definitions').then((r) => r.json()), api('/stores/settings/settings?limit=200').then((r) => r.json()), ]); @@ -44,7 +44,7 @@ const sections = categories.data.map((category) => ({ })); ``` -Map `type` to an input (`boolean` to a toggle, `integer` to a number field, `email` to an email field), and render `sensitive` fields as write-only: the listing leaves out values the user may not read. Follow `meta.next_cursor` when a store holds more than 200 keys. +Map `type` to an input (`boolean` to a toggle, `integer` to a number field, `email` to an email field), and render `sensitive` fields as write-only: the listing leaves out values the user may not read. Definitions come back in one response; for values, follow `meta.next_cursor` when a store holds more than 200 keys. ## Save one field at a time, with its ETag diff --git a/docs/recipes/calling-the-rest-api-with-sanctum.md b/docs/recipes/calling-the-rest-api-with-sanctum.md index d1cd0d2..c5f98aa 100644 --- a/docs/recipes/calling-the-rest-api-with-sanctum.md +++ b/docs/recipes/calling-the-rest-api-with-sanctum.md @@ -41,7 +41,7 @@ curl -s -X PUT https://app.example/api/settings/v1/stores/settings/settings/site -d '{"value": "Acme Ltd", "reason": "rebrand"}' ``` -`412` means the setting changed since you read its ETag; read it again. `428` means the ability needs step-up verification (`verification.abilities`): use the `actor` verifier and send a fresh `verifiedAt`, or leave such abilities to people. +`412` means the setting changed since you read its ETag; read it again. `428` means the ability needs step-up verification (`verification.abilities`): no request field satisfies it, so either use the `actor` verifier with an actor resolver that sets `Actor::$verifiedAt` (see `resolveActorsUsing()` and `Actor::withVerifiedAt()`), or leave such abilities to people. See [REST API](../tools/rest-api.md). diff --git a/docs/recipes/migrating-from-spatie-laravel-settings.md b/docs/recipes/migrating-from-spatie-laravel-settings.md index b933e96..129478b 100644 --- a/docs/recipes/migrating-from-spatie-laravel-settings.md +++ b/docs/recipes/migrating-from-spatie-laravel-settings.md @@ -23,7 +23,7 @@ php artisan laranail::settings.import :settings --from=spatie # a dry php artisan laranail::settings.import :settings --from=spatie --apply --trusted ``` -`:settings` is spatie's table on the default connection (`:`). Each row becomes the key `.`; `--trusted` keeps spatie's locks. Keys are lower-cased and `-` becomes `_`, so two rows such as `general.site_name` and `General.Site-Name` would land on one key: the import then fails, names both, and writes nothing. Rename one in spatie's table and import again. Values spatie stored encrypted arrive as spatie's ciphertext: define those keys `encrypted()` here and set them again. +`:settings` is spatie's table on the default connection (`:
`). Each row becomes the key `.`; `--trusted` keeps spatie's locks. Keys are lower-cased, and `-` and spaces become `_`, so two rows such as `general.site_name` and `General.Site-Name` would land on one key: the import then fails, names both, and writes nothing. Rename one in spatie's table and import again. Values spatie stored encrypted arrive as spatie's ciphertext: define those keys `encrypted()` here and set them again. ## 3. Keep the typed classes @@ -40,7 +40,7 @@ final class GeneralSettings extends TypedSettings } ``` -Properties map to snake-cased keys by default (`siteName` is `general.site_name`), so `#[Key]` is only needed where the names differ. Replace `GeneralSettings::class` injections with the new class (resolved from the container, it loads itself) and `$settings->save()` keeps working. +Properties map to snake-cased keys by default (`siteName` is `general.site_name`), so `#[Key]` is only needed where the names differ. List the class in `'typed' => ['classes' => [GeneralSettings::class]]`, then replace `GeneralSettings::class` injections with it: a listed class resolves from the container already loaded, and `$settings->save()` keeps working. An unlisted class resolves empty, and `save()` on it throws `TypeMismatch`. spatie's settings migrations become [settings migrations](../tools/typed-settings.md#settings-migrations). When nothing reads spatie's table any more, drop it. diff --git a/docs/recipes/moving-settings-between-environments.md b/docs/recipes/moving-settings-between-environments.md index 493845d..f06d510 100644 --- a/docs/recipes/moving-settings-between-environments.md +++ b/docs/recipes/moving-settings-between-environments.md @@ -16,7 +16,7 @@ Encrypted values are left out by default, so the file is safe to commit or attac php artisan laranail::settings.diff storage/settings-staging.json --store=settings ``` -The diff lists keys `added`, `removed`, `changed` and `unchanged`, never values, and exits 1 when the two differ, so it can gate a deploy. +The diff lists keys added (`+`), removed (`-`), changed (`~`) and unknown to this release (`?`), never values, and exits 1 when keys are added, removed or changed, so it can gate a deploy. With no difference it prints how many keys are unchanged. ## Import, dry run first diff --git a/docs/recipes/testing-with-the-fake.md b/docs/recipes/testing-with-the-fake.md index 9b2e165..e16c301 100644 --- a/docs/recipes/testing-with-the-fake.md +++ b/docs/recipes/testing-with-the-fake.md @@ -31,6 +31,8 @@ Actors work in the fake exactly as in the engine, so gates you define in the tes ```php use Illuminate\Support\Facades\Gate; use Simtabi\Laranail\Settings\Enums\Ability; +use Simtabi\Laranail\Settings\Facades\Settings; +use Simtabi\Laranail\Settings\Exceptions\AccessDenied; it('refuses a non-admin', function () { $settings = Settings::fake(); diff --git a/docs/tools/access-control.md b/docs/tools/access-control.md index 41cc551..987de06 100644 --- a/docs/tools/access-control.md +++ b/docs/tools/access-control.md @@ -46,7 +46,7 @@ When nobody is authenticated, `asCurrentActor()` raises `ActorRequired` rather t ## Abilities -`Enums\Ability`: `view`, `view_sensitive`, `update`, `forget`, `lock`, `unlock`, `override_lock`, `approve`, `view_history`, `rollback`, `view_audit`, `export`, `import`, `promote`, `manage_categories`, `manage_definitions`, `manage_stores`. This release checks the first seven; the rest are reserved for the features that use them. +`Enums\Ability`: `view`, `view_sensitive`, `update`, `forget`, `lock`, `unlock`, `override_lock`, `approve`, `view_history`, `rollback`, `view_audit`, `export`, `import`, `promote`, `manage_categories`, `manage_definitions`, `manage_stores`, `prune`. The table below covers the value operations; the rest check their own ability: approving a change `approve`, history `view_history` and `rollback`, audit queries `view_audit`, transfer `export` and `import`, promotion `promote`, categories `manage_categories`, definitions `manage_definitions`, store, configuration and cache management `manage_stores`, and the prune commands `prune`. | Operation | Abilities | |---|---| diff --git a/docs/tools/audit-and-logging.md b/docs/tools/audit-and-logging.md index 6e99b9b..8eb81ec 100644 --- a/docs/tools/audit-and-logging.md +++ b/docs/tools/audit-and-logging.md @@ -13,13 +13,13 @@ Every `set`, `forget`, `lock` and `unlock`, allowed or failed, and every refusal | Field | Meaning | |---|---| | `id`, `occurredAt` | a ULID and the time, from `Str::ulid()` and `now()` | -| `action` | `AuditAction`: each ability, plus `configure` | +| `action` | `AuditAction`: each ability, plus `configure`, `propose`, `reject`, `cancel`, `reencrypt`, `rescope` and `migrate` | | `outcome` | `AuditOutcome`: `allowed`, `denied`, `pending`, `failed` | | `store`, `scope`, `key`, `locale` | what was addressed | | `versionFrom`, `versionTo` | the row's version before and after | | `actorType`, `actorAlias`, `actorId`, `channel` | who, through which surface; `system` without an actor | | `ip`, `userAgent`, `requestId`, `reason` | the actor's context and the reason given with `because()` | -| `meta` | identifiers only: `refusal`, `detail`, `error`, `override_lock`, `change` | +| `meta` | identifiers only, never a value: for example `refusal`, `detail`, `error`, `override_lock`, `change`, `operation` | ```php Settings::as($user)->because('INC-123')->set('mail.from.address', 'ap@acme.test'); diff --git a/docs/tools/commands.md b/docs/tools/commands.md index 2ecd813..d7ca548 100644 --- a/docs/tools/commands.md +++ b/docs/tools/commands.md @@ -1,6 +1,6 @@ # Commands -Nineteen Artisan commands, all named `laranail::settings.`. +Eighteen Artisan commands, all named `laranail::settings.`. ## The commands @@ -38,8 +38,8 @@ php artisan migrate It writes one file, `…_create_settings_user_settings_table.php`: a copy of the package migration whose `$only` line names the store, so it creates that store's values table and nothing else. With `--connection=archive` the copy's `$pinnedConnection` line names the connection too, and it -also creates that connection's categories and audit tables (each skipped when it already -exists); it prints the layer to add. It refuses a store that already has a migration. +also creates that connection's categories, audit, history and change requests tables (each +skipped when it already exists); it prints the layer to add. It refuses a store that already has a migration. ## Seeding diff --git a/docs/tools/definitions.md b/docs/tools/definitions.md index 62bdeff..3afaaab 100644 --- a/docs/tools/definitions.md +++ b/docs/tools/definitions.md @@ -37,7 +37,7 @@ Or in `config/laranail/settings.php` under `definitions`: | `public()` / `private()` | `public` | whether the value may leave the server; cannot be combined with `encrypted` | | `sensitive()` | `sensitive` | reading needs `view_sensitive`; implied by `encrypted` (see [Access control](access-control.md)) | | `requiresVerification()` | `requires_verification` | writes need a recent step-up verification | -| `requiresApproval()` | `requires_approval` | writes need approval; until the database layer ships, every write raises `ApprovalUnavailable` | +| `requiresApproval()` | `requires_approval` | writes become change requests; a store without an active database layer raises `ApprovalUnavailable` | | `locked()` | `locked` | refuses every write | | `localised()` | `localised` | allows per-locale values; other keys refuse a locale | | `inherits()` / `doesNotInherit()` | `inherits` | lets owners fall back to parents and the global value | diff --git a/docs/tools/events.md b/docs/tools/events.md index 8253fde..154e056 100644 --- a/docs/tools/events.md +++ b/docs/tools/events.md @@ -10,7 +10,7 @@ Thirty events, all `final readonly` classes in `Simtabi\Laranail\Settings\Events | `SettingForgetting` / `SettingForgotten` | around a forget | the same; `version` is the removed one | | `SettingLocked` / `SettingUnlocked` | after a lock or unlock | the same, with the new `version` | | `SettingRolledBack` | after a rollback | the same, plus `toVersion` (the version returned to) and `version` (the new one) | -| `ScopeFlushing` / `ScopeFlushed` | around `flush()` | `store`, `scope` | +| `ScopeFlushing` / `ScopeFlushed` | around `flush()` | `store`, `scope`; `ScopeFlushed` adds `removed` | | `StorePromoting` / `StorePromoted` | around a promotion | counts, the archive path | | `CategorySaving` / `CategorySaved` | around a category create, rename or move | `store`, `slug` | | `CategoryMoved` | after a move, besides `CategorySaved` | `store`, `slug`, `parent` (null: top level) | diff --git a/docs/tools/exceptions.md b/docs/tools/exceptions.md index 9ce2a7d..c95f46f 100644 --- a/docs/tools/exceptions.md +++ b/docs/tools/exceptions.md @@ -1,6 +1,6 @@ # Exceptions -Thirty-one exception classes in `Simtabi\Laranail\Settings\Exceptions`, with when each is raised and how the REST API answers it. Thirty extend `SettingsException` (a `RuntimeException`) and report run-time failures; `SettingsMisuse` (a `LogicException`) reports a call the package cannot serve. All of them implement `SettingsError`, so one catch takes them all. +Thirty-one exception classes in `Simtabi\Laranail\Settings\Exceptions`, with when each is raised and how the REST API answers it. `SettingsException` (a `RuntimeException`) and the twenty-nine that extend it report run-time failures; `SettingsMisuse` (a `LogicException`) reports a call the package cannot serve. All of them implement `SettingsError`, so one catch takes them all. ## Catching them diff --git a/docs/tools/history.md b/docs/tools/history.md index b938f34..51087b7 100644 --- a/docs/tools/history.md +++ b/docs/tools/history.md @@ -67,7 +67,7 @@ The value of version 3 is read back from the history, decrypted and decoded, the Every store with an active database layer keeps history. For a store on file layers only, `history()`, `rollback()` and `historyDiff()` raise `HistoryUnavailable`. -`reencrypt` (rewriting payloads after a key rotation, history included) is not part of this release. +`laranail::settings.reencrypt` rewrites history payloads too after a key rotation; see [Re-encryption and rescoping](reencryption.md). --- diff --git a/docs/tools/models-and-factories.md b/docs/tools/models-and-factories.md index 28f8439..01121e6 100644 --- a/docs/tools/models-and-factories.md +++ b/docs/tools/models-and-factories.md @@ -1,6 +1,6 @@ # Models and factories -Four Eloquent models, `Setting`, `SettingCategory`, `SettingDefinition` and `SettingAuditEntry`, with factories for tests, seeding and admin screens. +Six Eloquent models, four of them (`Setting`, `SettingCategory`, `SettingDefinition`, `SettingAuditEntry`) with factories for tests, seeding and admin screens; `SettingHistory` and `SettingChangeRequest` have none. ## The models diff --git a/docs/tools/owners.md b/docs/tools/owners.md index 199106f..d3ac2c8 100644 --- a/docs/tools/owners.md +++ b/docs/tools/owners.md @@ -33,7 +33,7 @@ Each store lists the aliases it holds in `owners`, and each alias belongs to one ## Inheritance -Off by default. When a definition says `inherits()`, or the store sets `inherits => true` for keys without a definition, a read for an owner tries: +Off by default. When a definition says `inherits()`, or the store sets `inherits => true` for keys whose definition does not say either way (and keys without one), a read for an owner tries: 1. the owner's own value; 2. each parent's value, in the parent's own store; diff --git a/docs/tools/rest-api-reference.md b/docs/tools/rest-api-reference.md index a100e5e..d4665f3 100644 --- a/docs/tools/rest-api-reference.md +++ b/docs/tools/rest-api-reference.md @@ -151,7 +151,7 @@ Status: `200`, `401`, `403`, `404`. Owner form: `GET /stores/{store}/owners/{alias}/{id}/settings/{key}/history`. -`settings.history`, ability `view_history`. The setting's versions, newest first, paginated (`limit`, `cursor`, `locale`). Payloads are as stored (encrypted values encrypted) and are removed for an actor without `view_sensitive`. +`settings.history`, ability `view_history`. The setting's versions, newest first, paginated (`limit`, `cursor`, `locale`). Encrypted payloads are always `null` (`old_encrypted` and `new_encrypted` say which); the others are as stored, and are removed for an actor without `view_sensitive`. ```json {"data": [{"id": "01JC…", "store": "settings", "setting_ref": "site.name", "scope": "global", "key": "site.name", "locale": "", diff --git a/docs/tools/runtime-configuration.md b/docs/tools/runtime-configuration.md index 9895d36..afa907e 100644 --- a/docs/tools/runtime-configuration.md +++ b/docs/tools/runtime-configuration.md @@ -50,7 +50,7 @@ $report = $settings->withConfiguration( ); ``` -Persisted configuration, saved in the database and edited through the API, arrives with the governance release. +Configuration saved in the database and edited through the API is covered by [Persisted configuration](persisted-configuration.md). --- diff --git a/docs/tools/runtime-overrides.md b/docs/tools/runtime-overrides.md index b2a1163..61b5b29 100644 --- a/docs/tools/runtime-overrides.md +++ b/docs/tools/runtime-overrides.md @@ -31,7 +31,7 @@ use Simtabi\Laranail\Settings\Contracts\Settings; public function handle(Settings $settings): void { - // One key, global: every owner reads it, unless the owner has an override of its own. + // One key, global: owners read it too when the setting inherits, unless they have their own. $settings->override('mail.default', 'log'); // Several keys at once. @@ -152,7 +152,7 @@ flowchart TD Three consequences worth knowing: -- **A global override beats a stored owner value.** `$settings->override('ui.theme', 'dark')` makes every user read `dark`, including a user who saved `light`, unless that user has an override of their own. This is what "override" means here: it sits above the database, not beside the global row. +- **A global override beats a stored owner value.** `$settings->override('ui.theme', 'dark')` makes every user read `dark` when `ui.theme` inherits, including a user who saved `light`, unless that user has an override of their own. This is what "override" means here: it sits above the database, not beside the global row. - **Inheritance is the definition's.** An owner reaches parent and global overrides only when the setting inherits (its definition's `inherits()`, or else the store's `inherits`), exactly as it reaches parent and global stored values. A setting that does not inherit sees only the owner's own override. - **Precedence and locks do not apply.** A definition's `precedence` (`file` or `config`) chooses between stored layers, and a lock stops writes; an override is neither, so it answers for a locked setting and for one whose shipped file normally wins. That is deliberate: the override is a code-level decision made by the application for this request, and it changes nothing anyone else can see. If a value must never differ, do not override it. diff --git a/docs/tools/settings-api.md b/docs/tools/settings-api.md index 392368a..dbee029 100644 --- a/docs/tools/settings-api.md +++ b/docs/tools/settings-api.md @@ -44,7 +44,7 @@ $settings->store('user_settings')->for($user)->locale('fr')->as($admin)->because Abilities are named in the [access control](access-control.md) reference. A handle **without** an actor is trusted code: it is not authorized, and it is audited as `system` (unless `authorization.require_actor` is on, when it throws `ActorRequired`). A handle **with** an actor is authorized for every operation, reads included, and every refusal fires `AccessWasDenied`. -Every exception extends `Simtabi\Laranail\Settings\Exceptions\SettingsException`; the [exceptions reference](exceptions.md) says when each is raised and how the REST API answers it. +Every exception implements `Simtabi\Laranail\Settings\Exceptions\SettingsError`, and all but `SettingsMisuse` (a `LogicException` for a call the package cannot serve) extend `SettingsException`; the [exceptions reference](exceptions.md) says when each is raised and how the REST API answers it. ## Scoping @@ -237,7 +237,7 @@ The store's definitions from code, configuration and the definitions table, in k ## Writing -A write by an actor needs the ability named below, and step-up verification when `verification.abilities` lists it or the definition `requiresVerification()` (`VerificationRequired`, with `VerificationWasRequired` fired). A write to a setting that needs approval opens a change request instead (`ChangeRequested`), and the method still returns normally; on a store that cannot hold change requests it throws `ApprovalUnavailable`. +A write by an actor needs the ability named below, and step-up verification when `verification.abilities` lists it or the definition requires it (`requiresVerification()` when defining it) (`VerificationRequired`, with `VerificationWasRequired` fired). A write to a setting that needs approval opens a change request instead (`ChangeRequested`), and the method still returns normally; on a store that cannot hold change requests it throws `ApprovalUnavailable`. ### `set()` @@ -326,7 +326,7 @@ An override is a value held in memory for the current request or job that answer ```php public function override(string|array $key, mixed $value = null): void -$settings->override('mail.default', 'log'); // global: every owner sees it, unless it has its own +$settings->override('mail.default', 'log'); // global; an owner sees it when the setting inherits $settings->for($user)->override('ui.theme', 'high-contrast'); // this owner only $settings->override(['features.beta' => true, 'limits.seats' => 50]); ``` @@ -606,7 +606,7 @@ The handle's actor, or `null` for trusted code. ```php public function configuration(): RuntimeConfiguration -$settings->configuration()->define('beta.enabled')->ofType('boolean')->withDefault(false); +$settings->configuration()->define('beta.enabled')->ofType('boolean')->withDefault(false)->register(); $settings->configuration()->authorizeUsing(fn ($actor, $ability, $subject) => …); ``` @@ -627,7 +627,7 @@ Applies the changes for the duration of `$run` only, then restores them; returns ## The facade -`Simtabi\Laranail\Settings\Facades\Settings` proxies every method above (its docblock lists them for IDEs). It is application sugar; the package's own classes never use it. +`Simtabi\Laranail\Settings\Facades\Settings` proxies every method above (its docblock lists them for IDEs). It is application sugar: the package's classes take the contract, except the `HasSettings` trait, which runs inside the application's own models and so calls the facade. ```php use Simtabi\Laranail\Settings\Facades\Settings; diff --git a/docs/tools/tenancy.md b/docs/tools/tenancy.md index 8df872b..fd3fb35 100644 --- a/docs/tools/tenancy.md +++ b/docs/tools/tenancy.md @@ -14,7 +14,7 @@ The mode is the one switch in the table shape: the migration adds the column, an reads the same key, so set it before migrating and change it only with a migration. In `column` mode the tenant leads the unique keys (`unique(tenant, scope, key, locale)` on values, `unique(tenant, store, slug)` on categories), so two tenants can hold the same key, and `''` is the central application's rows. The column is -`string(64)` and binary-collated, like `scope`. +`string(64)`, binary-collated on the values, history and change-request tables, like `scope`. Definitions are shared by every tenant: they describe settings, they hold no tenant's values. In `column` mode, synced definitions link to the central (`''`) categories. diff --git a/src/Console/MakeStoreCommand.php b/src/Console/MakeStoreCommand.php index 8082413..6bf58d2 100644 --- a/src/Console/MakeStoreCommand.php +++ b/src/Console/MakeStoreCommand.php @@ -19,7 +19,7 @@ final class MakeStoreCommand extends Command protected $signature = 'laranail::settings.make-store {store : The store name, [a-z][a-z0-9_]*} - {--connection= : A database connection of its own (its categories and audit tables are generated too)} + {--connection= : A database connection of its own (its categories, audit, history and change requests tables are generated too)} {--owner=* : A morph alias the store holds values for (repeat for several)}'; protected $description = 'Generate the migration and configuration for a new settings store';