Emoji Laravel Package

Getting Started

This is a subtree split of the Flarum emoji extension. It's shipped as part of the standard flarum/flarum skeleton, so most installs already have it enabled — check the admin Extensions page or composer show flarum/emoji before adding it manually.

Minimal setup if missing:

composer require flarum/emoji
php flarum migrate
php flarum cache:clear

Where to look first:

• vendor/flarum/emoji/src/ — service provider and the Configuring formatter listener (this is where the s9e/TextFormatter Emoji plugin is wired in).
• vendor/flarum/emoji/js/src/ — the composer emoji picker and : shortcode autocomplete.
• vendor/flarum/emoji/composer.json — confirms the flarum/core version constraint you must match.

First use case: type :smile: into a post, preview it, and confirm the picker opens from the editor toolbar. If both work, the extension is wired correctly; from there, all customization happens through the formatter event or JS extend.

Implementation Patterns

Default behavior (no code). Server-side rendering is handled by s9e's Emoji plugin; the frontend supplies the picker button and : autocomplete. For most forums this is the entire integration.

Adding aliases or custom emoji. Hook the shared formatter configuration event rather than editing vendor files:

use Flarum\Formatter\Event\Configuring;
use Illuminate\Events\Dispatcher;

return [
    function (Dispatcher $events) {
        $events->listen(Configuring::class, function (Configuring $event) {
            $event->configurator->Emoji->aliases['shrug'] = '🤷';
            $event->configurator->Emoji->aliases['flarum'] = '🅵';
        });
    },
];

Switching to plain Unicode output. If you'd rather store/render native emoji than <img> tags (better for copy-paste, RSS, text exports):

$event->configurator->Emoji->useEmojiImages = false;

Frontend extension. Import and wrap the exported picker to add a category or reorder tabs:

import { extend } from 'flarum/common/extend';
import EmojiPicker from 'flarum/emoji/components/EmojiPicker';

Programmatic content. Posts created via the API store raw :shortcode: text; parsing happens at render time, so you don't need to convert shortcodes before submitting.

Ordering with other inline parsers. Register your formatter listeners early and check interaction with flarum/mentions and flarum/markdown when you introduce custom :-prefixed syntax.

Testing. Formatter output is deterministic — unit-test by instantiating Flarum\Formatter\Formatter and asserting the parsed XML/HTML rather than doing HTTP round-trips.

Gotchas and Tips

• Do not patch this repo or open PRs here. It's read-only; source lives in flarum/framework under extensions/emoji. Any edit under vendor/ is destroyed on composer update.
• Clear the formatter cache. Server-side parser config is cached; alias or plugin changes won't appear until php flarum cache:clear. JS changes also require php flarum assets:publish.
• Disabling is destructive-ish. Existing posts keep their :shortcode: text but stop rendering once the extension is removed — plan migrations before disabling.
• Titles and other fields use a different formatter. Don't assume post-body emoji behavior applies to discussion titles or user bios in Flarum 1.x.
• Custom aliases + image mode is inconsistent. An alias mapped to Unicode will render as raw text if the picker/renderer is in image mode; prefer Unicode mode or extend the sprite/assets for truly custom emoji.
• Colon syntax collisions. Other :-based plugins (custom BBCode, timestamps) can steal input; verify plugin order in the formatter configurator.
• Keep majors aligned. flarum/emoji releases track flarum/core; a major mismatch breaks the service provider and formatter bindings.
• The picker assumes the default TextEditor. If you replace the composer editor, you must re-implement the toolbar button and autocomplete yourself.
• Debugging. Inspect the stored post XML for <EMOJI>/<e> tags, check storage/formatter cache freshness, and clear it before assuming a config change failed.
• Extension points are narrow by design: Flarum\Formatter\Event\Configuring server-side and JS extend on exported components. There is no admin settings page — behavior is code-driven.