docs: add a Role in the framework section to every module README

Each module README now says where the module sits in the dependency
graph, why it is its own module, and lists use cases for application
developers.
This commit is contained in:
2026-10-11 00:58:17 +02:00
parent 87953f68bf
commit 602e0412f3
24 changed files with 240 additions and 0 deletions

View File

@@ -10,6 +10,16 @@ Request-scoped actor, organization, collection and locale values carried through
`towel` replaces the request-global state that WinterCMS reads through facades (the current locale, the acting user) with explicit values on the request context. Middleware stores a value once, and any code further down the call chain that receives the context reads it back without a global lookup. [surf](../surf/README.md) sets the locale from `Accept-Language` (or the signed-in user's preferred locale) and the organization for every request, [phrasebook](../phrasebook/README.md) reads the locale when it translates, and [cabana](../cabana/README.md) sets it while localizing admin schemas.
## Role in the framework
A dependency-free leaf for request-scoped values. `surf` sets them, and `phrasebook`, `cabana` and plugin code read them. It replaces WinterCMS facades for per-request state, so it has to be importable by any module without cycles.
Use cases:
- Read the acting user or organization in a service without passing them through every call.
- Translate in the request's locale from deep inside a plugin.
- Set a locale explicitly in a job or a test.
## Features
- Four independent string values, each with a setter and a getter: actor (`towel.WithActor`, `towel.Actor`), organization (`towel.WithOrganization`, `towel.Organization`), collection (`towel.WithCollection`, `towel.Collection`) and locale (`towel.WithLocale`, `towel.Locale`).