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
137 changes: 137 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,103 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Approvals (design §16.7, Phase 4b): a write (`set`, `forget`, `lock`, `unlock`) to a setting
whose definition is `requiresApproval()`, or whose key matches the store's new
`approvals.keys` globs, opens a change request instead of writing. A
`settings_change_requests` table (one per connection, ULID keys, tenant column in column-mode
tenancy) is created by the one migration when the new schema switch `approvals.table` is on (the
default). The proposed value is validated and stored as the values table would store it, so an
encrypted definition's value is encrypted at rest. `$settings->propose()` and
`$settings->approvals()` (`Approvals\Approvals`: `pending()`, `status()`, `key()`, `for()`,
`get()`, `find()`, `approve()`, `reject()`, `cancel()`). Approving needs `approve`; the
requester cannot approve their own request unless `approvals.allow_self`; `approvals.min_approvals`
approvals apply the change through the write pipeline against the base version, so a setting
that changed meanwhile makes the request `stale`; requests expire after `approvals.expire_after`
days. Events `ChangeRequested`, `ChangeApproved`, `ChangeApplied`, `ChangeRejected`,
`ChangeCancelled`, `ChangeStale` (the alert listener knows the first four of interest); audit
actions `propose`, `reject`, `cancel` with the change request's id in the `change_request`
column; `laranail::settings.prune-changes`. Enums `ChangeStatus`, `ChangeOperation`; exceptions
`UnknownChangeRequest`, `ChangeRequestClosed`.
- Export, import and store diff (G-10, G-42): `$settings->export(ExportMode)`, `import()`,
`previewImport()`, `compare()`; `laranail::settings.export` (`--with-secrets`, `--decrypt` with
the store name typed), `.import` (dry run unless `--apply`; `--trusted` for locks and system
categories) and `.diff`. Documents name categories by slug and settings by scope, key and locale,
never a numeric id. Imports create categories first and write each setting through the write
pipeline, in one transaction. Gated by `export` / `import`, audited.
- Importers (G-43) behind `Contracts\Importer`: `spatie` (spatie/laravel-settings' table),
`toolkit` (laranail/toolkit's JSON store) and `akaunting` (akaunting/laravel-setting's table),
configured in `importers`, used with `import --from=<name>`. No dependency on any of them.
- `laranail::settings.reencrypt` (`Actions\ReencryptSettings`): encrypts live values, history and
change requests again under the current key, leaving unreadable payloads untouched and
reporting them. `laranail::settings.rescope {from} {to}` (`Actions\RescopeOwners`, G-30) renames
an owner alias in values (with `settable_type` and per-row slugs), history and change requests.
- `doctor` also reports encrypted values no key can read, open change requests past their expiry,
schema drift on the history, change requests and persisted configuration tables, and persisted
entries skipped as invalid.
- Persisted configuration (§16.11): with the new schema switch `configuration.persisted`, a
`settings_stores` table holds stores and layers saved through
`$settings->persistedConfiguration()` (and the REST API), and definitions are saved to the
definitions table. Validated like configuration, gated (`manage_stores`, `manage_definitions`),
audited, read on first use and merged in `configuration.sources` order; an invalid entry is
logged and skipped.
- The REST API (§16.10, Phase 4c), off unless `http.enabled`: 39 routes under `http.prefix`/v1
named `laranail-settings.api.*`, through `http.middleware`, the `laranail-settings` rate limiter
and an `Idempotency-Key` cache for writes. Route → FormRequest → controller → the same actions
the PHP API runs (`Enums\Capability`), API resources, ETags with `If-Match` (412), `202` with a
change request for approvals, cursor-paginated lists, values the actor may not view left out,
RFC 9457 problem details, `Contracts\OwnerResolver` (morph map by default; unknown alias 404).
New read actions `Actions\Reads\{ReadSetting, ReadSettings, ExplainSetting, ReadHistory,
ListStores, ListDefinitions}` and `Actions\Categories\ListCategories`.
`laranail::settings.openapi` writes an OpenAPI 3.1 document; the tests validate responses
against it.
- Typed settings classes (Phase 5): `Typed\TypedSettings` with `load()`, `save()`,
`register()` and the attributes `#[Store]`, `#[Group]`, `#[Key]`, `#[Encrypted]`, `#[Type]`;
typed classes resolve from the container loaded, and `typed.classes` registers their
definitions. Settings migrations (G-17): `Typed\SettingsMigration` with `rename()`, `move()`,
`add()` and `delete()` (`Actions\MigrateSettings`, audited as `migrate`).
- Value history (design §4.3, Phase 4): a `settings_history` table, one per connection like the
audit table, created by the one migration when the new schema switch `history.enabled` is on
(the default; recorded in the schema file as `history_table`, and read as off from a file
recorded before it existed). Every set, forget, lock, unlock and rollback on a database layer
appends the payload before and after exactly as stored (encrypted values stay encrypted), the
operation, the version, the causer (the actor; `system` without one), the reason and the row's
`uid` (or id) as `setting_ref`, in the same transaction as the change, so a failed history
insert rolls the change back. A forget writes a tombstone, and a key set again continues its
version from the history. Column-mode tenancy adds a `tenant` column. New config
`tables.history`, `history.enabled`, `history.keep_days` (365) and `history.keep_versions`
(null).
- `$settings->history()` (`History\HistoryQuery`: `key()`, `for()`, `global()`, `store()`,
`locale()`, `since()`, `until()`, `versions()`, then `get()`, `cursor()` or `paginate()`),
gated by `view_history`; payloads of encrypted or sensitive settings are removed for an actor
without `view_sensitive`. `$settings->rollback($key, $toVersion)` writes an earlier value as a
new version through the normal write pipeline (gated by `rollback`, step-up verification per
`verification.abilities`, audited as `rollback`) and returns the new version.
`$settings->historyDiff($key, $from, $to)` returns a `Data\HistoryDiff`, decrypting only for an
actor holding `view_sensitive` (or a trusted call). Actions `QueryHistory`, `RollbackSetting`,
`DiffHistory`, `PruneHistory` and the bundle `HistoryActions`; `Services\Database\HistoryRepository`;
`Data\HistoryEntry`, `HistoryFilter`, `HistoryPage`, `HistoryDiff`; `Enums\HistoryOperation`;
`Exceptions\HistoryUnavailable`; `DatabaseDriver::reference()`; `SettingWriter::causedBy()` and
`rollback()`.
- `laranail::settings.history {key}` (`--store`, `--owner=alias:id`, `--locale`,
`--diff=FROM..TO`, `--rollback=`, `--reveal`, `--limit`) and `laranail::settings.prune-history`
(`--days`, `--versions`; gated by `prune`, audited).
- Events: `SettingLocked`, `SettingUnlocked`, `SettingRolledBack`, `CategoryMoved`,
`CategoryRenamed`, `DefinitionsSynced`, `AuditPruned`, `HistoryPruned`, `OrphansPruned` (all
after commit), and `AccessWasDenied` and `VerificationWasRequired`, dispatched at once by the
access guard when it refuses (the refusal throws, so its transaction rolls back). None carries
a value.
- Built-in listeners, switchable under `listeners.*`: `Listeners\SendSettingsAlert` (on, but
needs `alerts.enabled`) and `Listeners\LogSettingsEvent` (off; every event to the operational
log, refusals at `warning`).
- Alerts (`alerts.enabled`, default `false`): Laravel notifications (`Notifications\SettingsAlert`)
sent when an event matches a rule in `alerts.rules` (events, key globs, stores,
`sensitive_only`, outcomes; `notify.mail`, `notify.slack` when
laravel/slack-notification-channel is installed, `notify.database`; `queue`), throttled per
rule and key for `alerts.throttle` seconds in `alerts.cache`. An alert carries identifiers only
(`Data\AlertContext`), never a value; a test renders every channel of alerts about a seeded
secret and fails if it appears. An alert that cannot be sent is logged, never thrown.
`Data\AlertRule`, `Support\EventSummary`.
- `CategoryGuard::run()` takes an optional list of further events to dispatch after commit.
- The settings cache (design phase 3, §7.5): `Drivers\CachingDriver` puts each database layer
behind `Caching\SettingsCache`, which caches every scope's raw rows (a "bag", every locale,
misses as empty bags) keyed by a hashed, length-prefixed tuple of connection, database, tenant,
Expand Down Expand Up @@ -82,6 +179,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- A write to a setting that needs approval opens a change request where the store can hold one;
`ApprovalUnavailable` is now raised only where it cannot (no active database layer, or no
change requests table). `SetSetting`, `ForgetSetting`, `LockSetting` and `UnlockSetting` return
the change request they opened (null when they wrote), and `WriteGuard::run()` takes an optional
proposal and returns it.
- The `Settings` contract gains `propose()`, `approvals()`, `export()`, `import()`,
`previewImport()`, `compare()` and `persistedConfiguration()` (pre-1.0; `SettingsManager` and
the fake implement them).
- The schema-switch matrix covers `approvals.table`: 11 pairwise shapes for 261 pairs per pull
request, 4,608 shapes in the weekly full product.
- The test suite runs with a 512 MB memory limit (`phpunit.xml`).
- Every service now lives under `Services\` (Phase 4 plan §1), moved verbatim:
`Services\Database\{AuditRepository, CategoryRepository, DefinitionsRepository, SchemaInspector,
SchemaShapeRepository}`, `Services\Stores\{SettingWriter, StoreRegistry}`,
`Services\Resolution\{Resolver, PreloadedRecords}`, `Services\Access\{AccessGuard, Auditor}`,
`Services\Configuration\RuntimeConfiguration`,
`Services\Definitions\{DefinitionRegistry, DatabaseDefinitions}`,
`Services\Tenancy\TenantDiscriminators`, `Services\Casting\CasterRegistry`,
`Services\Values\ValuePipeline`, `Services\Drivers\DriverFactory` and
`Services\Cache\SettingsCache`. The package's own code uses the new names. Architecture tests
keep contract implementations out of `Services\` and every `*Repository` / `*Registry` in it.
- The `Settings` contract gains `history()`, `rollback()` and `historyDiff()`. A third-party
implementation must add them (pre-1.0; `SettingsManager` and the fake implement them).
- With history on, a key set again after a forget continues its version (previously it started
again at 1), so "version N" names one value.
- The access guard dispatches `AccessWasDenied` / `VerificationWasRequired` when given a
dispatcher (the container's guard is); `PruneAudit`, `PruneOrphans` and `SyncDefinitions`
take an optional dispatcher for their new events.
- The schema-switch matrix covers `history.enabled`: 11 pairwise shapes for 217 pairs per pull
request, 2,304 shapes in the weekly full product.
- The code is layered entry points → actions → services → support, held by architecture
tests. Database work moved out of actions into `Database\AuditRepository` (the audit sink,
query and prune), `Database\DefinitionsRepository` (definitions sync and reads) and
Expand All @@ -101,6 +228,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Deprecated

- The old names of the 19 classes moved into `Services\` (listed under Changed):
`Database\AuditRepository`, `Database\CategoryRepository`, `Database\DefinitionsRepository`,
`Database\SchemaInspector`, `Database\SchemaShapeRepository`, `Stores\SettingWriter`,
`Stores\StoreRegistry`, `Resolution\Resolver`, `Resolution\PreloadedRecords`,
`Authorization\AccessGuard`, `Audit\Auditor`, `Configuration\RuntimeConfiguration`,
`Definitions\DefinitionRegistry`, `Definitions\DatabaseDefinitions`,
`Tenancy\TenantDiscriminators`, `Casting\CasterRegistry`, `Support\ValuePipeline`,
`Drivers\DriverFactory` and `Caching\SettingsCache`. Each still resolves to the moved class
through `class_alias` in `src/deprecated-aliases.php` (Composer `autoload.files`), so imports,
type declarations, container bindings and `instanceof` keep working; removed in 1.0.
- `PruneOrphans::find()`: use `FindOrphans::handle()`. It forwards; removed in 1.0.
- `DatabaseDefinitions::localised()`: use `Support\Translations::nullableText()`. It forwards;
removed in 1.0.
Expand Down
33 changes: 29 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@ They are added once each claim is true.

Requires PHP 8.4.1+ or 8.5 and Laravel 13. Works on MySQL, PostgreSQL and SQLite; SQL Server is not supported in 0.x.

> **Pre-release.** The engine reads and writes through database, file and config layers;
> caching and history arrive in the next phases. See [Getting started](docs/getting-started.md).
> **Pre-release.** The engine, caching, history, approvals, import and export, the opt-in REST API
> and typed settings classes are built; the 0.1 release is being prepared. See
> [Getting started](docs/getting-started.md).

## Install

Expand All @@ -24,7 +25,7 @@ composer require laranail/settings
### Getting started

Publish the config and the package's one migration (it creates `settings_categories`, a values
table per database store, and `settings_audit`), migrate, and optionally seed the default
table per database store, `settings_audit`, `settings_history` and `settings_change_requests`), migrate, and optionally seed the default
categories: the default store reads the database first, then its runtime file, then shipped
defaults from `settings/defaults.php` when that file exists.

Expand Down Expand Up @@ -61,6 +62,15 @@ Settings::for($user)->get('ui.theme', 'light');
Settings::as($user)->because('INC-123')->set('mail.from.address', 'ap@acme.test');
```

```php
// A typed class over the same keys (loaded and saved through the same write actions).
$mail = MailSettings::load(Settings::as($user));
$mail->fromAddress = 'ops@acme.test';
$mail->save();
```

The JSON REST API is off until `http.enabled` is true; see [REST API](docs/tools/rest-api.md).

[Getting started](docs/getting-started.md) walks through stores, owners and definitions; the
[Documentation](#documentation) index lists every page.

Expand All @@ -83,7 +93,7 @@ The hosted docs live at <https://opensource.simtabi.com/documentation/laranail/s
- [Drivers and layers](docs/tools/drivers.md) — the built-in drivers and custom ones.
- [Database](docs/tools/database.md) — the tables, version-checked writes, eager loading and `HasSettings`.
- [Categories](docs/tools/categories.md) — nested, per-store categories and the rules that guard them.
- [Commands](docs/tools/commands.md) — install, make-store, promote, doctor, warm, clear-cache and the prune commands.
- [Commands](docs/tools/commands.md) — install, make-store, promote, doctor, warm, clear-cache, history, export, import, diff, reencrypt, rescope, openapi and the prune commands.
- [Owners and inheritance](docs/tools/owners.md) — owner references, store routing and the cascade.
- [Access control](docs/tools/access-control.md) — actors, abilities, authorizers, guarded locks, sensitive reads and step-up verification.
- [Audit and logging](docs/tools/audit-and-logging.md) — the audit trail, its sinks and the operational log.
Expand All @@ -93,6 +103,16 @@ The hosted docs live at <https://opensource.simtabi.com/documentation/laranail/s
- [Tenancy](docs/tools/tenancy.md) — tenant column or database per tenant, the discriminator, and the stancl and spatie adapters.
- [Models and factories](docs/tools/models-and-factories.md) — Eloquent models and factories for tests, seeding and admin screens.
- [Caching](docs/tools/caching.md) — per-scope bags, tenant-safe keys, generation tokens and stale-while-revalidate.
- [History](docs/tools/history.md) — every value by version, rollback and diffs, and retention.
- [Events](docs/tools/events.md) — every event, when it is dispatched, and the built-in listeners.
- [Alerts](docs/tools/alerts.md) — notifications on changes and refusals, by rule, throttled, never with a value.
- [Approvals](docs/tools/approvals.md) — four-eyes change requests: proposing, approving, stale and expired requests.
- [Import and export](docs/tools/import-export.md) — portable JSON documents, secrets modes, dry runs and store diffs.
- [Importers](docs/tools/importers.md) — moving in from spatie/laravel-settings, toolkit's JSON store and akaunting/laravel-setting.
- [Re-encryption and rescoping](docs/tools/reencryption.md) — after an `APP_KEY` rotation, and after renaming a morph alias.
- [Persisted configuration](docs/tools/persisted-configuration.md) — stores, layers and definitions kept in the database.
- [REST API](docs/tools/rest-api.md) — the opt-in JSON API: endpoints, ETags, approvals, problem details, idempotency and OpenAPI.
- [Typed settings](docs/tools/typed-settings.md) — typed classes over the key-value engine, and settings migrations.

### Recipes

Expand All @@ -102,6 +122,11 @@ The hosted docs live at <https://opensource.simtabi.com/documentation/laranail/s
- [Move from files to the database](docs/recipes/moving-from-files-to-the-database.md) — bootstrap mode during install, then promotion.
- [Seed the default categories](docs/recipes/seeding-default-categories.md) — the shipped set, your own set, and per tenant.
- [Warm the cache after a deploy](docs/recipes/warming-the-cache.md) — warm, and reset after changing rows by hand.
- [Roll back a setting](docs/recipes/rolling-back-a-setting.md) — find a version, compare it, return to it.
- [Listen to settings events](docs/recipes/listening-to-settings-events.md) — your own listeners, and reading the new value.
- [Approve a change](docs/recipes/approving-a-change.md) — require a second person, then review and apply.
- [Call the REST API with Sanctum](docs/recipes/calling-the-rest-api-with-sanctum.md) — a token with an ability ceiling, ETags and idempotency.
- [Migrate from spatie/laravel-settings](docs/recipes/migrating-from-spatie-laravel-settings.md) — import the values and keep typed classes.

## Contributing & security

Expand Down
2 changes: 1 addition & 1 deletion benchmarks/ReadBench.php
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
use Illuminate\Support\Facades\Artisan;
use Simtabi\Laranail\Settings\Data\OwnerRef;
use Simtabi\Laranail\Settings\Contracts\Settings;
use Simtabi\Laranail\Settings\Caching\SettingsCache;
use Simtabi\Laranail\Settings\Services\Cache\SettingsCache;
use Orchestra\Testbench\Foundation\Application as Testbench;
use Simtabi\Laranail\DbTools\Providers\DbToolsServiceProvider;
use Simtabi\Laranail\Settings\Providers\SettingsServiceProvider;
Expand Down
5 changes: 4 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,10 @@
"Simtabi\\Laranail\\Settings\\": "src/",
"Simtabi\\Laranail\\Settings\\Database\\Factories\\": "database/factories/",
"Simtabi\\Laranail\\Settings\\Database\\Seeders\\": "database/seeders/"
}
},
"files": [
"src/deprecated-aliases.php"
]
},
"autoload-dev": {
"psr-4": {
Expand Down
Loading
Loading