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
10 changes: 8 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,15 @@ jobs:
run: |
version="${GITHUB_REF_NAME#v}"
notes=$(awk -v v="$version" '
$0 ~ "^## \\[" v "\\]" { f=1; next }
index($0, "## [" v "]") == 1 { f=1; next }
f && /^## \[/ { exit }
f { print }
' CHANGELOG.md)
# A final release must describe itself; only a pre-release (vX.Y.Z-rc.N) may fall back.
if [ -z "$(printf '%s' "$notes" | tr -d '[:space:]')" ] && [[ "$GITHUB_REF_NAME" != *-* ]]; then
echo "::error::CHANGELOG.md has no '## [$version]' section with content; add it before tagging."
exit 1
fi
{
echo "body<<__CHANGELOG_EOF__"
if [ -n "$notes" ]; then printf '%s\n' "$notes"; else
Expand All @@ -62,8 +67,9 @@ jobs:
} >> "$GITHUB_OUTPUT"

- name: Create GitHub release
uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4
with:
generate_release_notes: true
prerelease: ${{ contains(github.ref_name, '-') }}
body: ${{ steps.changelog.outputs.body }}
files: settings.cdx.json
655 changes: 141 additions & 514 deletions CHANGELOG.md

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,9 @@ php artisan db:seed # general, appearance, localisation, mail, notifications
```

For multi-tenant applications set `tenancy.mode` before migrating (see
[Tenancy](docs/tools/tenancy.md)).
[Tenancy](docs/tools/tenancy.md)). To keep values per owner, list the owner's morph alias in a
store's `owners` (for example `'owners' => ['user']` under `stores.settings`); an alias no store
lists raises `OwnerNotAllowed`.

An application without a database drops `database` from `stores.settings.layers` and keeps its
values in `storage/app/private/laranail/settings/settings.json`.
Expand Down
8 changes: 8 additions & 0 deletions config/settings.php
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,14 @@
'retry_on_conflict' => true,
],

/*
| max_bytes: the largest value a write accepts, measured as the encoded
| payload before encryption; null for no limit.
*/
'values' => [
'max_bytes' => env('LARANAIL_SETTINGS_MAX_VALUE_BYTES', 1048576),
],

/*
| The cache in front of database layers.
|
Expand Down
1 change: 1 addition & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings.
| Key | Default | Purpose |
|---|---|---|
| `writes.retry_on_conflict` | `true` | retry a plain `set()` once after a concurrent change |
| `values.max_bytes` | `1048576` (`LARANAIL_SETTINGS_MAX_VALUE_BYTES`) | the largest value a write accepts, as its encoded payload before encryption; `null` for no limit; a larger value raises `InvalidSettingValue` |
| `seed.enabled` | `true` (`LARANAIL_SETTINGS_SEED`) | whether `db:seed` creates the default categories |
| `seed.stores` | `[]` | the stores to seed; empty means the default store |
| `seed.categories` | general, appearance, localisation, mail, notifications, security | `slug => title` or `slug => [title, description, icon, parent, sort_order, translations]` |
Expand Down
3 changes: 2 additions & 1 deletion docs/tools/audit-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ at either end) and `hasMore()`.
## Access

With an actor on the handle, every run needs `view_audit` (checked against the filtered store,
key and owner); a denial is itself audited. Without an actor the call is trusted, unless
key and owner); a denial is itself audited. Without `store()`, the query returns entries of the
stores the actor may audit only, and is refused when there is none. Without an actor the call is trusted, unless
`authorization.require_actor` is on. Entries never carry a value, encrypted or not, so there is
nothing to redact.

Expand Down
2 changes: 1 addition & 1 deletion docs/tools/exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Messages name the store, key, scope and ability involved, never a value, so they
| `UnknownCategory` | `SettingsException` | no category with the slug exists in the store | `404 unknown-category` |
| `CategoryCycle` | `SettingsException` | moving a category under itself or a descendant | `422 category-cycle` |
| `CategoryStoreMismatch` | `SettingsException` | a category belongs to another store than what refers to it | `422 category-store-mismatch` |
| `InvalidSettingValue` | `SettingsException` | a value failed its definition's rules, cast or locale constraints | `422 invalid-value` |
| `InvalidSettingValue` | `SettingsException` | a value failed its definition's rules, cast or locale constraints, or its payload is larger than `values.max_bytes` | `422 invalid-value` |
| `TypeMismatch` | `SettingsException` | a typed getter (`string()`, `integer()`, …) or a typed settings property found another type, or no value | `422 type-mismatch` |
| `InvalidIdentifier` | `SettingsException` | a store name, locale, owner alias or filter failed validation | `422 invalid-identifier` |
| `InvalidKey` | `InvalidIdentifier` | a key is not lower-case dot notation of `[a-z0-9_]` segments, at most 191 characters; or `many()` got a non-string list entry | `422 invalid-identifier` |
Expand Down
4 changes: 2 additions & 2 deletions docs/tools/persisted-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,13 @@ $editor->saveDefinition('site.theme', ['type' => 'string', 'default' => 'light',
$editor->deleteDefinition('site.theme');
```

Store and layer entries take the shape the configuration file gives `stores.<name>` and `layers.<name>`; definitions take the attributes of `definitions.<key>`. Each change is validated exactly like configuration before it is stored, needs `manage_stores` (step-up verification by default) or `manage_definitions`, and is audited. A definition from code or configuration cannot be overridden or deleted here, and a persisted store may not change the layers the configuration file gives a store: moving data between drivers is [promote](commands.md)'s job.
Store and layer entries take the shape the configuration file gives `stores.<name>` and `layers.<name>`; definitions take the attributes of `definitions.<key>`. Each change is validated exactly like configuration before it is stored, needs `manage_stores` (step-up verification by default) or `manage_definitions`, and is audited. A definition from code or configuration cannot be overridden or deleted here, and a persisted store may not change the layers the configuration file gives a store: moving data between drivers is [promote](commands.md)'s job. A persisted layer only adds to the file's: one named like a layer the configuration file defines is refused. It may not use the `php` or `config` driver: the first requires the file it names and the second reads application configuration, so both are defined in the configuration file only.

## Loading

Persisted entries are read on first use, never at boot, once per request or job. An entry that fails validation (a layer that no longer exists, a driver that is not registered) is logged to the operational log and skipped, so a bad row never stops the application from booting; `doctor` lists what was skipped.

`configuration.sources` decides precedence: with `['config', 'database', 'runtime']` a persisted entry overrides the file, and a change made in code for one request ([runtime configuration](runtime-configuration.md)) overrides both. Put `database` first to let the file win.
`configuration.sources` decides precedence: with `['config', 'database', 'runtime']` a persisted store entry overrides the file's (layers never: see above), and a change made in code for one request ([runtime configuration](runtime-configuration.md)) overrides both. Put `database` first to let the file win.

---

Expand Down
8 changes: 4 additions & 4 deletions docs/tools/rest-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ Paths are under `/{http.prefix}/v1`, by default `/api/settings/v1`; set `http.pr
| Owners | a settings route has a global form (`/stores/{store}/settings/…`) and an owner form (`/stores/{store}/owners/{alias}/{id}/settings/…`). `{alias}` is a morph alias from `http.owners` or the morph map, never a class name. |
| Locales | `?locale=fr` on settings routes; the write routes also take it. |
| Bodies | JSON. Every write may send `"reason"` (recorded in the audit trail and history). |
| ETags | setting responses carry `ETag`. Send it back as `If-Match` on `PUT` or `DELETE`: a mismatch is `412`; `*` matches any version. |
| Idempotency | every non-`GET` route accepts `Idempotency-Key`; a retry with the same key, user, method and path within `http.idempotency.ttl` (24 hours) is answered from cache with `Idempotent-Replayed: true`. |
| Pagination | lists answer `{"data": [...], "meta": {"next_cursor": "…" or null}}`; pass `?cursor=<next_cursor>` and `?limit=` (1 to 200, default `http.page_size`). Cursors are opaque. |
| ETags | setting responses carry `ETag`. Send it back as `If-Match` on `PUT` or `DELETE`: a mismatch is `412`, and the write or delete applies only at that version, so a change made after the check is also `412`; `*` matches any version. |
| Idempotency | every non-`GET` route accepts `Idempotency-Key`; a retry with the same key, actor, host, method and path within `http.idempotency.ttl` (24 hours) is answered from cache with `Idempotent-Replayed: true`. The same key with a different body answers `422` (`http-422`) and applies nothing. |
| Pagination | lists answer `{"data": [...], "meta": {"next_cursor": "…" or null}}`; pass `?cursor=<next_cursor>` and `?limit=` (1 to 200, default `http.page_size`). Cursors are opaque; one the listing did not hand out answers `422` (`validation`). |
| Visibility | values the actor may not view are left out of lists; a single setting answers `"redacted": true` without `value`. |
| Approvals | a write to a setting that needs approval answers `202` with the change request instead of the setting. |
| Errors | RFC 9457 `application/problem+json`; see [Problem types](#problem-types). |
Expand Down Expand Up @@ -179,7 +179,7 @@ Answers `200` with the setting as now read. Status: `200`, `401`, `403`, `404`,

### `GET /audit`

`audit.index`, ability `view_audit`. The audit trail, newest first. Entries never hold values. Filters: `store`, `scope` (`global` or `alias:id`), `key`, `action` (an `AuditAction` value such as `set`, `forget`, `rollback`), `outcome` (`allowed`, `denied`, `pending`, `failed`), `since`, `until` (dates); plus `limit`, `cursor`.
`audit.index`, ability `view_audit`. The audit trail, newest first; without `store`, of the stores the actor may audit only (`403` when none). Entries never hold values. Filters: `store`, `scope` (`global` or `alias:id`), `key`, `action` (an `AuditAction` value such as `set`, `forget`, `rollback`), `outcome` (`allowed`, `denied`, `pending`, `failed`), `since`, `until` (dates); plus `limit`, `cursor`.

```json
{"data": [{"id": "01JC…", "occurred_at": "2026-11-10T09:12:00+00:00", "action": "set", "outcome": "allowed",
Expand Down
6 changes: 3 additions & 3 deletions docs/tools/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,12 @@ Idempotency-Key: 6c0d1e8e-…
"layer": "database", "from": "global", "version": 2, "redacted": false, "value": "Acme Ltd"}}
```

- **ETags.** Every setting response carries an `ETag` derived from store, scope, key, locale and version. Send it back as `If-Match` and the write is checked against that version; a mismatch answers `412`.
- **ETags.** Every setting response carries an `ETag` derived from store, scope, key, locale and version. Send it back as `If-Match` and the write or delete applies only at that version; a mismatch answers `412`.
- **Approvals.** A write to a setting that needs approval answers `202 Accepted` with the change request.
- **Lists** are `{"data": [...], "meta": {"next_cursor": …}}`; pass `?cursor=` for the next page and `?limit=` (1-200).
- **Lists** are `{"data": [...], "meta": {"next_cursor": …}}`; pass `?cursor=` for the next page and `?limit=` (1-200). A cursor the list did not hand out answers `422`.
- **Locales**: `?locale=fr`.
- **Values the actor may not view** are left out, not masked: a list skips the key, a single setting answers `"redacted": true` without `value`.
- **Idempotency.** A write with an `Idempotency-Key` header is answered from cache when retried (same user, method, path and key) for `http.idempotency.ttl` seconds (24 hours), with `Idempotent-Replayed: true`.
- **Idempotency.** A write with an `Idempotency-Key` header is answered from cache when retried (same actor, host, method, path and key) for `http.idempotency.ttl` seconds (24 hours), with `Idempotent-Replayed: true`. A retry with the same key and a different body is refused with `422` and applies nothing. The stored response is encrypted with the application key, since it can hold an encrypted setting's value; without an application key, or without an actor, nothing is stored.

## Errors

Expand Down
9 changes: 6 additions & 3 deletions docs/upgrading.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,12 @@ its replacement.

A checkout from before the single migration published four migrations
(`create_settings_categories_table`, `create_settings_table`, `create_settings_audit_table`,
`create_settings_definitions_table`). They stay in your `database/migrations` and keep working; do
not publish the new one next to them, or the tables would be created twice. Store migrations
written by an older `make-store` keep working too.
`create_settings_definitions_table`). They no longer work: they import classes removed before the
tag (`SchemaShapeRepository`, `IdentityMode`, `OwnerKeyType`, `TranslationsMode`), so a fresh
`migrate` stops on them, and the tables they made have the old shape (integer keys, `slug`, no
`uid`), which 0.1.0 does not read. Delete them and the store migrations an older `make-store`
wrote, publish the one migration with `install`, and create the tables again; copy any values
you need across before dropping the old tables.

1. Compare your `config/laranail/settings.php` with the package's `config/settings.php`, and drop
any key that [Configuration](configuration.md) does not list.
Expand Down
23 changes: 16 additions & 7 deletions src/Actions/Approvals/ApproveChange.php
Original file line number Diff line number Diff line change
Expand Up @@ -75,11 +75,23 @@ public function handle(ChangeDecision $decision, ?Actor $actor = null): ChangeRe
throw AccessDenied::for(Ability::Approve, $subject, 'the requester cannot approve their own change request');
}

$approvals = array_values(array_unique([...$request->approvals, ChangeRequest::actorKey($actor ?? Actor::system())]));
$remaining = max(0, $this->policy->minApprovals - count($approvals));
// Counted under a row lock, so two approvals recorded at once both count.
[$approvals, $remaining] = $database->transaction(function () use ($database, $store, $request, $subject, $actor, $decision, $now): array {
$current = $database->attempt($store->name, static fn (): ChangeRequest => SettingChangeRequest::locked($database->connectionName(), $store->name, $request->id));
$approvals = array_values(array_unique([...$current->approvals, ChangeRequest::actorKey($actor ?? Actor::system())]));
$remaining = max(0, $this->policy->minApprovals - count($approvals));

if ($remaining > 0) {
$this->record($database, $current, $subject, $actor, $decision->reason, $approvals, $remaining, $now);
}

return [$approvals, $remaining];
}, $store->name);

if ($remaining > 0) {
return $this->record($database, $request, $subject, $actor, $decision->reason, $approvals, $remaining, $now);
$this->events->dispatch(new ChangeApproved($request->id, $request->store, $request->scope, $request->key, $request->locale, $request->operation->value, $remaining));

return $database->attempt($store->name, static fn (): ChangeRequest => SettingChangeRequest::get($database->connectionName(), $store->name, $request->id));
}

try {
Expand Down Expand Up @@ -113,16 +125,13 @@ public function handle(ChangeDecision $decision, ?Actor $actor = null): ChangeRe
}

/** @param list<string> $approvals */
private function record(DatabaseDriver $database, ChangeRequest $request, Subject $subject, ?Actor $actor, ?string $reason, array $approvals, int $remaining, CarbonImmutable $now): ChangeRequest
private function record(DatabaseDriver $database, ChangeRequest $request, Subject $subject, ?Actor $actor, ?string $reason, array $approvals, int $remaining, CarbonImmutable $now): void
{
if (! $database->attempt(new StoreName($request->store), static fn (): bool => SettingChangeRequest::transition($database->connectionName(), $request, [ChangeStatus::Pending, ChangeStatus::Approved], ChangeStatus::Approved, null, null, $now, $approvals))) {
throw new ChangeRequestClosed(sprintf('Change request [%s] was decided by somebody else first.', $request->id));
}

$this->access->auditor()->record(AuditAction::Approve, AuditOutcome::Pending, $subject, $actor, $reason, meta: ['change_request' => $request->id, 'remaining' => $remaining]);
$this->events->dispatch(new ChangeApproved($request->id, $request->store, $request->scope, $request->key, $request->locale, $request->operation->value, $remaining));

return $database->attempt($subject->store, static fn (): ChangeRequest => SettingChangeRequest::get($database->connectionName(), $subject->store, $request->id));
}

private function assertOpen(DatabaseDriver $database, ChangeRequest $request, CarbonImmutable $now): void
Expand Down
19 changes: 13 additions & 6 deletions src/Actions/ForgetSetting.php
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,20 @@ public function __construct(
private WriteGuard $guard,
) {}

/** @return ?ChangeRequest the change request opened instead, when the setting needs approval */
public function handle(SettingTarget $target, ?Actor $actor = null): ?ChangeRequest
/**
* @param ?int $expectedVersion forget only while the row is at this version (0: no row)
*
* @return ?ChangeRequest the change request opened instead, when the setting needs approval
*/
public function handle(SettingTarget $target, ?Actor $actor = null, ?int $expectedVersion = null): ?ChangeRequest
{
return $this->guard->run(Ability::Forget, $target, $actor, respectsLocks: true, write: function (bool $override) use ($target, $actor): array {
$removed = $override
? $this->writer->causedBy($actor, $target->reason)->forgetOverridingLock($target->store, $target->key, $target->locale, $target->owner, $target->definition)
: $this->writer->causedBy($actor, $target->reason)->forget($target->store, $target->key, $target->locale, $target->owner, $target->definition);
return $this->guard->run(Ability::Forget, $target, $actor, respectsLocks: true, write: function (bool $override) use ($target, $actor, $expectedVersion): array {
$writer = $this->writer->causedBy($actor, $target->reason);
$removed = match (true) {
$expectedVersion !== null => $writer->forgetExpecting($target->store, $target->key, $target->locale, $target->owner, $target->definition, $expectedVersion, $override),
$override => $writer->forgetOverridingLock($target->store, $target->key, $target->locale, $target->owner, $target->definition),
default => $writer->forget($target->store, $target->key, $target->locale, $target->owner, $target->definition),
};

return [$removed?->version, null];
}, proposal: new ChangeProposal($target, ChangeOperation::Forget));
Expand Down
Loading
Loading