[n4ff4h]

javaabu/settings v2.0

This is the next major of settings: you define each setting once, with javaabu/stencil, and it gets typed access, a settings page in Blade or Inertia React, and fresh values in queue workers. It was developed on the fork n4ff4h/settings (branch next-gen) and tracked in n4ff4h#12.

What's in it

• Definitions. Setting::make('per_page')->default(20)->integer()->minValue(1) puts the default, the stencil field and the validation in one place. Settings are grouped into SettingsPage classes (or inline pages) and Sections. Settings::define() covers settings that have no page.
• Storage. v2 has its own database (default), json and array stores, plus custom drivers, replacing anlutro/l4-settings. Values are kept as JSON, so their types survive. php artisan settings:import-v1 copies the v1 values across.
• Reading. The settings() helper and the Settings facade cast values from the field (booleans, integers, floats, arrays, enums). Typed getters (settings()->integer('per_page')) throw on the wrong type. Settings can be encrypted, and file settings have URLs.
• Fresh everywhere. Values are cached under a version token. Queue workers (before each job) and Octane (before each request) reload them when another process changes them. This is tested with a real queue:work process, both with the reload on and off.
• Pages. Route::settings([...]) gives each page a form, validation, saving, uploads and live fields. You choose the prefix, name, guard and middleware.
  • Blade: built with javaabu/forms.
  • Inertia React: settings::Settings/Edit with <StencilForm>, shipped through javaabu/manifest; the components are exported as @javaabu/settings.
  • JSON for API clients. The controller can be overridden.
• RBAC. view_settings, edit_settings and per-page permissions are registered with javaabu/permissions. SettingsPolicy can be overridden. Any guard and user model works.
• Optional packages. Translatable settings come from javaabu/translatable v3 (->translatable(), one input per language). The activity log comes from spatie/laravel-activitylog, and encrypted values are never logged.
• Dhivehi, RTL and docs. Dhivehi translations, RTL pages and Thaana fields. Docusaurus docs, llms.txt, AGENTS.md, and a Laravel Boost guideline and skill.

Breaking changes (full list in docs/upgrading.md)

• Requires PHP 8.4 and Laravel 12 or 13.
• anlutro/l4-settings is gone. Replace anlutro\LaravelSettings\Facades\Setting with Javaabu\Settings\Facades\Settings; writes save immediately, so there's no save(). anlutro's config/settings.php is replaced by v2's file of the same name.
• Values keep their types (v1's database store returned strings).
• SettingsUpdated::$causer is any Eloquent model, and defaults to the authenticated user.
• spatie/laravel-activitylog is now optional.
• Providers\EventServiceProvider is removed.
• Still working from v1: get_setting(), default_setting(), set_file_setting(), reset_file_setting(), remove_prefix(), config/defaults.php, FakesSettings and SettingsUpdated.

Tests and CI

• 114 PHPUnit tests: two guards, Blade, Inertia, JSON, live fields, a real queue worker, and translatable on and off.
• Vitest tests of the React page.
• CI runs PHP 8.4/8.5 × Laravel 12/13 × lowest/stable, plus Pint, the React page checks (typecheck and Vitest) and a job without the optional packages. All green on the fork.

Before or after merging

• Codecov: add CODECOV_TOKEN. On the fork the upload is rejected without it (Foundations: PHP 8.4 / Laravel 12+, CI matrix, coverage and codestyle n4ff4h/settings#1).
• After the merge:
  • Change the branch alias ("dev-next-gen": "2.x-dev") to "dev-main": "2.x-dev".
  • Point the README's test and Codecov badges at Javaabu/settings main.
• Unreleased dependencies: composer.json gets javaabu/forms, manifest, permissions and stencil from VCS repositories on their next-gen/main branches, and translatable from n4ff4h/translatable. Switch to released versions once they're on Packagist.
• Docs: register the package with docs.javaabu.com (Register with Javaabu Docs (docs.javaabu.com) n4ff4h/settings#11).
• Dhivehi: a native speaker should review the strings listed in docs/advanced-usage/dhivehi-and-rtl.md.
• Follow-up (dev-only): Test against javaabu/settings v2 (require-dev still pins ^1.8) forms#20 asks forms to test against settings v2.
• Release: tag v2.0.0 when ready.

🤖 Generated with Claude Code