README

Who is due on watch, where and when: the rotation a post or a team runs, the duties it generates, the swaps and absences that change them, and the on-duty presence read back from the area. A uhifadhi module bundle.

Status: in build. The domain was ruled on 20 September 2026 and this repository is being built against that ruling. See What is built for where it has got to.

Contents

• Charter
• What this module owns — and what it does not
• What is built
• Installation
• Configuration
• Development
• License

Charter

Planned work, not performed work. A roster says who was meant to be somewhere; a patrol says what was done. This module owns the plan, and the one place the two touch is a person on a watch who is out on a patrol — printed with the patrols module's own id and never copied.

Presence is derived, never typed. There is no on-duty field on any form in this module, for any role, including an administrator. Who is actually at a post is read from the area's check-ins and the pings that followed them.

What this module owns — and what it does not

Keeping the three apart is what lets a ranger cover another station for a fortnight without the org chart quietly rewriting itself.

What is built

Still to come: the swap flow on the Week tab (the picker, the cost bar and the offer states, being graduated from the archive), the Live tab's plate, the cycle editor, the widget surface and its presets, the overview contributions, the WatchProviderInterface implementation the area's /me/roster answers the handset through, and the presence reads behind all of them.

The bundle maps its own entity directory and serves its own assets, so an installation writes no doctrine block and no asset path for it.

Installation

composer require uhifadhi/roster-module
php bin/console doctrine:migrations:migrate
php bin/console doctrine:migrations:diff     # must say "No changes detected"
php bin/console registry:sync
php bin/console asset-map:compile
php bin/console cache:clear

The Flex recipe (uhifadhi/roster-module/0.1 in uhifadhilabs/recipes) adds Uhifadhi\Roster\UhifadhiRosterBundle to config/bundles.php, mounts config/routes/roster.yaml and writes config/packages/roster.yaml with the vocabulary below. Entity mapping, the migrations path and the module's icon set are prepended by the bundle itself, so there is nothing else to wire.

The two lines a recipe cannot merge

assets/controllers.json is the INSTALLATION's file and Flex merges into it, but an installation that was built before this module shipped its controllers will not have them — and a Stimulus controller that is not enabled there is markup that looks perfect and does nothing. Check for this block and add it if it is missing:

// assets/controllers.json
"@uhifadhi/roster-module": {
    "rotation": { "enabled": true, "fetch": "eager" },   // the cycle editor
    "now-line":  { "enabled": true, "fetch": "eager" }   // the day board's line at "now"
}

The widget library also imports uhifadhi/widgets, which the CORE's own recipe puts in importmap.php; an installation running the shell already has it.

docs/upgrading.md says which release added which controller, and how to check the compiled map rather than trusting the eye.

Then switch it on per area — a module is installed but parked, and every page answers 404 in an area that has not taken it — and grant roster.manage to whoever changes how the area runs its roster. Reading needs nothing.

A heavy console run goes with --no-debug. A warm-up that walks the registry collects every query of every request while the debug kernel is on, and on a small box that is how cache:warmup meets the memory limit.

Configuration

# config/packages/roster.yaml
roster:
    module_category: operations   # catalogue category for the module tile
    dev_tools: false              # dev-only tooling; when@dev / when@test

    # The named windows a watch can be stood in. A station declares which of
    # them it runs; a window may cross midnight, and a duty belongs to the
    # calendar day its watch BEGINS on.
    shifts:
        - { key: day,    label: Day,         start: '06:00', end: '18:00' }
        - { key: night,  label: Night,       start: '18:00', end: '06:00' }
        - { key: office, label: Office,      start: '07:30', end: '16:30' }
        - { key: radio,  label: Radio night, start: '18:00', end: '06:00' }

    # The values a new area setting, station watch or rotation STARTS at.
    # What any of them actually runs at afterwards is its own stored value,
    # edited on a screen — nothing here is read at display time.
    defaults:
        ping_interval_minutes: 30
        silence_window_minutes: 120
        offline_after_minutes: 1440
        catchment_metres: 1500
        horizon_days: 42

Every key has a default and the tree is closed, so an unknown key fails loudly rather than being ignored.

Development

composer install
composer check      # cs:check -> phpstan (max) -> phpunit

• PHP 8.4+, PHPStan level max over src, tests and migrations, php-cs-fixer @Symfony + @Symfony:risky.
• Tests first, always.
• The integration suite boots a real installation (tests/Integration/TestKernel.php) against a real PostGIS database at postgresql://app:app@127.0.0.1:5434/roster_bundle_test. Never SQLite.

License

AGPL-3.0-or-later — see LICENSE: the same license as the uhifadhi core this module plugs into. Use, modify and self-host freely; if you offer a modified version to users over a network, they are entitled to the source of what they're running.