Default User Preferences Laravel Package

Getting Started

This is a Flarum extension, not a Laravel package — it uses Illuminate's event dispatcher and Eloquent, but registers itself through Flarum's extend.php rather than a ServiceProvider. Treat it as a reference implementation for "seed user preferences at registration" as much as a feature.

Minimal steps:

composer require fof/default-user-preferences
php flarum cache:clear

Then enable it in Admin → Extensions and open its settings modal. The extension exposes toggles that decide which notification-email preferences (reply, mention) are written into a new user's preferences JSON blob.

Where to look first:

1. extend.php — the whole wiring of the extension is here (Extend\Settings, event listeners, any migrations).
2. src/Listeners/ — the listener that stamps defaults onto the user model.
3. migrations/ — check whether it touches the users table or only settings.
4. js/src/admin/ — the admin settings component; the setting keys here are what you'll read in your own code.

First use case: enable the extension, flip both defaults on, register a throwaway account through the normal signup form, then inspect the row:

SELECT username, preferences FROM users ORDER BY id DESC LIMIT 1;

You should see the notification-email keys set to true in the JSON. That single query tells you whether the listener ran and which exact preference keys the package uses — copy those keys if you plan to extend it.

Implementation Patterns

Registration-time defaults (the core path). The listener hooks Flarum's user Saving event and, for records that don't exist yet (!$user->exists), merges the configured defaults into $user->preferences. Any flow that dispatches that event — the JSON:API /api/users endpoint, the signup form, most auth extensions — gets the defaults for free.

Admin-configured vs. hardcoded defaults. For a single forum, use the admin toggles. For multi-tenant or environment-specific deployments, set the values directly in the settings table (or via a seeder) so you can version-control policy instead of clicking checkboxes:

// in a migration or bootstrap script
$this->settings->set('fof-default-user-preferences.reply', true);
$this->settings->set('fof-default-user-preferences.mention', true);

Confirm the exact setting keys against the admin component before relying on them.

Backfilling existing users. The extension only affects new registrations. If you're turning it on for an established forum, write a one-off migration that merges the same keys into existing rows without clobbering choices users already made:

foreach (User::query()->cursor() as $user) {
    $prefs = $user->preferences;
    $prefs += ['notification_email_reply' => true, 'notification_email_mention' => true];
    $user->preferences = $prefs; // note: array union preserves existing keys
    $user->save();
}

The += union is deliberate — array_merge would overwrite explicit false values users set themselves.

Extending to other preferences. The pattern generalizes cleanly: add your own Saving listener at a similar priority and stamp additional keys (notification_email_newPost, digest flags, etc.) using the same guard. If you need both the package's keys and yours, register your listener after theirs so your merge wins on conflicts.

SSO / OAuth registration. Social-login extensions create users through the same model events, so defaults apply. Verify with your provider's flow specifically — some create the user, then immediately update it, and a listener that fires on every save (rather than only on create) will re-apply defaults on that second save and undo a user's first preference change.

Testing. In a Pest/PHPUnit test for your own extension, assert the merge rather than the whole JSON blob:

$user = User::factory()->create();
$this->assertTrue($user->preferences['notification_email_reply'] ?? false);

If you're building on top of this package, freeze its behavior in a test so a future release changing the listener guard doesn't silently alter your forum's notification policy.

Gotchas and Tips

• New users only. This is the most common surprise. Nothing backfills existing accounts; plan a migration and communicate the change, because users who deliberately muted email will suddenly... not, if you're careless with merge semantics.
• Direct DB inserts bypass everything. Seeders, imports, and raw INSERTs never dispatch Saving, so imported users get no defaults. Run the backfill migration after any bulk import.
• Guard on existence, not on "is new". If you fork or extend the listener, check $user->exists (or wasRecentlyCreated) before writing. A listener that unconditionally merges defaults will silently reset preferences every time a user edits their profile.
• Cache clearing is mandatory after composer require or toggling settings; Flarum caches the settings and extension registry aggressively. When toggles "don't work," run php flarum cache:clear before debugging code.
• Preferences live in a JSON column. MySQL JSON semantics mean you can't query individual keys cheaply across a large user table without generated columns or JSON_EXTRACT. If you need reporting on notification opt-in rates, add an indexed column rather than scanning JSON.
• Version constraints matter more than stars. With a tiny dependent count and a single maintainer, pin the version in composer.json and check the flarum/core constraint in the package's composer.json against your Flarum minor version before upgrading core. A Flarum major bump is the realistic breakage vector here.
• Debugging the listener. If a test user has no preferences, confirm the extension is enabled (php flarum info lists enabled extensions), then check that the event actually fired — a temporary Log::info() inside the listener, or Event::listen in extend.php with a higher priority, will tell you whether the problem is registration or merging.
• Extension point worth knowing: the listener priority. Registering your own Flarum\User\Event\Saving listener at a later priority lets you override the package's defaults for specific groups or registration sources without forking it.