Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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,
Expand Down
6 changes: 3 additions & 3 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.

---

Expand Down
2 changes: 1 addition & 1 deletion docs/recipes/acting-as-a-user.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
2 changes: 1 addition & 1 deletion docs/recipes/auditing-a-change.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
10 changes: 7 additions & 3 deletions docs/recipes/building-a-preferences-screen.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/recipes/building-an-admin-ui-on-the-rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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()),
]);

Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/recipes/calling-the-rest-api-with-sanctum.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
4 changes: 2 additions & 2 deletions docs/recipes/migrating-from-spatie-laravel-settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 (`<connection>:<table>`). Each row becomes the key `<group>.<name>`; `--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 (`<connection>:<table>`). Each row becomes the key `<group>.<name>`; `--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

Expand All @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/recipes/moving-settings-between-environments.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions docs/recipes/testing-with-the-fake.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/access-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|
Expand Down
4 changes: 2 additions & 2 deletions docs/tools/audit-and-logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
6 changes: 3 additions & 3 deletions docs/tools/commands.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Commands

Nineteen Artisan commands, all named `laranail::settings.<command>`.
Eighteen Artisan commands, all named `laranail::settings.<command>`.

## The commands

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/tools/definitions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/exceptions.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/tools/history.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

---

Expand Down
2 changes: 1 addition & 1 deletion docs/tools/models-and-factories.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/tools/owners.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/rest-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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": "",
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/runtime-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

---

Expand Down
Loading
Loading