javaabu/settings v2.0 (next-gen)

.gitattributes

@@ -1,11 +1,20 @@
 # Path-based git attributes
 # https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html
 
-# Ignore all test and documentation with "export-ignore".
+# Keep development files out of the Composer package. docs, llms.txt and
+# resources/boost ship with it, for AI assistants and Laravel Boost.
 /.gitattributes     export-ignore
 /.gitignore         export-ignore
-/.travis.yml        export-ignore
+/.github            export-ignore
+/.editorconfig      export-ignore
 /phpunit.xml.dist   export-ignore
-/.scrutinizer.yml   export-ignore
+/pint.json          export-ignore
 /tests              export-ignore
-/.editorconfig      export-ignore
+/AGENTS.md          export-ignore
+/CLAUDE.md          export-ignore
+/node_modules       export-ignore
+/package.json       export-ignore
+/pnpm-lock.yaml     export-ignore
+/tsconfig.json      export-ignore
+/vitest.config.ts   export-ignore
+/testbench.yaml    export-ignore

.github/workflows/tests.yml

@@ -0,0 +1,150 @@
+name: tests
+
+on:
+    pull_request:
+    push:
+        branches:
+            - main
+            - next-gen
+
+# The unreleased javaabu/* dependencies come from VCS repositories; the job's own
+# token keeps Composer within GitHub's API limits
+env:
+    COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ github.token }}"}}'
+
+jobs:
+    pint:
+        runs-on: ubuntu-latest
+
+        name: Pint
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.4
+                    coverage: none
+
+            -   name: Install dependencies
+                run: composer update --prefer-dist --no-interaction --no-progress
+
+            -   name: Check code style
+                run: vendor/bin/pint --test
+
+    js:
+        runs-on: ubuntu-latest
+
+        name: React pages (typecheck, tests)
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            # The pages import stencil's React renderer from vendor/javaabu/stencil
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.4
+                    coverage: none
+
+            -   name: Install Composer dependencies
+                run: composer update --prefer-dist --no-interaction --no-progress
+
+            -   name: Setup pnpm
+                uses: pnpm/action-setup@v4
+
+            -   name: Setup Node
+                uses: actions/setup-node@v5
+                with:
+                    node-version: 22
+                    package-manager-cache: false
+
+            # The default store is inside a node_modules folder, which breaks the declaration
+            # build of @javaabu/forms (installed from git and built on install)
+            -   name: Install dependencies
+                run: pnpm install --frozen-lockfile --store-dir "$RUNNER_TEMP/pnpm-store"
+
+            -   name: Typecheck
+                run: pnpm typecheck
+
+            -   name: Test
+                run: pnpm test
+
+    without-optional:
+        runs-on: ubuntu-latest
+
+        name: Without optional packages
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.4
+                    extensions: curl, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, iconv
+                    coverage: none
+
+            -   name: Install dependencies without activitylog, Inertia and translatable
+                run: |
+                    composer remove --dev spatie/laravel-activitylog inertiajs/inertia-laravel javaabu/translatable --no-interaction --no-update
+                    composer update --prefer-dist --no-interaction --no-progress
+
+            -   name: Execute tests
+                run: vendor/bin/phpunit
+
+    tests:
+        runs-on: ubuntu-latest
+
+        strategy:
+            fail-fast: false
+            matrix:
+                php: [ 8.4, 8.5 ]
+                laravel: [ 12.*, 13.* ]
+                stability: [ prefer-lowest, prefer-stable ]
+                include:
+                    -   laravel: 12.*
+                        testbench: 10.*
+                    -   laravel: 13.*
+                        testbench: 11.*
+
+        name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.stability }}
+
+        env:
+            COVERAGE: ${{ matrix.php == '8.4' && matrix.laravel == '13.*' && matrix.stability == 'prefer-stable' }}
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v5
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: ${{ matrix.php }}
+                    extensions: curl, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, iconv
+                    coverage: ${{ env.COVERAGE == 'true' && 'pcov' || 'none' }}
+
+            -   name: Install dependencies
+                run: |
+                    composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+                    composer update --${{ matrix.stability }} --prefer-dist --no-interaction --no-progress
+
+            -   name: Execute tests
+                if: env.COVERAGE != 'true'
+                run: vendor/bin/phpunit
+
+            -   name: Execute tests with coverage
+                if: env.COVERAGE == 'true'
+                run: vendor/bin/phpunit --coverage-clover build/coverage.xml
+
+            -   name: Upload coverage to Codecov
+                if: env.COVERAGE == 'true'
+                uses: codecov/codecov-action@v5
+                with:
+                    files: build/coverage.xml
+                    fail_ci_if_error: false
+                    token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -3,5 +3,6 @@ composer.lock
 vendor
 coverage
 .phpunit.result.cache
+.phpunit.cache
 .idea
-clover.xml
+node_modules

AGENTS.md

@@ -0,0 +1,45 @@
+# settings: notes for AI coding agents
+
+`javaabu/settings` keeps app settings: defined with javaabu/stencil fields (`Setting::make()`), grouped into `SettingsPage`s and `Section`s, stored by a `SettingsStore` (database, json, array), cached under a version token that queue workers and Octane check, and edited through `Route::settings()` pages in Blade or Inertia React with a policy and permissions from javaabu/permissions. Apps extend `SettingsPage`, `SettingsController` and `SettingsPolicy`, and other Javaabu packages call the v1 helpers, so treat `Setting`, `Section`, `SettingsPage`, `SettingsRepository`/`Settings`, the helpers in `src/helpers.php`, `SettingsStore`, `SettingsUpdated`, `FakesSettings`, `Route::settings()` and the page props as public contracts.
+
+## Layout
+
+| Path | What |
+| --- | --- |
+| `src/SettingsRepository.php`, `src/Facades/Settings.php`, `src/helpers.php` | Reading, writing, typed getters, versioned cache, fakes; `settings()` and the v1 helpers |
+| `src/SettingsRegistry.php`, `src/Definitions` | Pages and the index of settings; `Setting`, `Section`, `SettingsPage`, `InlinePage` |
+| `src/Stores`, `src/Contracts` | The stores and their manager |
+| `src/Forms/SettingsForm.php` | The stencil form of a page: values, saving, files, encrypted and translatable settings |
+| `src/Routing`, `src/Http`, `src/Policies`, `src/Views` | `Route::settings()`, the controller, the policy, `ViewRenderer` |
+| `src/Support` | Optional javaabu/translatable support (`Translations`, `Translatable\SettingsRecord`) |
+| `src/Events`, `src/Listeners`, `src/Commands`, `src/Testing` | `SettingsUpdated`, the activity log listener, `settings:import-v1`, `FakesSettings` |
+| `config/settings.php`, `config/defaults.php`, `database/migrations` | Options; the v1 defaults sample; the `settings` table |
+| `resources/views` | The Blade page (javaabu/forms components, stencil's Blade driver) |
+| `resources/js` | The Inertia React page (TypeScript), shipped through javaabu/manifest |
+| `lang/en.json`, `lang/dv.json` | Translations; English strings are the keys |
+| `docs`, `llms.txt` | Docusaurus pages for docs.javaabu.com and the index for AI assistants |
+| `resources/boost` | Laravel Boost guideline and skill, shipped in the package |
+| `tests` | Testbench tests; two guards (`web` → `User`, `web_admin` → `Admin`); `QueueWorkerProcessTest` starts a real worker with `vendor/bin/testbench` (`testbench.yaml`); `tests/js` are Vitest tests of the React page |
+
+## Rules
+
+- Follow Javaabu codestyle ([boost-javaabu-guidelines](https://github.com/Javaabu/boost-javaabu-guidelines)): snake_case variables and properties, camelCase methods, early returns, `#[Test]` and `it_…` test names. Pint enforces formatting.
+- Every write must go through `SettingsRepository::set()`/`forget()`/`flush()` so the cache version changes; never cache values outside the versioned keys.
+- Nothing may assume the `web` guard or `App\Models\User`. Type-hint users as `Model`; test on both guards.
+- Inertia, javaabu/translatable and spatie/laravel-activitylog are optional: feature-detect them (translatable only through `Support\Translations`), keep them in `suggest`, and test both ways. Test classes must load without them (no `use` of their traits).
+- Keep the v1 helpers and `FakesSettings` working; document any break in `docs/upgrading.md`.
+- Encrypted values must never reach the browser or the activity log.
+- Every user-facing string goes through `__()` with an English key, and gets a line in `lang/en.json` and `lang/dv.json` (`TranslationsTest` checks). Use Thaana in tests of user-facing behaviour. List uncertain translations in `docs/advanced-usage/dhivehi-and-rtl.md`. Views use logical CSS only (`ms-`, `pe-`, `start-`), never `left`/`right`.
+- When the Inertia props change, regenerate the JS fixture: `UPDATE_FIXTURES=1 vendor/bin/phpunit --filter InertiaPagesTest`.
+- Every change needs tests, docs (linked from `llms.txt`), the Boost skill if it changes how the package is used, and a line in `CHANGELOG.md`.
+- Work on the `next-gen` branch; don't commit to `main`.
+
+## Commands
+
+```bash
+composer install
+composer lint       # vendor/bin/pint --test
+composer format     # vendor/bin/pint
+composer test       # vendor/bin/phpunit
+pnpm install && pnpm check   # typecheck and Vitest for resources/js (needs vendor/ for stencil)
+```