Tags Laravel Package

Getting Started

This is a Flarum extension, not a Laravel package. Treat it as a domain module that exposes tag CRUD and discussion-tag relationships through Flarum’s JSON:API. In a Laravel app, integrate over HTTP/API tokens; do not import its models into Laravel.

Minimal path:

1. Run it inside a Flarum installation, not a Laravel skeleton:
   • composer require flarum/tags in the Flarum root, or enable the bundled extension.
   • php flarum migrate
   • php flarum cache:clear
2. Create a tag in Admin → Tags, then grant tag-scoped permissions for starting discussions and adding tags.
3. Smoke-test the API:
   • GET /api/tags
   • POST /api/tags with data.type = "tags" and attributes such as name, slug, description, color, icon
   • PATCH /api/discussions/{id} with a relationships.tags payload
4. First real use case: create a “laravel” tag, attach it to a discussion, then list discussions filtered by that tag.

Look here first:

• extend.php for routes, resources, policies, and model extensions.
• src/Tag.php for the tag model and relationships.
• src/Api/Resource/TagResource.php for exact API attributes and relationships.
• src/Access/TagPolicy.php for permission behavior.
• migrations/ for the tags table and discussion-tag pivot.
• js/src/forum and js/src/admin for Mithril UI integration.

Read the resource class before writing payloads; field names and relationship shapes are version-sensitive.

Implementation Patterns

API-first CRUD. Use Flarum’s JSON:API rather than direct database access. Tag IDs are strings in payloads:

{
  "data": {
    "type": "tags",
    "id": "5"
  }
}

Create tags with POST /api/tags; update with PATCH /api/tags/{id}; delete with DELETE /api/tags/{id}. For Laravel integrations, keep a local mapping table such as flarum_tag_id and upsert by slug.

Attach tags through relationships. Add tags when creating a discussion by including relationships.tags, or replace the tag set with a discussion PATCH:

{
  "data": {
    "type": "discussions",
    "id": "123",
    "relationships": {
      "tags": {
        "data": [
          { "type": "tags", "id": "5" },
          { "type": "tags", "id": "8" }
        ]
      }
    }
  }
}

Relationship updates generally replace the set, so always send the full desired tag list.

Filter discussions by tag. Use the tag filter exposed by the extension, for example GET /api/discussions?filter[tag]=laravel&include=tags. Check the installed version’s filter/gambit implementation for multi-tag syntax; do not assume comma or + semantics across versions.

Server-side extension. For custom behavior, listen to discussion lifecycle events such as Flarum\Discussion\Event\Saving or Created, then sync tags through the relationship added by the extension. Prefer the extension’s relationships and commands over raw pivot inserts so events, validation, and permissions remain intact.

Permissions are tag-scoped. A user may start discussions in one tag but only add tags in another. Use TagPolicy and tag-scoped abilities; do not recreate authorization in Laravel. When calling the API, authenticate as a user who actually has the relevant tag permissions.

Laravel integration pattern. Use Laravel’s HTTP client with a Flarum API token, queue synchronization jobs, and make operations idempotent by slug. For inbound sync, use Flarum webhooks if available, or poll/list with include=tags,tags.parent. Avoid sharing the Flarum database directly unless you accept tight coupling.

Frontend extension. Flarum’s frontend is Mithril, not Vue/React. Extend tag pages, tag heroes, and composer tag selection by importing from flarum/tags and overriding components through Flarum’s extend system. Rebuild assets with the Flarum frontend toolchain after changes.

Custom fields. Add fields with Extend\ApiResource(TagResource::class)->fields(...), a migration, and matching frontend serialization. Keep custom fields optional so existing API consumers do not break.

Gotchas and Tips

• This repository is a read-only subtree split. Do not patch vendor/flarum/tags; changes will be overwritten. Fork the extension or work in the Flarum monorepo.
• It is not a Laravel package. There is no Laravel service provider, and its Eloquent models are only safe inside the Flarum app.
• Permissions are the most common source of 403s. Verify the API token’s user, the tag’s visibility, and per-tag “start discussion” and “add to discussion” permissions.
• Tag slugs appear in URLs and filters. Renaming a slug can break links and stored filters; prefer stable slugs, and update external mappings deliberately.
• Relationship PATCH replaces tag sets. Sending only a new tag can unintentionally remove existing tags.
• JSON:API IDs are strings. Use "5", not 5, and always include "type": "tags".
• Do not insert into discussion_tag directly. Use the relationship/API path so validation, events, and permission checks run.
• After migrations or extension changes, run php flarum migrate and php flarum cache:clear. After frontend changes, rebuild and publish assets.
• If tag pages or filters behave unexpectedly, inspect TagResource, the discussion list controller, and the tag gambit for the installed version.
• Use include=tags,tags.parent when rendering tag hierarchies to avoid N+1 API calls.
• Debug with php flarum info, storage/logs/flarum.log, and the browser network tab. Many API failures are validation or permission errors disguised as generic client errors.
• Pin the extension version and test upgrades. As a subtree split, its version tracks Flarum core and internal classes are not a stable public contract.
• Prefer public extension points: API resources/fields, policies, event listeners, and frontend component overrides. Avoid depending on private handler internals.