### Tag API Response Example

Source: https://context7.com/flarum/tags/llms.txt

Example JSON response structure for tag-related API requests, showing tag attributes and relationships.

```json
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "name": "General",
        "slug": "general",
        "description": "General discussions",
        "color": "#FF5733",
        "icon": "fas fa-comments",
        "isHidden": false,
        "isPrimary": true,
        "position": 0,
        "discussionCount": 42,
        "lastPostedAt": "2024-01-15T10:30:00Z",
        "canStartDiscussion": true,
        "canAddToDiscussion": true
      },
      "relationships": {
        "parent": { "data": null },
        "children": { "data": [{ "type": "tags", "id": "3" }] }
      }
    }
  ]
}
```

```json
{
  "data": {
    "type": "tags",
    "id": "1",
    "attributes": {
      "name": "General",
      "slug": "general",
      "description": "General discussions",
      "color": "#FF5733",
      "icon": "fas fa-comments",
      "isHidden": false,
      "isPrimary": true,
      "isRestricted": false,
      "backgroundUrl": null,
      "backgroundMode": null,
      "position": 0,
      "defaultSort": null,
      "isChild": false,
      "discussionCount": 42,
      "lastPostedAt": "2024-01-15T10:30:00Z",
      "canStartDiscussion": true,
      "canAddToDiscussion": true
    }
  }
}
```

```json
{
  "data": {
    "type": "tags",
    "id": "15",
    "attributes": {
      "name": "Dev Blog",
      "slug": "dev-blog",
      "description": "Follow Flarum development!",
      "color": "#123456",
      "icon": "fas fa-code",
      "isHidden": false,
      "isPrimary": true,
      "position": 5,
      "discussionCount": 0
    }
  }
}
```

--------------------------------

### Build and Save Tags

Source: https://context7.com/flarum/tags/llms.txt

Demonstrates creating new tags, including primary and child tags, and saving them. Also shows how to query tags visible to a user and manage tag relationships.

```php
<?php

use Flarum\Tags\Tag;
use Flarum\User\User;

// Build a new tag
$tag = Tag::build(
    name: 'Announcements',
    slug: 'announcements',
    description: 'Official forum announcements',
    color: '#FF9800',
    icon: 'fas fa-bullhorn',
    isHidden: false
);
$tag->is_primary = true;
$tag->save();

// Create child tag with parent
$childTag = Tag::build(
    name: 'Release Notes',
    slug: 'release-notes',
    description: 'Software release announcements',
    color: '#4CAF50',
    icon: 'fas fa-rocket',
    isHidden: false
);
$childTag->parent_id = $tag->id;
$childTag->is_primary = true;
$childTag->save();

// Query tags visible to a user
$user = User::find(1);
$visibleTags = Tag::query()
    ->whereVisibleTo($user)
    ->withStateFor($user)
    ->get();

// Query tags with specific permission
$tagsWithPermission = Tag::query()
    ->whereHasPermission($user, 'startDiscussion')
    ->get();

// Get tag relationships
$parent = $tag->parent;           // BelongsTo relationship
$children = $tag->children;       // HasMany relationship
$discussions = $tag->discussions; // BelongsToMany relationship

// Refresh last posted discussion metadata
$tag->refreshLastPostedDiscussion();
$tag->save();

// Get user-specific state (e.g., subscription status)
$state = $tag->stateFor($user);
$state->is_hidden = true;
$state->save();

```

--------------------------------

### Create Tag

Source: https://context7.com/flarum/tags/llms.txt

Creates a new tag. Requires administrator privileges or `createTag` permission.

```APIDOC
## POST /api/tags

### Description
Creates a new tag. Requires admin privileges or `createTag` permission. Can optionally create a child tag by specifying a parent relationship.

### Method
POST

### Endpoint
/api/tags

### Request Body
- **data** (object) - Required - The tag resource object.
  - **type** (string) - Required - Must be "tags".
  - **attributes** (object) - Required - The tag's attributes.
    - **name** (string) - Required - The name of the tag.
    - **slug** (string) - Required - The URL-friendly slug for the tag.
    - **description** (string) - Optional - A description of the tag.
    - **color** (string) - Optional - The color associated with the tag (hex format).
    - **icon** (string) - Optional - The icon class for the tag.
    - **isHidden** (boolean) - Optional - Whether the tag is hidden (defaults to false).
    - **isPrimary** (boolean) - Optional - Whether the tag is a primary tag (defaults to false).
  - **relationships** (object) - Optional - Relationships to other resources.
    - **parent** (object) - Optional - Relationship to the parent tag.
      - **data** (object) - Required if `parent` is present.
        - **type** (string) - Must be "tags".
        - **id** (string) - The ID of the parent tag.

### Request Example
```bash
# Create a new primary tag
curl -X POST "https://forum.example.com/api/tags"
  -H "Authorization: Token YOUR_ADMIN_TOKEN"
  -H "Content-Type: application/json"
  -d '{ "data": { "type": "tags", "attributes": { "name": "Dev Blog", "slug": "dev-blog", "description": "Follow Flarum development!", "color": "#123456", "icon": "fas fa-code", "isHidden": false, "isPrimary": true } } }'

# Create a child tag with a parent relationship
curl -X POST "https://forum.example.com/api/tags"
  -H "Authorization: Token YOUR_ADMIN_TOKEN"
  -H "Content-Type: application/json"
  -d '{ "data": { "type": "tags", "attributes": { "name": "Frontend", "slug": "frontend", "description": "Frontend development discussions", "color": "#4CAF50", "isPrimary": true }, "relationships": { "parent": { "data": { "type": "tags", "id": "1" } } } } }'
```

### Response
#### Success Response (201 Created)
- **data** (object) - The newly created tag object.
  - **type** (string) - The resource type, always "tags".
  - **id** (string) - The unique identifier for the tag.
  - **attributes** (object) - The tag's attributes.
    - **name** (string) - The name of the tag.
    - **slug** (string) - The URL-friendly slug for the tag.
    - **description** (string) - A description of the tag.
    - **color** (string) - The color associated with the tag.
    - **icon** (string) - The icon class for the tag.
    - **isHidden** (boolean) - Whether the tag is hidden.
    - **isPrimary** (boolean) - Whether the tag is a primary tag.
    - **position** (integer) - The display order of the tag.
    - **discussionCount** (integer) - The number of discussions associated with this tag.

#### Response Example
```json
{
  "data": {
    "type": "tags",
    "id": "15",
    "attributes": {
      "name": "Dev Blog",
      "slug": "dev-blog",
      "description": "Follow Flarum development!",
      "color": "#123456",
      "icon": "fas fa-code",
      "isHidden": false,
      "isPrimary": true,
      "position": 5,
      "discussionCount": 0
    }
  }
}
```
```

--------------------------------

### List All Tags with Flarum API

Source: https://context7.com/flarum/tags/llms.txt

Retrieves all tags visible to the authenticated user. Use the 'include' parameter to fetch parent or children relationships.

```bash
# List all tags
curl -X GET "https://forum.example.com/api/tags" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

```bash
# List tags with parent relationships included
curl -X GET "https://forum.example.com/api/tags?include=parent" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

```bash
# List tags with children relationships included
curl -X GET "https://forum.example.com/api/tags?include=children" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

--------------------------------

### Create Discussion with Parent and Child Tags

Source: https://context7.com/flarum/tags/llms.txt

Creates a new discussion and associates it with both parent and child tags. This demonstrates assigning multiple tags to a single discussion.

```bash
# Create discussion with parent and child tags
curl -X POST "https://forum.example.com/api/discussions" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "data": { \
      "type": "discussions", \
      "attributes": { \
        "title": "Frontend Bug Report", \
        "content": "Found an issue with the tag selector component." \
      }, \
      "relationships": { \
        "tags": { \
          "data": [ \
            { "type": "tags", "id": "2" }, \
            { "type": "tags", "id": "3" } \
          ] \
        } \
      } \
    } \
  }'
```

--------------------------------

### List All Tags

Source: https://context7.com/flarum/tags/llms.txt

Retrieves all tags visible to the authenticated user. Supports including parent and children relationships.

```APIDOC
## GET /api/tags

### Description
Retrieves all tags visible to the authenticated user, with optional relationship includes for parent/children tags.

### Method
GET

### Endpoint
/api/tags

### Query Parameters
- **include** (string) - Optional - Comma-separated list of relationships to include (e.g., `parent`, `children`).

### Request Example
```bash
curl -X GET "https://forum.example.com/api/tags?include=parent"
  -H "Authorization: Token YOUR_API_TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - An array of tag objects.
  - **type** (string) - The resource type, always "tags".
  - **id** (string) - The unique identifier for the tag.
  - **attributes** (object) - The tag's attributes.
    - **name** (string) - The name of the tag.
    - **slug** (string) - The URL-friendly slug for the tag.
    - **description** (string) - A description of the tag.
    - **color** (string) - The color associated with the tag (hex format).
    - **icon** (string) - The icon class for the tag (e.g., Font Awesome class).
    - **isHidden** (boolean) - Whether the tag is hidden.
    - **isPrimary** (boolean) - Whether the tag is a primary tag.
    - **position** (integer) - The display order of the tag.
    - **discussionCount** (integer) - The number of discussions associated with this tag.
    - **lastPostedAt** (string) - The timestamp of the last post in discussions with this tag.
    - **canStartDiscussion** (boolean) - Whether the user can start a discussion in this tag.
    - **canAddToDiscussion** (boolean) - Whether the user can add this tag to a discussion.
  - **relationships** (object) - Relationships to other resources.
    - **parent** (object) - Relationship to the parent tag.
    - **children** (object) - Relationship to child tags.

#### Response Example
```json
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "name": "General",
        "slug": "general",
        "description": "General discussions",
        "color": "#FF5733",
        "icon": "fas fa-comments",
        "isHidden": false,
        "isPrimary": true,
        "position": 0,
        "discussionCount": 42,
        "lastPostedAt": "2024-01-15T10:30:00Z",
        "canStartDiscussion": true,
        "canAddToDiscussion": true
      },
      "relationships": {
        "parent": { "data": null },
        "children": { "data": [{ "type": "tags", "id": "3" }] }
      }
    }
  ]
}
```
```

--------------------------------

### Create Tag with Flarum API

Source: https://context7.com/flarum/tags/llms.txt

Creates a new tag. Requires admin privileges or the 'createTag' permission. Can specify parent relationships for child tags.

```bash
curl -X POST "https://forum.example.com/api/tags" \
  -H "Authorization: Token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "type": "tags", "attributes": { "name": "Dev Blog", "slug": "dev-blog", "description": "Follow Flarum development!", "color": "#123456", "icon": "fas fa-code", "isHidden": false, "isPrimary": true } } }'
```

```bash
# Create child tag with parent relationship
curl -X POST "https://forum.example.com/api/tags" \
  -H "Authorization: Token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "type": "tags", "attributes": { "name": "Frontend", "slug": "frontend", "description": "Frontend development discussions", "color": "#4CAF50", "isPrimary": true }, "relationships": { "parent": { "data": { "type": "tags", "id": "1" } } } } }'
```

--------------------------------

### Load and Access All Tags

Source: https://context7.com/flarum/tags/llms.txt

Loads all tags with their relationships and iterates through them to log various attributes. Accesses tags from the store using app.store.all() or app.store.getById().

```typescript
import app from 'flarum/forum/app';
import Tag from 'flarum/tags/common/models/Tag';

// Load all tags with relationships
app.tagList.load(['parent', 'children']).then((tags: Tag[]) => {
  tags.forEach(tag => {
    console.log('Tag:', tag.name());
    console.log('Slug:', tag.slug());
    console.log('Description:', tag.description());
    console.log('Color:', tag.color());
    console.log('Icon:', tag.icon());
    console.log('Is Primary:', tag.isPrimary());
    console.log('Is Hidden:', tag.isHidden());
    console.log('Is Child:', tag.isChild());
    console.log('Position:', tag.position());
    console.log('Discussion Count:', tag.discussionCount());
    console.log('Last Posted At:', tag.lastPostedAt());
    console.log('Can Start Discussion:', tag.canStartDiscussion());
    console.log('Can Add To Discussion:', tag.canAddToDiscussion());

    // Relationship accessors
    const parent = tag.parent();       // Tag | null
    const children = tag.children();   // Tag[]

    // Computed property for primary parent tags
    if (tag.isPrimaryParent()) {
      console.log('This is a top-level primary tag');
    }
  });
});

// Get tags from store
const allTags = app.store.all<Tag>('tags');
const specificTag = app.store.getById<Tag>('tags', '1');
```

--------------------------------

### Handle Tag Lifecycle Events

Source: https://context7.com/flarum/tags/llms.txt

Listens for tag creation, saving, and deletion events to perform custom logic during tag management. Use these events for validation, default value setting, or cleanup.

```php
<?php

use Flarum\Tags\Event\Creating;
use Flarum\Tags\Event\Saving;
use Flarum\Tags\Event\Deleting;
use Illuminate\Contracts\Events\Dispatcher;

class TagLifecycleListener
{
    public function subscribe(Dispatcher $events): void
    {
        $events->listen(Creating::class, function (Creating $event) {
            $tag = $event->tag;
            $actor = $event->actor;
            $data = $event->data;

            // Validate or modify tag before creation
            if (empty($tag->color)) {
                $tag->color = '#607D8B'; // Default color
            }
        });

        $events->listen(Saving::class, function (Saving $event) {
            $tag = $event->tag;
            // Perform actions on tag update
        });

        $events->listen(Deleting::class, function (Deleting $event) {
            $tag = $event->tag;
            // Clean up related data before deletion
        });
    }
}

```

--------------------------------

### TagRepository Queries

Source: https://context7.com/flarum/tags/llms.txt

Utilizes the TagRepository for efficient tag queries, including user visibility scoping and finding tags by ID or slug. Ensure the TagRepository is resolved via the service container.

```php
<?php

use Flarum\Tags\TagRepository;
use Flarum\User\User;

$repository = resolve(TagRepository::class);
$user = User::find(2);

// Get base query builder
$query = $repository->query();

// Get query scoped to user visibility
$visibleQuery = $repository->queryVisibleTo($user);

// Find tag by ID with visibility check
try {
    $tag = $repository->findOrFail(5, $user);
} catch (\Illuminate\Database\Eloquent\ModelNotFoundException $e) {
    // Tag not found or not visible to user
}

// Get all visible tags for user
$allTags = $repository->all($user);

// Get tag ID by slug
$tagId = $repository->getIdForSlug('announcements', $user);
if ($tagId === null) {
    // Tag not found or not visible
}

```

--------------------------------

### Create Discussion with Primary Tag

Source: https://context7.com/flarum/tags/llms.txt

Creates a new discussion and assigns a primary tag to it. Tag requirements are enforced unless the user has `bypassTagCounts` permission.

```bash
# Create discussion with primary tag
curl -X POST "https://forum.example.com/api/discussions" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "data": { \
      "type": "discussions", \
      "attributes": { \
        "title": "New Feature Discussion", \
        "content": "Let us discuss the new tagging features!" \
      }, \
      "relationships": { \
        "tags": { \
          "data": [ \
            { "type": "tags", "id": "1" } \
          ] \
        } \
      } \
    } \
  }'
```

--------------------------------

### Create Discussion with Tags

Source: https://context7.com/flarum/tags/llms.txt

Creates a new discussion and associates tags with it. Tag requirements (min/max primary/secondary) are enforced unless the user has `bypassTagCounts` permission.

```APIDOC
## POST /api/discussions

### Description
Creates a new discussion with tag relationships.

### Method
POST

### Endpoint
`/api/discussions`

### Parameters
#### Request Body
- **data.type** (string) - Required - Must be "discussions".
- **data.attributes.title** (string) - Required - The title of the discussion.
- **data.attributes.content** (string) - Required - The content of the discussion.
- **data.relationships.tags.data** (array) - Optional - An array of tag objects to associate with the discussion.
  - Each object should have `type` (string, "tags") and `id` (string).

### Request Example
```json
{
  "data": {
    "type": "discussions",
    "attributes": {
      "title": "New Feature Discussion",
      "content": "Let us discuss the new tagging features!"
    },
    "relationships": {
      "tags": {
        "data": [
          { "type": "tags", "id": "1" }
        ]
      }
    }
  }
}
```

### Response
#### Success Response (201 Created)
- **data.type** (string) - Type of the resource, always "discussions".
- **data.id** (string) - The ID of the newly created discussion.
- **data.attributes.title** (string) - The title of the discussion.
- **data.attributes.canTag** (boolean) - Indicates if the user can tag discussions.
- **data.relationships.tags.data** (array) - An array of tag objects associated with the discussion.
- **included** (array) - Optional - Included resources, typically the tag details.
  - **included[].type** (string) - Type of the included resource, always "tags".
  - **included[].id** (string) - The ID of the tag.
  - **included[].attributes.name** (string) - The name of the tag.
  - **included[].attributes.slug** (string) - The slug of the tag.

#### Response Example
```json
{
  "data": {
    "type": "discussions",
    "id": "42",
    "attributes": {
      "title": "New Feature Discussion",
      "canTag": true
    },
    "relationships": {
      "tags": {
        "data": [{ "type": "tags", "id": "1" }]
      }
    }
  },
  "included": [
    {
      "type": "tags",
      "id": "1",
      "attributes": { "name": "General", "slug": "general" }
    }
  ]
}
```
```

--------------------------------

### Open Tag Selection Modal

Source: https://context7.com/flarum/tags/llms.txt

Opens a modal for selecting tags, with options to configure limits, filters, permissions, and callbacks for selection and deselection. The onsubmit callback saves the selected tags to a discussion.

```typescript
import app from 'flarum/forum/app';
import TagSelectionModal from 'flarum/tags/common/components/TagSelectionModal';
import type Tag from 'flarum/tags/common/models/Tag';

// Open tag selection modal
app.modal.show(TagSelectionModal, {
  title: 'Select Categories',
  selectedTags: discussion.tags() as Tag[],

  // Configure tag count limits
  limits: {
    allowBypassing: app.forum.attribute('canBypassTagCounts'),
    min: {
      primary: 1,
      secondary: 0,
      total: 1,
    },
    max: {
      primary: 3,
      secondary: 5,
      total: 8,
    },
  },

  // Filter which tags can be selected
  selectableTags: (tags) => tags.filter(tag => !tag.isHidden()),

  // Permission check for each tag
  canSelect: (tag) => tag.canStartDiscussion(),

  // Require parent tag when selecting child
  requireParentTag: true,

  // Allow resetting to zero tags
  allowResetting: false,

  // Callbacks
  onSelect: (tag, selected) => {
    console.log('Tag selected:', tag.name());
  },
  onDeselect: (tag, selected) => {
    console.log('Tag deselected:', tag.name());
  },
  onsubmit: (selectedTags) => {
    // Save selected tags to discussion
    discussion.save({
      relationships: { tags: selectedTags }
    }).then(() => {
      app.alerts.show({ type: 'success' }, 'Tags updated!');
    });
  },
});
```

--------------------------------

### Show Single Tag

Source: https://context7.com/flarum/tags/llms.txt

Retrieves a specific tag by its ID or slug. Supports including related resources.

```APIDOC
## GET /api/tags/{id_or_slug}

### Description
Retrieves a specific tag by ID or slug, supporting UTF-8 slugs with URL encoding. Can include parent and children relationships.

### Method
GET

### Endpoint
/api/tags/{id_or_slug}

### Parameters
#### Path Parameters
- **id_or_slug** (string) - Required - The unique identifier or slug of the tag.

### Query Parameters
- **include** (string) - Optional - Comma-separated list of relationships to include (e.g., `parent`, `parent.children`).

### Request Example
```bash
# Get tag by ID
curl -X GET "https://forum.example.com/api/tags/1"
  -H "Authorization: Token YOUR_API_TOKEN"

# Get tag by slug
curl -X GET "https://forum.example.com/api/tags/general"
  -H "Authorization: Token YOUR_API_TOKEN"

# Get tag with UTF-8 slug (URL encoded)
curl -X GET "https://forum.example.com/api/tags/%E6%B5%8B%E8%AF%95"
  -H "Authorization: Token YOUR_API_TOKEN"

# Include parent and children relationships
curl -X GET "https://forum.example.com/api/tags/child-tag?include=parent,parent.children"
  -H "Authorization: Token YOUR_API_TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - The tag object.
  - **type** (string) - The resource type, always "tags".
  - **id** (string) - The unique identifier for the tag.
  - **attributes** (object) - The tag's attributes.
    - **name** (string) - The name of the tag.
    - **slug** (string) - The URL-friendly slug for the tag.
    - **description** (string) - A description of the tag.
    - **color** (string) - The color associated with the tag (hex format).
    - **icon** (string) - The icon class for the tag.
    - **isHidden** (boolean) - Whether the tag is hidden.
    - **isPrimary** (boolean) - Whether the tag is a primary tag.
    - **isRestricted** (boolean) - Whether the tag is restricted.
    - **backgroundUrl** (string|null) - URL for the tag's background image.
    - **backgroundMode** (string|null) - Mode for the background image display.
    - **position** (integer) - The display order of the tag.
    - **defaultSort** (string|null) - Default sort order for discussions in this tag.
    - **isChild** (boolean) - Whether the tag is a child tag.
    - **discussionCount** (integer) - The number of discussions associated with this tag.
    - **lastPostedAt** (string) - The timestamp of the last post.
    - **canStartDiscussion** (boolean) - Whether the user can start a discussion in this tag.
    - **canAddToDiscussion** (boolean) - Whether the user can add this tag to a discussion.

#### Response Example
```json
{
  "data": {
    "type": "tags",
    "id": "1",
    "attributes": {
      "name": "General",
      "slug": "general",
      "description": "General discussions",
      "color": "#FF5733",
      "icon": "fas fa-comments",
      "isHidden": false,
      "isPrimary": true,
      "isRestricted": false,
      "backgroundUrl": null,
      "backgroundMode": null,
      "position": 0,
      "defaultSort": null,
      "isChild": false,
      "discussionCount": 42,
      "lastPostedAt": "2024-01-15T10:30:00Z",
      "canStartDiscussion": true,
      "canAddToDiscussion": true
    }
  }
}
```
```

--------------------------------

### Order Tags

Source: https://context7.com/flarum/tags/llms.txt

Reorders tags, allowing for parent-child hierarchy definition. This endpoint is for administrators only.

```APIDOC
## POST /api/tags/order

### Description
Reorders tags with parent-child hierarchy.

### Method
POST

### Endpoint
`/api/tags/order`

### Parameters
#### Request Body
- **order** (array) - Required - An array of tag objects defining the new order and hierarchy.
  - Each object should have an `id` (string, required) and an optional `children` array (array of strings).

### Request Example
```json
{
  "order": [
    { "id": "1" },
    { "id": "2", "children": ["3", "4"] },
    { "id": "5", "children": ["6", "7", "8"] }
  ]
}
```

### Response
#### Success Response (204 No Content)
No content is returned upon successful reordering.
```

--------------------------------

### Retrieve Single Tag with Flarum API

Source: https://context7.com/flarum/tags/llms.txt

Fetches a specific tag by its ID or slug. Supports UTF-8 slugs and inclusion of parent/child relationships.

```bash
# Get tag by ID
curl -X GET "https://forum.example.com/api/tags/1" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

```bash
# Get tag by slug
curl -X GET "https://forum.example.com/api/tags/general" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

```bash
# Get tag with UTF-8 slug (URL encoded)
curl -X GET "https://forum.example.com/api/tags/%E6%B5%8B%E8%AF%95" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

```bash
# Include parent and children relationships
curl -X GET "https://forum.example.com/api/tags/child-tag?include=parent,parent.children" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

--------------------------------

### Filter Discussions by Multiple Tag Slugs

Source: https://context7.com/flarum/tags/llms.txt

Searches for discussions tagged with any of the specified tags, using a comma-separated list of slugs. This performs an OR condition.

```bash
# Filter by multiple tags (OR condition using comma)
curl -X GET "https://forum.example.com/api/discussions?filter[tag]=general,announcements" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

--------------------------------

### Manage Tag List State

Source: https://context7.com/flarum/tags/llms.txt

Utilizes the global TagListState to load and cache tags. Supports loading with specific relationships and forcing a fresh query to bypass the cache.

```typescript
import app from 'flarum/forum/app';
import TagListState from 'flarum/tags/common/states/TagListState';

// The global tag list state is available at app.tagList
const tagList: TagListState = app.tagList;

// Load tags (cached after first load)
tagList.load().then(tags => {
  console.log('Loaded tags:', tags.length);
});

// Load with specific includes
tagList.load(['parent', 'children', 'lastPostedDiscussion']).then(tags => {
  tags.forEach(tag => {
    const lastDiscussion = tag.lastPostedDiscussion();
    if (lastDiscussion) {
      console.log(`${tag.name()} - Last post: ${lastDiscussion.title()}`);
    }
  });
});

// Force fresh query (bypasses cache for new includes)
tagList.query(['parent']).then(tags => {
  // Fresh data from server
});
```

--------------------------------

### Open Tag Discussion Modal

Source: https://context7.com/flarum/tags/llms.txt

Shows a specialized modal for tagging discussions. It can be used to edit existing discussion tags or select tags for a new discussion, with an onsubmit callback to handle the selected tags.

```typescript
import app from 'flarum/forum/app';
import TagDiscussionModal from 'flarum/tags/forum/components/TagDiscussionModal';

// Edit existing discussion tags
app.modal.show(TagDiscussionModal, {
  discussion: discussion,
  onsubmit: (tags) => {
    console.log('Discussion tagged with:', tags.map(t => t.name()));
  },
});

// Select tags for new discussion (no discussion object)
app.modal.show(TagDiscussionModal, {
  selectedTags: [],
  onsubmit: (tags) => {
    // Use selected tags when creating discussion
    app.store.createRecord('discussions').save({
      title: 'New Discussion',
      content: 'Discussion content...',
      relationships: { tags }
    });
  },
});
```

--------------------------------

### Filter Discussions by Single Tag Slug

Source: https://context7.com/flarum/tags/llms.txt

Searches for discussions that are tagged with a specific tag, identified by its slug. Requires `Authorization` header.

```bash
# Filter by single tag slug
curl -X GET "https://forum.example.com/api/discussions?filter[tag]=general" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

--------------------------------

### Delete Tag

Source: https://context7.com/flarum/tags/llms.txt

Deletes a tag. Requires `delete` permission.

```APIDOC
## DELETE /api/tags/{id}

### Description
Deletes a tag.

### Method
DELETE

### Endpoint
`/api/tags/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the tag to delete.

### Response
#### Success Response (204 No Content)
No content is returned upon successful deletion.
```

--------------------------------

### Register Custom Tag Permissions

Source: https://context7.com/flarum/tags/llms.txt

Register custom permissions scoped to individual tags using the Policy extension. This allows for granular control over tag moderation based on user permissions and tag properties.

```php
<?php

use Flarum\Extend;
use Flarum\Tags\Tag;

return [
    (new Extend\Policy())
        ->modelPolicy(Tag::class, CustomTagPolicy::class),
];

class CustomTagPolicy extends \Flarum\User\Access\AbstractPolicy
{
    public function moderate(User $actor, Tag $tag): ?string
    {
        if ($tag->is_restricted) {
            return $actor->hasPermission("tag{$tag->id}.moderate")
                ? $this->allow()
                : $this->deny();
        }
        return null;
    }
}
```

--------------------------------

### Filter Discussions by Tag

Source: https://context7.com/flarum/tags/llms.txt

Searches for discussions using the `tag` filter, supporting slug-based queries for single tags, multiple tags, untagged discussions, and tag exclusion.

```APIDOC
## GET /api/discussions?filter[tag]={slug}

### Description
Filters discussions by tag slug.

### Method
GET

### Endpoint
`/api/discussions`

### Parameters
#### Query Parameters
- **filter[tag]** (string) - Required - The tag slug to filter by. Can be a single slug, comma-separated slugs (OR condition), "untagged" for discussions without tags, or a negated slug (e.g., "-off-topic") to exclude discussions with a specific tag.

### Request Example
```bash
# Filter by single tag slug
curl -X GET "https://forum.example.com/api/discussions?filter[tag]=general"

# Filter by multiple tags (OR condition)
curl -X GET "https://forum.example.com/api/discussions?filter[tag]=general,announcements"

# Filter for untagged discussions
curl -X GET "https://forum.example.com/api/discussions?filter[tag]=untagged"

# Negate filter (exclude tag)
curl -X GET "https://forum.example.com/api/discussions?filter[-tag]=off-topic"
```

### Response
#### Success Response (200 OK)
- **data** (array) - An array of discussion objects matching the filter criteria.
  - Each object contains `type`, `id`, `attributes` (including `title`), and `relationships` (including associated `tags`).

#### Response Example
```json
{
  "data": [
    {
      "type": "discussions",
      "id": "42",
      "attributes": { "title": "Discussion in General" },
      "relationships": {
        "tags": { "data": [{ "type": "tags", "id": "1" }] }
      }
    }
  ]
}
```
```

--------------------------------

### Update Tag

Source: https://context7.com/flarum/tags/llms.txt

Updates an existing tag's attributes. Requires `edit` permission.

```APIDOC
## PATCH /api/tags/{id}

### Description
Updates an existing tag's attributes.

### Method
PATCH

### Endpoint
`/api/tags/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the tag to update.

#### Request Body
- **data.type** (string) - Required - Must be "tags".
- **data.id** (string) - Required - The ID of the tag to update.
- **data.attributes.name** (string) - Optional - The new name for the tag.
- **data.attributes.description** (string) - Optional - The new description for the tag.
- **data.attributes.color** (string) - Optional - The new color for the tag (e.g., "#654321").
- **data.attributes.isRestricted** (boolean) - Optional - Whether the tag is restricted.

### Request Example
```json
{
  "data": {
    "type": "tags",
    "id": "15",
    "attributes": {
      "name": "Development Blog",
      "description": "Updated description for dev blog",
      "color": "#654321",
      "isRestricted": true
    }
  }
}
```

### Response
#### Success Response (200 OK)
- **data.type** (string) - Type of the resource, always "tags".
- **data.id** (string) - The ID of the tag.
- **data.attributes.name** (string) - The name of the tag.
- **data.attributes.slug** (string) - The slug of the tag.
- **data.attributes.description** (string) - The description of the tag.
- **data.attributes.color** (string) - The color of the tag.
- **data.attributes.isRestricted** (boolean) - Whether the tag is restricted.

#### Response Example
```json
{
  "data": {
    "type": "tags",
    "id": "15",
    "attributes": {
      "name": "Development Blog",
      "slug": "dev-blog",
      "description": "Updated description for dev blog",
      "color": "#654321",
      "isRestricted": true
    }
  }
}
```
```

--------------------------------

### Update Discussion Tags

Source: https://context7.com/flarum/tags/llms.txt

Modifies the tags associated with an existing discussion. Requires `tag` permission on the discussion.

```APIDOC
## PATCH /api/discussions/{id}

### Description
Modifies tags on an existing discussion.

### Method
PATCH

### Endpoint
`/api/discussions/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the discussion to update.

#### Request Body
- **data.type** (string) - Required - Must be "discussions".
- **data.id** (string) - Required - The ID of the discussion to update.
- **data.relationships.tags.data** (array) - Required - An array of tag objects to associate with the discussion. This replaces the existing tags.
  - Each object should have `type` (string, "tags") and `id` (string).

### Request Example
```json
{
  "data": {
    "type": "discussions",
    "id": "42",
    "relationships": {
      "tags": {
        "data": [
          { "type": "tags", "id": "1" },
          { "type": "tags", "id": "5" }
        ]
      }
    }
  }
}
```

### Response
#### Success Response (200 OK)
Indicates success. This action typically creates a "discussionTagged" event post.
```

--------------------------------

### Order Tags API Request

Source: https://context7.com/flarum/tags/llms.txt

Reorders tags, allowing for parent-child hierarchy configuration. This operation is restricted to administrators only. The request body defines the new order and parent-child relationships.

```bash
curl -X POST "https://forum.example.com/api/tags/order" \
  -H "Authorization: Token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "order": [ \
      { "id": 1 }, \
      { "id": 2, "children": [3, 4] }, \
      { "id": 5, "children": [6, 7, 8] } \
    ] \
  }'
```

--------------------------------

### Handle DiscussionWasTagged Event

Source: https://context7.com/flarum/tags/llms.txt

Listens for the DiscussionWasTagged event to perform actions when a discussion's tags are modified. Access old and new tags to determine changes and implement custom logic.

```php
<?php

use Flarum\Tags\Event\DiscussionWasTagged;
use Illuminate\Contracts\Events\Dispatcher;

class TagChangeSubscriber
{
    public function subscribe(Dispatcher $events): void
    {
        $events->listen(DiscussionWasTagged::class, [$this, 'handleTagChange']);
    }

    public function handleTagChange(DiscussionWasTagged $event): void
    {
        $discussion = $event->discussion;
        $actor = $event->actor;
        $oldTags = $event->oldTags; // array of Tag objects

        // Get new tags
        $newTags = $discussion->tags;

        // Calculate added/removed tags
        $oldTagIds = collect($oldTags)->pluck('id')->all();
        $newTagIds = $newTags->pluck('id')->all();

        $addedTagIds = array_diff($newTagIds, $oldTagIds);
        $removedTagIds = array_diff($oldTagIds, $newTagIds);

        // Perform custom logic (notifications, logging, etc.)
        foreach ($addedTagIds as $tagId) {
            // Tag was added to discussion
        }
    }
}

```

--------------------------------

### Filter for Untagged Discussions

Source: https://context7.com/flarum/tags/llms.txt

Retrieves discussions that have not been assigned any tags. The `untagged` keyword is used in the `filter[tag]` parameter.

```bash
# Filter for untagged discussions
curl -X GET "https://forum.example.com/api/discussions?filter[tag]=untagged" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

--------------------------------

### Add Custom Fields to Tag API Resource

Source: https://context7.com/flarum/tags/llms.txt

Extend the Tag API resource to include custom fields. This allows for exposing and manipulating additional data associated with tags through the JSON:API.

```php
<?php

use Flarum\Api\Schema;
use Flarum\Extend;
use Flarum\Tags\Api\Resource\TagResource;
use Flarum\Tags\Tag;

return [
    (new Extend\ApiResource(TagResource::class))
        ->fields(fn () => [
            Schema\Str::make('customField')
                ->get(fn (Tag $tag) => $tag->custom_field)
                ->writable(),
            Schema\Integer::make('subscriberCount')
                ->get(fn (Tag $tag) => $tag->subscribers()->count()),
        ]),
];
```

--------------------------------

### Update Tag API Request

Source: https://context7.com/flarum/tags/llms.txt

Updates an existing tag's attributes. Requires `edit` permission. The request body specifies the tag's ID and the attributes to modify.

```bash
curl -X PATCH "https://forum.example.com/api/tags/15" \
  -H "Authorization: Token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "data": { \
      "type": "tags", \
      "id": "15", \
      "attributes": { \
        "name": "Development Blog", \
        "description": "Updated description for dev blog", \
        "color": "#654321", \
        "isRestricted": true \
      } \
    } \
  }'
```

--------------------------------

### Delete Tag API Request

Source: https://context7.com/flarum/tags/llms.txt

Deletes a tag. Requires `delete` permission. The endpoint specifies the tag ID to be removed.

```bash
curl -X DELETE "https://forum.example.com/api/tags/15" \
  -H "Authorization: Token YOUR_ADMIN_TOKEN"
```

--------------------------------

### Filter Discussions Excluding a Tag

Source: https://context7.com/flarum/tags/llms.txt

Searches for discussions that are not tagged with a specific tag. The `tag` filter is negated by prefixing the slug with a hyphen (`-`).

```bash
# Negate filter (exclude tag)
curl -X GET "https://forum.example.com/api/discussions?filter[-tag]=off-topic" \
  -H "Authorization: Token YOUR_API_TOKEN"
```

--------------------------------

### Update Discussion Tags API Request

Source: https://context7.com/flarum/tags/llms.txt

Modifies the tags associated with an existing discussion. Requires `tag` permission on the discussion. The request body specifies the discussion ID and the new set of tags.

```bash
curl -X PATCH "https://forum.example.com/api/discussions/42" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "data": { \
      "type": "discussions", \
      "id": "42", \
      "relationships": { \
        "tags": { \
          "data": [ \
            { "type": "tags", "id": "1" }, \
            { "type": "tags", "id": "5" } \
          ] \
        } \
      } \
    } \
  }'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.