Drafts Laravel Package

Getting Started

• composer require fof/drafts, enable it under Admin → Extensions, then run php flarum migrate and php flarum cache:clear from the forum root. Flarum is not a full Laravel app (it uses Illuminate database/events/validation under the hood), so use the flarum CLI, not artisan.
• Read these first, in order: extend.php (which controllers, policies, model defaults, and listeners are registered), migrations/ (the authoritative schema — column names like is_draft, plus any scheduled-publish columns), src/ (policies and event listeners), and js/src/forum/ (composer autosave and draft-list UI).
• Check the admin settings for autosave behavior and scheduling before writing code; a lot of "where is this implemented" questions are answered by a setting rather than by PHP.
• First use case: save and resume. Start a discussion as a normal user, leave the composer, come back, find the draft, edit, publish. Smoke-test with a non-admin account to confirm the draft is visible only to its author, and confirm publishing fires the normal DiscussionStarted notifications.
• Sanity-check the database immediately: select id, user_id, is_draft, created_at from discussions order by id desc limit 5; — that tells you what the extension actually persists far faster than reading the JS.

Implementation Patterns

• Drafts are discussions. Everything — tags, recipients, attachments — is stored as a real discussion with a flag. Build against the Discussion model and add where('is_draft', false) to any query that feeds a public surface. Don't invent a parallel Draft model.
• Autosave loop: debounce input in the composer, POST /api/discussions on first save, then PATCH the same id on subsequent saves. Keep the draft id in composer state so a page refresh or a second tab doesn't create duplicates.
• Gate side effects on the flag. Listen for Discussion\Saving / Created / Started and bail early when $discussion->is_draft is true. Notifications, activity entries, webhooks, search indexing, and external syncs should all treat drafts as invisible.

(new Extend\Event())
    ->listen(DiscussionStarted::class, function (DiscussionStarted $event) {
        if ($event->discussion->is_draft) {
            return; // don't broadcast/index/notify for drafts
        }
        // normal publish-time work
    }),

• Policy work: reuse discussion.start / discussion.edit where possible. If you need a "may create drafts" ability, add it via a policy extender and expose the same boolean as a forum attribute so the frontend can hide the save button consistently.
• Scheduled publishing (if enabled in your version): it depends on Flarum's scheduler and queue. Confirm the cron entry running php flarum schedule:run and a queue:work worker; otherwise scheduled drafts sit unpublished indefinitely and look like a bug.
• Custom fields: add your own columns by migration, populate them in the save listener, and only enforce required-ness at publish time. Optional-for-drafts / required-to-publish is the pattern users expect.
• Frontend points: extend DiscussionComposer for a save-draft button, DiscussionListItem for a badge, and a route or filter for "my drafts" rather than making users scroll the main list.

Gotchas and Tips

• Draft leakage is the main failure mode. Search, sitemaps, RSS, digests, and any custom "latest discussions" widget will happily show drafts unless filtered. Index the draft column if the forum is large.
• Mentions and notifications fire on save. @mentions inside an unpublished draft can notify people before it's published. Test by saving a draft containing a mention and inspecting the recipient's notification list.
• Publish-time validation surprises. A draft saved without required tags or fields (or with a tag the user later lost permission for) will fail on publish. Surface the validation error clearly in the composer instead of silently leaving it as a draft.
• Slug and timestamps. Depending on version, slug/start_time are set at save or at publish. Check the migration before using them for sorting or permalinks — a draft with a real slug can be reached by URL if your policy check is missing.
• Orphan cleanup. Deleting a user, a tag, or the extension itself leaves drafts behind, along with any uploaded files. Write a prune query or scheduled job; don't assume the package does it.
• Small package, few dependents. Pin the constraint in composer.json, read the migration diff before php flarum migrate, and re-run save → resume → publish → (schedule) after every upgrade.
• Debugging: php flarum cache:clear after any settings change, check storage/logs/flarum-*.log, and replay the failing autosave with curl against /api/discussions — that separates composer/frontend bugs from policy 403s quickly.
• Prefer extension over fork. Model event listeners and policy abilities cover most customization; only patch the package when you need to change autosave cadence or the scheduling interval.