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
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,5 @@ composer.lock
.phpunit.cache
.php-cs-fixer.cache
.DS_Store
# Design, ledger and audit files never enter the repository (design §8).
# Local design, ledger and audit notes stay out of the repository.
/.claude/
44 changes: 44 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Automatic promotion. A store set to `promote: auto` (or every store, with
`LARANAIL_SETTINGS_PROMOTE=auto`) copies its runtime file into its database layer once, the
first time the connection answers and its table exists: straight after `migrate`, or after the
first request or queued job that finds the database ready, once the response is sent. It runs as
the system under the promotion lock, skips keys that already have a row, and archives the file.
A failure is logged and retried on the next run, and reads keep coming from the file until then.
`manual`, the default, keeps today's behaviour. The runtime configuration's
`promote($store, $mode)` sets it per request, and `Settings::promoteWhenReady()` promotes now
when it can and otherwise sets the store to `auto` for the rest of the request, job or command.
`doctor` warns about an `auto` store whose file is still there while its database is ready.
- Selective promotion. `promote` also takes a long form, `['mode' => 'auto', 'include' =>
['settings', 'owners'], 'owners' => ['user', 'team']]`: `settings` are the application-wide
values, `owners` the per-owner values, optionally limited to some morph aliases (`['*']`, the
default, is everything; the runtime file holds setting values only, so these are the only
kinds). The archive keeps the whole original file, and the values left out are written back to
the runtime file in one rename, so they keep answering reads from there. `laranail::settings.promote`
takes `--only=settings,owners` and `--owner=user,team`, `promoteWhenReady()` and the runtime
configuration's `promote()` take a `PromotionSelection`, and `PromotionReport` lists what was
`kept`.
- Fluent promotion setters: `Settings::store('settings')->promotion()->auto()->only('owners')
->forOwners('user')` (also `manual()`, `everything()`, `forAllOwners()`), for the current
request or job. Each option is resolved in one place, highest first: the fluent setters, the
runtime configuration, persisted configuration, then the configuration file. Automatic promotion,
`promoteWhenReady()`, `doctor` and the command's defaults all read that result, and `SettingsFake`
supports the chain.
- `laranail::settings.show` reads a cached answer's row past the cache and prints its `Stored`
version and whether the `Cache` is stale.
- `doctor` warns when a dedicated store's `owner_id` column does not have the type of the owner
table's key (`<store>: owner key`).

- `laranail::settings.show {key} [--store=] [--owner=] [--locale=] [--reveal]`: prints how one
setting resolves (value, layer, scope, type, version, locked, encrypted and sensitive flags, and
the latest audit entry), through the same `ExplainSetting` action as `explain()`. Sensitive and
Expand Down Expand Up @@ -209,6 +239,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- REST listings read `http.page_size` (default 50, clamped to 1 to 200) for a request without
`?limit=`; the key was documented as reserved and every listing used 50.
- Sanctum token abilities are vendor-scoped: `laranail-settings:<ability>` and
`laranail-settings:*`, in place of `settings:<ability>` and `settings:*`. Issue tokens with the
new names; a token holding only the old names is refused.
- Problem `type` URIs point at sections of the exceptions reference,
`https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#<type>`
(`#http-status` for every `http-<status>` type), instead of `…/settings/problems/<type>`,
which had no page. Each type has an anchor there, and a test holds the two together.
- `composer test-coverage` reports coverage without a fixed `--min` floor; coverage ratchets
instead (see CONTRIBUTING).
- With the REST API on, an `authorization.driver` that cannot be built fails closed (every actor
denied, API requests answer `401 actor-required`, one warning logged) instead of raising
`InvalidConfiguration` on every call. Without the API it still raises.
- The table shape is fixed, with `tenancy.mode` as the one switch: every table is keyed by a ULID,
each values row has a unique `uid` (the history's `setting_ref`) and no `slug`, `settable_id` is
`string(36)`, and titles, labels and descriptions are JSON maps of locale to text. The migration
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Contributions are welcome via pull requests.
| Command | What it checks |
|---|---|
| `composer test` | the Pest suite (Arch, Unit, Feature) |
| `composer test-coverage` | the suite with line coverage, failing below 90 % |
| `composer test-coverage` | the suite with a line coverage report. There is no fixed floor: coverage ratchets, so a pull request may not lower the total it reports, and a number set before it was measured would only be a guess CI enforces |
| `composer mutate` | Pest mutation testing of the whole package, failing below a 70 % score (slow; CI runs it weekly, not on pull requests). For your change only: `vendor/bin/pest --mutate --path=src/Changed.php,src/Other.php --exclude-group=mutation-excluded --min=70` |
| `composer lint` | Pint (shared laranail config), PHPStan at level max, Rector dry run; never changes files |
| `composer composer-audit` | known-vulnerable dependencies |
Expand Down
23 changes: 14 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,12 @@

`laranail/settings` is not published to Packagist, so there is no registry-version badge to show: see [Install](#install).

> Key-value settings for any Laravel owner (the application, a user, a tenant, a product), stored in layered stores that work before the database exists.
> Key-value settings for any Laravel owner (the application, a user, a tenant, a product), stored in layered stores that work even before the database exists, and after it does.

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, 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).
> **Pre-1.0.** 0.1.0 is the first tagged release. Before 1.0 a minor release may change the API;
> [Upgrading](docs/upgrading.md) and the [CHANGELOG](CHANGELOG.md) say what changed.

## Install

Expand All @@ -28,9 +27,10 @@ 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, `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.
table per database store, `settings_audit`, `settings_history`, `settings_change_requests`,
`settings_definitions` and `settings_stores`), 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.

```bash
php artisan laranail::settings.install
Expand Down Expand Up @@ -74,7 +74,9 @@ $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).
The JSON REST API is off until `http.enabled` is true; the [REST API quick start](docs/recipes/rest-api-quick-start.md)
gets a first request through. When something does not resolve as expected, run
`php artisan laranail::settings.doctor` and see [Troubleshooting](docs/troubleshooting.md).

[Getting started](docs/getting-started.md) walks through stores, owners and definitions; the
[Documentation](#documentation) index lists every page.
Expand All @@ -89,6 +91,8 @@ The hosted docs live at <https://opensource.simtabi.com/documentation/laranail/s
- [Getting started](docs/getting-started.md) — stores, owners and definitions in a first application.
- [Configuration](docs/configuration.md) — every key in `config/laranail/settings.php`.
- [Architecture](docs/architecture.md) — stores, layers, owners, categories and why they are shaped this way.
- [Troubleshooting](docs/troubleshooting.md) — the common errors, what causes them, and `doctor` and `show`.
- [Upgrading](docs/upgrading.md) — where changes are recorded, and the steps after an upgrade.
- [Release](docs/release.md) — versioning, tags and how a release is cut.

### Reference
Expand All @@ -99,7 +103,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, history, export, import, diff, reencrypt, rescope and the prune commands.
- [Commands](docs/tools/commands.md) — install, make-store, promote, doctor, show, sync-definitions, warm, clear-cache, history, export, import, diff, reencrypt, rescope 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 Down Expand Up @@ -131,6 +135,7 @@ The hosted docs live at <https://opensource.simtabi.com/documentation/laranail/s
- [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.
- [REST API quick start](docs/recipes/rest-api-quick-start.md) — enable the API, authenticate and make a first request.
- [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.
- [Build your own admin UI on the REST API](docs/recipes/building-an-admin-ui-on-the-rest-api.md) — forms from definitions, ETag saves, history and activity.
Expand Down
4 changes: 2 additions & 2 deletions benchmarks/ReadBench.php
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,13 @@
use Simtabi\Laranail\Package\Tools\Providers\PackageToolsServiceProvider;

/**
* Phase 3's gate (design §7.5, §11): one request's reads, with and without the settings cache.
* The cache's performance gate: one request's reads, with and without the settings cache.
*
* Every revolution is one request: the scoped services (registry, resolver, the cache's
* in-request memory) are rebuilt, then ten settings of one owner are read through the cascade
* owner → team → global, all in one SQLite-file store. Subjects:
*
* - uncached: cache.enabled off: one query per request.
* - uncached: cache.enabled off: one query per read.
* - cold: caching on, every bag invalidated first: the query plus the cache writes.
* - warm: caching on, bags cached in the `array` store (in-process).
* - warm file: caching on, bags cached in the `file` store (serialised to disk, the nearest
Expand Down
6 changes: 3 additions & 3 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "laranail/settings",
"description": "Key-value settings for any Laravel owner (application, user, tenant, product) with layered stores, categories, and a file-to-database bootstrap path. MySQL, PostgreSQL and SQLite; SQL Server is not supported in 0.x.",
"description": "Key-value settings for any Laravel owner (the application, a user, a tenant, a product), stored in layered stores that work even before the database exists, and after it does.",
"keywords": [
"laravel",
"laranail",
Expand Down Expand Up @@ -53,7 +53,7 @@
"roave/security-advisories": "dev-latest"
},
"suggest": {
"laranail/installer-headless": "Lets a store's database layer be skipped while the application is being installed (design: bootstrap mode).",
"laranail/installer-headless": "Lets a store's database layer be skipped while the application is being installed (bootstrap mode).",
"laravel/sanctum": "Enables the sanctum actor resolver, which makes a token's settings:<ability> abilities a ceiling on what the token may do.",
"stancl/tenancy": "Detected automatically (tenancy.discriminator = auto): settings, categories, audit rows and in-memory reads are kept per tenant.",
"spatie/laravel-multitenancy": "Detected automatically (tenancy.discriminator = auto), like stancl/tenancy."
Expand All @@ -77,7 +77,7 @@
"scripts": {
"setup": "@composer install",
"test": "vendor/bin/pest --colors=always",
"test-coverage": "@test --coverage --min=90",
"test-coverage": "@test --coverage",
"test-dirty": "@test --dirty --compact",
"mutate": "vendor/bin/pest --mutate --everything --exclude-group=mutation-excluded --min=70",
"bench": [
Expand Down
11 changes: 10 additions & 1 deletion config/settings.php
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@
| locked setting.
| approvals: key globs (`mail.*`) whose writes become change requests.
| bootstrap: skip the database layer while the application installs.
| promote: `manual` (run laranail::settings.promote) or `auto` (copy
| the runtime file into the database once it is ready).
| table: the values table name (default: the store name).
| mode: `polymorphic` or `dedicated` (one owner alias, with a
| foreign key to `owner.table`; read when migrating).
Expand All @@ -56,6 +58,7 @@
'locks' => ['overridable' => false],
'approvals' => ['keys' => []],
'bootstrap' => false,
'promote' => 'manual',
'mode' => 'polymorphic',
'soft_deletes' => false,
],
Expand All @@ -68,6 +71,12 @@
*/
'bootstrap' => env('LARANAIL_SETTINGS_BOOTSTRAP', false),

/*
| Overrides every store's `promote` when set: `manual` or `auto`. Null
| leaves each store's own setting.
*/
'promote' => env('LARANAIL_SETTINGS_PROMOTE'),

/*
| Table names. `prefix` is prepended to every table, including each store's
| values table.
Expand Down Expand Up @@ -415,7 +424,7 @@
| routes: switch route groups off.
| idempotency: how long (`ttl`) and where (`cache`) responses to writes
| sent with an Idempotency-Key header are kept.
| page_size: items per page in listings.
| page_size: items per page in listings without `?limit=` (1 to 200).
|
| An optional `owners` key maps owner aliases a URL may name to model
| classes; unset, the morph map is used.
Expand Down
Loading
Loading