Nicknames Laravel Package

Product Decisions This Supports

• Identity model: display name vs. login identifier. Decouples the human-facing name from the credential/mention handle. This is a real product decision — it determines how users present themselves, how mentions resolve, and how moderation traces a person across renames.
• Onboarding and SSO fit. If you authenticate via Google, LDAP, SAML, or a legacy forum migration, usernames arrive as jsmith or john.smith.4821. Nicknames let you ship a usable, presentable identity on day one instead of forcing a rename flow or a custom profile field.
• Build vs. buy: buy (adopt). This is the classic "don't build it" case — a few hundred lines of column, validator, permission, and serializer work that you would otherwise re-implement and maintain forever. Adopt the first-party extension; spend the engineering budget on your differentiated community features.
• Roadmap input for community/social surface. Nickname availability is a prerequisite for: real-name-optional policies, per-cohort naming conventions (gamer tags, professional names, anonymized handles), and migration from forums where display names were already separate.
• Moderation and trust-and-safety scope. Once users can rename independently of their login handle, you inherit questions: how often, whether unique, whether reserved words are blocked, whether old names are retained for abuse tracking. This package sets defaults; your policy layer sits on top — decide that deliberately rather than inheriting whatever the extension ships.
• Not a differentiator. Treat it as table stakes plumbing. It should not appear on a roadmap slide as a feature; it should appear as an unblocker for one.

When to Consider This Package

Adopt when:

• You are running Flarum (1.x era) and need a display name distinct from the login username — the extension is part of the Flarum first-party ecosystem, MIT-licensed, and requires no bespoke schema work.
• You have SSO or imported accounts where usernames are machine-generated or mismatched to how people want to be seen.
• You need permission-gated renaming (who can set a nickname, how often) rather than a free-for-all profile field.
• You want a small, auditable surface area — one composer dependency, low blast radius, easy to remove.

Look elsewhere or build custom when:

• You are not on Flarum. Despite the PHP/Laravel-adjacent stack (Flarum builds on Illuminate components), this extension is coupled to Flarum's extension API and will not port to a standalone Laravel app.
• You need alias history, per-space names, or moderation-grade rename auditing. This is a single nickname field, not an identity graph. Plan a companion table.
• You require vendor SLAs or a maintained release cadence you can contract on. Read the signals honestly: this repo is a read-only subtree split of a monorepo, so direct PRs and issue tracking do not live here, and the star count is not a meaningful popularity indicator. The release date (2026-10-14) should be verified against your installed Flarum version before you commit.
• You need uniqueness guarantees, profanity filtering, or cooldowns beyond what ships by default — be prepared to add a small policy extension on top.
• Your governance forbids single-maintainer or monorepo-split dependencies, or your security review requires an independently versioned artifact with its own CVE history.

How to Pitch It (Stakeholders)

To executives (one paragraph): We can give every community member a proper display name — separate from the handle they log in with — for the cost of one dependency and roughly a day of configuration, instead of a custom identity feature we would own and maintain indefinitely. It's MIT-licensed, first-party to the Flarum ecosystem we already run on, and removable without data loss. The business value is onboarding friction and migration readiness: people joining via SSO or from an old forum arrive with usernames like j.smith.4821, and today that is the name they wear in public. It removes a visible rough edge at near-zero cost and does not appear on the roadmap as a project.

To engineering (the honest version): Small, well-scoped extension adding a nickname field with permission-gated editing, layered onto Flarum's existing user model — no fork of core, no custom migration. Constraints to note: this repository is a read-only subtree split, so patches and issues go upstream to the parent monorepo, not here; star count is not a health signal. Budget time for policy decisions the extension won't make for us — uniqueness, rename frequency, reserved names, and whether we retain prior names for abuse investigations. Recommend we pin the version, verify compatibility with our Flarum release, and wrap the rename policy in our own config so we can change it without forking.