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';