Flarum Tags

https://github.com/flarum/tags
Admin
Flarum Tags is an official Flarum extension that adds tag-based organization to forums, providing...
Tokens:34,494
Snippets:275
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### TagSelectionModal usage example

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-components.md

Shows how to open the TagSelectionModal with selected tags, limits, and a callback. The example sets a minimum of one primary tag, a maximum of three primary and three secondary tags, and requires a parent tag.

```tsx
import TagSelectionModal from 'flarum-tags/common/components/TagSelectionModal';

app.modal.show(TagSelectionModal, {
  selectedTags: discussion.tags() as Tag[],
  limits: { min: { primary: 1 }, max: { primary: 3, secondary: 3 } },
  requireParentTag: true,
  onsubmit: (tags) => console.log(tags),
});
```

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

### TagRepository usage example

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-repositories-and-state.md

Example usage of TagRepository: retrieving all visible tags, finding a tag by ID (may throw), and getting an ID from a slug.

```php
use Flarum\Tags\TagRepository;

$repo = $app->container->make(TagRepository::class);

$allVisible = $repo->all($actor);
$one = $repo->findOrFail(3, $actor);            // may throw ModelNotFoundException
$id = $repo->getIdForSlug('general', $actor);   // ?int
```

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

### TagState usage example

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-repositories-and-state.md

Example usage of TagState: retrieving a user's state for a tag, updating marked_as_read_at, and saving with the composite key.

```php
use Flarum\Tags\TagState;

// Read a user's state for a tag (typically via Tag::stateFor()).
$state = $tag->stateFor($user);
$state->marked_as_read_at = now();
$state->save(); // uses composite key, no auto-increment
```

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

### TagFactory usage example

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-repositories-and-state.md

Example usage of TagFactory to create a fake Tag record with a custom name.

```php
use Flarum\Tags\TagFactory;

$tag = TagFactory::new()->create(['name' => 'Custom']);
```

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

### Example: filtering primary and secondary tags

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Shows how to retrieve all tags from the application store and filter them into primary (using isPrimaryParent()) and secondary (position is null) tags.

```ts
import app from 'flarum/common/app';

const tags = app.store.all<Tag>('tags');
const primary = tags.filter((t) => t.isPrimaryParent());
const secondary = tags.filter((t) => t.position() === null);
```

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

### Request body example

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-api-resource.md

Example JSON request body for the order endpoint. The order array contains objects with an id and children array, specifying the new tag hierarchy.

```json
{
  "order": [
    { "id": 1, "children": [5, 6] },
    { "id": 2, "children": [] }
  ]
}
```

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

### Checking permissions in code

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-access-policies.md

Shows how to use the actor's can and assertCan methods to check permissions for starting discussions, tagging discussions, and adding to discussions.

```php
use Flarum\Tags\Tag;

$canStart = $actor->can('startDiscussion', $tag);
$canTagDiscussion = $actor->can('tag', $discussion);
$actor->assertCan('addToDiscussion', $tag); // throws PermissionDeniedException
```

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

### Example: using tagsLabel and tagIcon helpers

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Shows how to import and use the `tagsLabel` and `tagIcon` helpers. `tagsLabel` renders a group of tag labels inside a `TagsLabel` span, sorted with `sortTags`; `tagIcon` renders a tag's icon or placeholder.

```tsx
import tagsLabel from 'flarum-tags/common/helpers/tagsLabel';
import tagIcon from 'flarum-tags/common/helpers/tagIcon';

const label = tagsLabel(discussion.tags(), { link: true });
const icon = tagIcon(tag, { className: 'Button-icon' });
```

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

### TagListState usage example

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Shows how to load tags with specific includes using the TagListState instance from the app. The load method returns a promise that resolves to an array of tags, which are logged to the console.

```typescript
import app from 'flarum/common/app';

app.tagList.load(['parent', 'children']).then((tags) => {
  console.log(tags);
});
```

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

### sortTags usage example

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Shows how to use the sortTags utility to sort all tags from the store. The result is assigned to a constant named 'ordered'.

```typescript
import sortTags from 'flarum-tags/common/utils/sortTags';

const ordered = sortTags(app.store.all<Tag>('tags'));
```

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

### Creating a DiscussionTaggedPost with reply

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

Example of creating a DiscussionTaggedPost using the reply method and merging it into a discussion. The comment notes that this is similar to what CreatePostWhenTagsAreChanged does.

```php
use Flarum\Tags\Post\DiscussionTaggedPost;

$post = DiscussionTaggedPost::reply($discussionId, $userId, [1, 2], [2, 3]);
$discussion->mergePost($post); // like CreatePostWhenTagsAreChanged does
```

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

### GET /tags

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-api-resource.md

Lists all tags visible to the current actor. Supports default include of `parent`.

```APIDOC
## GET /tags

### Description
Lists all tags visible to the current actor. Supports default include of `parent`.

### Method
GET

### Endpoint
/tags

### Parameters
#### Query Parameters
- **include** (string) - Optional - Comma-separated list of relations to include. Default includes `parent`.

### Response
#### Success Response (200)
- **data** (array) - Array of tag resource objects.

#### Response Example
```json
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "name": "General",
        "description": "General discussion",
        "slug": "general",
        "color": "#888",
        "icon": "fas fa-comments",
        "isHidden": false,
        "isPrimary": true,
        "discussionCount": 10,
        "position": 1,
        "defaultSort": null,
        "isChild": false,
        "lastPostedAt": "2023-01-01T00:00:00+00:00",
        "canStartDiscussion": true,
        "canAddToDiscussion": true
      },
      "relationships": {
        "parent": {
          "data": null
        },
        "children": {
          "data": []
        },
        "lastPostedDiscussion": {
          "data": null
        }
      }
    }
  ]
}
```
```

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

### GET /tags

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Renders the All Tags page listing all visible tags. Public route; only tags visible to the current user are returned.

```APIDOC
## GET /tags

### Description
Renders the All Tags page, displaying all tags visible to the current user.

### Method
GET

### Endpoint
/tags

### Parameters
No parameters.

### Request Example
GET /tags

### Response
#### Success Response (200)
- HTML page rendered by the server-side handler

#### Response Example
(HTML content)

### Notes
- Auth: public; only visible tags are returned
- The SSR handler internally calls `GET /tags` including `children,lastPostedDiscussion,parent`.
```

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

### GET /tags/{id}

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-api-resource.md

Shows a single tag by ID or slug. No authentication required.

```APIDOC
## GET /tags/{id}

### Description
Shows a single tag by ID or slug. No authentication required.

### Method
GET

### Endpoint
/tags/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The tag ID or slug.

### Response
#### Success Response (200)
- **data** (object) - The tag resource object.

#### Response Example
```json
{
  "data": {
    "type": "tags",
    "id": "1",
    "attributes": {
      "name": "General",
      "description": "General discussion",
      "slug": "general",
      "color": "#888",
      "icon": "fas fa-comments",
      "isHidden": false,
      "isPrimary": true,
      "discussionCount": 10,
      "position": 1,
      "defaultSort": null,
      "isChild": false,
      "lastPostedAt": "2023-01-01T00:00:00+00:00",
      "canStartDiscussion": true,
      "canAddToDiscussion": true
    },
    "relationships": {
      "parent": {
        "data": null
      },
      "children": {
        "data": []
      },
      "lastPostedDiscussion": {
        "data": null
      }
    }
  }
}
```
```

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

### GET /api/tags

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Lists all tags. The response includes the `parent` relationship by default and is scoped to the actor's visibility.

```APIDOC
## GET /api/tags

### Description
Lists all tags. The response includes the `parent` relationship by default and is scoped to the actor's visibility.

### Method
GET

### Endpoint
/api/tags

### Parameters
None

### Response
#### Success Response (200)
- **data** (array) - List of tag resources
- **data[].type** (string) - Resource type, always "tags"
- **data[].id** (string) - Tag ID
- **data[].attributes** (object) - Tag attributes (see below)
- **data[].relationships** (object) - Tag relationships (see below)

#### Response Example
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "name": "General",
        "description": "General discussions",
        "slug": "general",
        "color": "#888",
        "icon": "fas fa-comments",
        "isHidden": false,
        "isPrimary": true,
        "discussionCount": 10,
        "position": 1,
        "defaultSort": "latest",
        "isChild": false,
        "lastPostedAt": "2023-01-01T00:00:00+00:00",
        "canStartDiscussion": true,
        "canAddToDiscussion": true
      },
      "relationships": {
        "parent": {
          "data": null
        },
        "children": {
          "data": []
        },
        "lastPostedDiscussion": {
          "data": null
        }
      }
    }
  ]
}

```

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

### GET /t/{slug}

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Renders a single tag page. Public route; the tag must be visible to the actor. Supports sorting, search, pagination, and filtering via query parameters.

```APIDOC
## GET /t/{slug}

### Description
Renders a single tag page for the given tag slug. The tag must be visible to the current user, otherwise a 404 error is returned.

### Method
GET

### Endpoint
/t/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The tag's slug (resolved via the active slug driver)

#### Query Parameters
- **sort** (string) - Optional - Discussion sort; defaults to the tag's `default_sort`
- **q** (string) - Optional - Search query; defaults to empty string
- **page** (number) - Optional - Page number (20 per page); defaults to 1
- **filter** (object) - Optional - Extra filters merged with `tag`; defaults to empty array

### Request Example
GET /t/general?sort=newest&q=test&page=2&filter[author]=admin

### Response
#### Success Response (200)
- HTML page rendered by the server-side handler

#### Response Example
(HTML content)

### Notes
- Auth: public; tag must be visible to the actor
- The SSR handler internally calls `GET /discussions` (filter `tag => slug`, page offset/limit 20) and `GET /tags/{slug}`.
```

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

### GET /api/tags/{id|slug}

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Shows a single tag, resolved by numeric ID or slug.

```APIDOC
## GET /api/tags/{id|slug}

### Description
Shows a single tag, resolved by numeric ID or slug.

### Method
GET

### Endpoint
/api/tags/{id|slug}

### Parameters
#### Path Parameters
- **id|slug** (string) - Required - The tag's numeric ID or slug.

### Response
#### Success Response (200)
- **data** (object) - The tag resource
- **data.type** (string) - Resource type, always "tags"
- **data.id** (string) - Tag ID
- **data.attributes** (object) - Tag attributes
- **data.relationships** (object) - Tag relationships

#### Response Example
{
  "data": {
    "type": "tags",
    "id": "1",
    "attributes": {
      "name": "General",
      "description": "General discussions",
      "slug": "general",
      "color": "#888",
      "icon": "fas fa-comments",
      "isHidden": false,
      "isPrimary": true,
      "discussionCount": 10,
      "position": 1,
      "defaultSort": "latest",
      "isChild": false,
      "lastPostedAt": "2023-01-01T00:00:00+00:00",
      "canStartDiscussion": true,
      "canAddToDiscussion": true
    },
    "relationships": {
      "parent": {
        "data": null
      },
      "children": {
        "data": []
      },
      "lastPostedDiscussion": {
        "data": null
      }
    }
  }
}

```

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

### Tag visibility scoping with whereVisibleTo and whereHasPermission

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-tag-model.md

Use this snippet to fetch tags visible to an actor, with state loaded, and to fetch tags where the actor can start a discussion. The methods whereVisibleTo and whereHasPermission are used. Note that these methods can throw ModelNotFoundException when no matching tag is found.

```php
use Flarum\Tags\Tag;
use Flarum\User\User;

$actor = User::find(1);

// Only tags the actor can see, with their state loaded.
$tags = Tag::whereVisibleTo($actor)->withStateFor($actor)->get();

// Only tags where the actor can start a discussion.
$startable = Tag::whereHasPermission($actor, 'startDiscussion')->get();
```

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

### Resolving a tag slug in application code

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-slug-drivers.md

Example of using SlugManager to resolve a tag slug to a Tag instance and back to a URL slug. Catches ModelNotFoundException when the tag is not found or not visible to the actor.

```php
use Flarum\Http\SlugManager;
use Flarum\Tags\Tag;

$slugger = $app->container->make(SlugManager::class);

try {
    $tag = $slugger->forResource(Tag::class)->fromSlug($requestedSlug, $actor);
    $urlSlug = $slugger->forResource(Tag::class)->toSlug($tag);
} catch (\Illuminate\Database\Eloquent\ModelNotFoundException $e) {
    // tag not found or not visible to the actor
}
```

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

### Listen to DiscussionWasTagged with Extend\Event

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

Shows how to subscribe a listener class to the DiscussionWasTagged event from an extension's boot or extend.php using Extend\Event::listen().

```php
use Flarum\Tags\Event\DiscussionWasTagged;

// Inside an extension boot / extend.php:
(new Extend\Event())
    ->listen(DiscussionWasTagged::class, MyListener::class);
```

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

### POST /tags

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-api-resource.md

Creates a new tag. Requires authentication and the `createTag` permission.

```APIDOC
## POST /tags

### Description
Creates a new tag. Requires authentication and the `createTag` permission.

### Method
POST

### Endpoint
/tags

### Parameters
#### Request Body
- **data.type** (string) - Required - Must be `tags`.
- **data.attributes.name** (string) - Required - The tag name.
- **data.attributes.description** (string) - Optional - Tag description, max 700 characters, nullable.
- **data.attributes.slug** (string) - Required - Unique slug, cannot contain `/`, `\`, or spaces.
- **data.attributes.color** (string) - Optional - Hex color code, nullable.
- **data.attributes.icon** (string) - Optional - Icon identifier, nullable.
- **data.attributes.isHidden** (boolean) - Optional - Whether the tag is hidden.
- **data.attributes.isPrimary** (boolean) - Optional - Whether the tag is primary.
- **data.attributes.defaultSort** (string) - Optional - Default sort alias, nullable.
- **data.relationships.parent.data.id** (string) - Optional - Parent tag ID, only writable when `isPrimary` is truthy.

### Request Example
```json
{
  "data": {
    "type": "tags",
    "attributes": {
      "name": "New Tag",
      "description": "A new tag",
      "slug": "new-tag",
      "color": "#ff0000",
      "icon": "fas fa-tag",
      "isHidden": false,
      "isPrimary": false
    }
  }
}
```

### Response
#### Success Response (201)
- **data** (object) - The created tag resource object.

#### Response Example
```json
{
  "data": {
    "type": "tags",
    "id": "2",
    "attributes": {
      "name": "New Tag",
      "description": "A new tag",
      "slug": "new-tag",
      "color": "#ff0000",
      "icon": "fas fa-tag",
      "isHidden": false,
      "isPrimary": false,
      "discussionCount": 0,
      "position": null,
      "defaultSort": null,
      "isChild": false,
      "lastPostedAt": null,
      "canStartDiscussion": true,
      "canAddToDiscussion": true
    },
    "relationships": {
      "parent": {
        "data": null
      },
      "children": {
        "data": []
      },
      "lastPostedDiscussion": {
        "data": null
      }
    }
  }
}
```
```

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

### Forum Initializer: app.initializers.add('flarum-tags')

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-extenders.md

Registers the forum initializer for the flarum-tags extension. It sets up the tag list state and adds tag-related UI components and filters. If the flarum-realtime extension is present, it also extends realtime functionality.

```TypeScript
app.initializers.add('flarum-tags', () => {
  app.tagList = new TagListState();
  addTagList();
  addTagFilter();
  addTagLabels();
  addTagControl();
  addTagComposer();
  if ('flarum-realtime' in flarum.extensions) {
    extendRealtime();
  }
});
```

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

### Admin Initializer: app.initializers.add('flarum-tags', (app) => ...)

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-extenders.md

Registers the admin initializer for the flarum-tags extension. It sets up the tag list state and adds various admin-side permission and setting components.

```TypeScript
app.initializers.add('flarum-tags', (app) => {
  app.tagList = new TagListState();
  addTagsPermissionScope();
  addTagsHomePageOption();
  addTagChangePermission();
  addTagSelectionSettingComponent();
  addTagSlugDriverLabels();
});
```

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

### GlobalPolicy class definition

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-access-policies.md

Defines the GlobalPolicy class with a verdict cache and constructor. The class checks tag count permissions for starting discussions and viewing the forum.

```php
class GlobalPolicy extends AbstractPolicy
{
    protected array $enoughTags = [];  // verdict cache "{actor id}:{ability}" => bool

    public function __construct(protected SettingsRepositoryInterface $settings) {}

    public function can(User $actor, string $ability): ?string
    protected function enoughTagsWithPermission(User $actor, string $ability, int $minPrimary, int $minSecondary): bool
}
```

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

### TagRepository all signature

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-repositories-and-state.md

Signature for all, which returns all tags (optionally visible to the given user) as an Eloquent Collection.

```php
public function all(?User $user = null): Collection
```

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

### Creating event class constructor

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

Constructor for the Creating event, holding the new Tag, the acting User, and the request body data array. Includes a doc comment in source.

```php
class Creating
{
    public function __construct(
        public Tag $tag,
        public User $actor,
        public array $data
    ) {}
}
```

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

### Settings serialization in extend.php

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/configuration.md

Registers default and serializes tag-count settings to the forum frontend. Used in the extension's extend.php to configure the 'flarum-tags' settings namespace.

```php
(new Extend\Settings())
    ->default('slug_driver_'.Tag::class, 'default')
    ->serializeToForum('minPrimaryTags', 'flarum-tags.min_primary_tags')
    ->serializeToForum('maxPrimaryTags', 'flarum-tags.max_primary_tags')
    ->serializeToForum('minSecondaryTags', 'flarum-tags.min_secondary_tags')
    ->serializeToForum('maxSecondaryTags', 'flarum-tags.max_secondary_tags'),
```

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

### POST /api/tags

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Creates a new tag. Requires authentication and the `createTag` permission.

```APIDOC
## POST /api/tags

### Description
Creates a new tag. Requires authentication and the `createTag` permission.

### Method
POST

### Endpoint
/api/tags

### Parameters
#### Request Body
- **data** (object) - Required - The tag resource object
- **data.type** (string) - Required - Must be "tags"
- **data.attributes** (object) - Required - Tag attributes
- **data.attributes.name** (string) - Required - Tag name
- **data.attributes.description** (string) - Optional - Tag description
- **data.attributes.slug** (string) - Optional - Tag slug
- **data.attributes.color** (string) - Optional - Tag color
- **data.attributes.icon** (string) - Optional - Tag icon
- **data.attributes.isHidden** (boolean) - Optional - Whether the tag is hidden
- **data.attributes.isPrimary** (boolean) - Optional - Whether the tag is primary
- **data.attributes.isRestricted** (boolean) - Optional - Admin-only
- **data.attributes.position** (number) - Optional - Tag position
- **data.attributes.defaultSort** (string) - Optional - Default sort
- **data.relationships** (object) - Optional - Tag relationships
- **data.relationships.parent** (object) - Optional - Parent tag relationship
- **data.relationships.parent.data** (object) - Optional - Parent tag resource identifier
- **data.relationships.parent.data.type** (string) - Required - Must be "tags"
- **data.relationships.parent.data.id** (string) - Required - Parent tag ID

### Request Example
{
  "data": {
    "type": "tags",
    "attributes": {
      "name": "New Tag",
      "description": "A new tag",
      "slug": "new-tag",
      "color": "#ff0000",
      "icon": "fas fa-tag",
      "isHidden": false,
      "isPrimary": true,
      "position": 1
    },
    "relationships": {
      "parent": {
        "data": null
      }
    }
  }
}

### Response
#### Success Response (201)
- **data** (object) - The created tag resource

#### Response Example
{
  "data": {
    "type": "tags",
    "id": "10",
    "attributes": {
      "name": "New Tag",
      "description": "A new tag",
      "slug": "new-tag",
      "color": "#ff0000",
      "icon": "fas fa-tag",
      "isHidden": false,
      "isPrimary": true,
      "discussionCount": 0,
      "position": 1,
      "defaultSort": "latest",
      "isChild": false,
      "lastPostedAt": null,
      "canStartDiscussion": true,
      "canAddToDiscussion": true
    },
    "relationships": {
      "parent": {
        "data": null
      },
      "children": {
        "data": []
      },
      "lastPostedDiscussion": {
        "data": null
      }
    }
  }
}

```

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

### POST /api/tags/order

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-api-resource.md

Documentation for the OrderTagsController endpoint that handles POST /api/tags/order.

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

### Description
Handles the reordering of tags. Requires an admin actor. Resets all tags and applies the new order from the request body.

### Method
POST

### Endpoint
/api/tags/order

### Parameters
#### Request Body
- **order** (array) - Required - An array of objects, each containing an `id` and an optional `children` array of tag IDs.

### Request Example
{
  "order": [
    { "id": 1, "children": [5, 6] },
    { "id": 2, "children": [] }
  ]
}

### Response
#### Success Response (204)
No content. Indicates the order was successfully updated.

#### Error Response (422)
Returned when the `order` field is missing or null.

### Authentication
Admin only. Requires an admin actor, otherwise throws `PermissionDeniedException`.
```

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

### Register policies and visibility scopes in extend.php

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-access-policies.md

Registers the DiscussionPolicy, TagPolicy, GlobalPolicy, and visibility scopes for Discussion and Tag models using Extend\Policy and Extend\ModelVisibility.

```php
(new Extend\Policy())
    ->modelPolicy(Discussion::class, Access\DiscussionPolicy::class)
    ->modelPolicy(Tag::class, Access\TagPolicy::class)
    ->globalPolicy(Access\GlobalPolicy::class),

(new Extend\ModelVisibility(Discussion::class))
    ->scopeAll(Access\ScopeDiscussionVisibilityForAbility::class),

(new Extend\ModelVisibility(Tag::class))
    ->scope(Access\ScopeTagVisibility::class),
```

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

### TagRepository method signatures

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-repositories-and-state.md

Method signatures for the TagRepository class, showing the available query and read methods with optional user scoping.

```php
public function query(): Builder
public function queryVisibleTo(?User $actor = null): Builder
public function findOrFail(int $id, ?User $actor = null): Tag
public function all(?User $user = null): Collection   // Collection<int, Tag>
public function getIdForSlug(string $slug, ?User $user = null): ?int
protected function scopeVisibleTo(Builder $query, ?User $user = null): Builder
```

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

### Import SelectTagsSettingComponent

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-components.md

Imports the SelectTagsSettingComponent from the flarum-tags admin components.

```tsx
import SelectTagsSettingComponent from 'flarum-tags/admin/components/SelectTagsSettingComponent';
```

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

### IdWithSlugDriver class skeleton

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-slug-drivers.md

Shows the class structure of the IdWithSlugDriver, including its constructor and the three public methods. The method bodies are not shown in the source.

```php
class IdWithSlugDriver implements SlugDriverInterface, BatchSlugDriverInterface
{
    public function __construct(
        protected TagRepository $repository
    ) {
    }

    public function toSlug(AbstractModel $instance): string
    public function fromSlug(string $slug, User $actor): AbstractModel
    public function fromSlugs(array $slugs, User $actor): Collection
}
```

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

### scopeWithStateFor method

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-tag-model.md

Eager-loads the user's state relation on the query and returns the query builder.

```php
public function scopeWithStateFor(Builder $query, User $user): Builder
```

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

### Add client-side routes in extend.ts

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Adds client-side routes for the forum pages: 'tags' for /tags and 'tag' for /t/:tags, plus a helper to generate tag URLs. Used in js/src/forum/extend.ts.

```typescript
new Extend.Routes()
  .add('tags', '/tags', TagsPage)
  .add('tag', '/t/:tags', IndexPage)
  .helper('tag', (tag) => app.route('tag', { tags: tag.slug() })),
```

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

### Register forum routes in extend.php

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Registers the two forum routes for the Flarum Tags extension: /t/{slug} for a single tag page and /tags for the All Tags page. Used in the extension's extend.php file.

```php
(new Extend\Frontend('forum'))
    ->route('/t/{slug}', 'tag', Content\Tag::class)
    ->route('/tags', 'tags', Content\Tags::class),
```

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

### Create a new Tag with Tag::build()

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-tag-model.md

Use the static build() method to create an unsaved Tag instance with the given attributes. The method coerces is_hidden to bool and returns the new Tag, which must be saved separately with save().

```php
use Flarum\Tags\Tag;

$tag = Tag::build('General', 'general', 'Talk about anything', '#F28326', 'fas fa-comments', false);
$tag->save();
```

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

### Tags content class skeleton

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-content-search.md

Defines the Tags class handling the /tags route. Constructor injects API client, view factory, tag repository, translator, settings, and URL generator. The __invoke method fetches tags and renders the page, while getTagsDocument retrieves the tag data.

```php
class Tags
{
    public function __construct(
        protected Client $api,
        protected Factory $view,
        protected TagRepository $tags,
        protected TranslatorInterface $translator,
        protected SettingsRepositoryInterface $settings,
        protected UrlGenerator $url
    ) {}

    public function __invoke(Document $document, Request $request): Document
    protected function getTagsDocument(Request $request): array
}
```

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

### Deleting event class constructor

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

Constructor for the Deleting event, holding the Tag being deleted and the acting User.

```php
class Deleting
{
    public function __construct(
        public Tag $tag,
        public User $actor
    ) {}
}
```

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

### class TagListState

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

The TagListState class loads and caches tag lists (with includes) into the store. It provides load and query methods to fetch tags from the API and manage cached state.

```APIDOC
## Class: `TagListState`

### Description
Loads and caches tag lists (with includes) into the store. The class provides two methods to fetch tags and manage caching.

### Methods

#### `load(includes: string[] = []): Promise<Tag[]>`

- **Parameters:**
  - `includes` (string[]) - Optional - An array of include strings to load with tags.
- **Returns:** `Promise<Tag[]>`
- **Description:** Returns cached tags if all requested includes already loaded, else calls `query`.

#### `query(includes: string[] = []): Promise<Tag[]>`

- **Parameters:**
  - `includes` (string[]) - Optional - An array of include strings to load with tags.
- **Returns:** `Promise<Tag[]>`
- **Description:** Runs `app.store.find('tags', { include: includes.join(',') })` and records loaded includes.

### Example
```ts
import app from 'flarum/common/app';

app.tagList.load(['parent', 'children']).then((tags) => {
  console.log(tags);
});
```
```

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

### buildPermissionSubquery protected helper

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-tag-model.md

Builds the perm_tags subquery for the scopeWhereHasPermission method.

```php
protected static function buildPermissionSubquery(QueryBuilder $base, bool $isAdmin, bool $hasGlobalPermission, iterable $tagIdsWithPermission): void
```

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

### Utf8SlugDriver class skeleton

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-slug-drivers.md

Shows the class structure of the default Utf8SlugDriver, including its constructor and the three public methods from SlugDriverInterface and BatchSlugDriverInterface. The method bodies are not shown in the source.

```php
class Utf8SlugDriver implements SlugDriverInterface, BatchSlugDriverInterface
{
    public function __construct(
        protected TagRepository $repository
    ) {
    }

    public function toSlug(AbstractModel $instance): string
    public function fromSlug(string $slug, User $actor): AbstractModel
    public function fromSlugs(array $slugs, User $actor): Collection
}
```

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

### TagState method signatures

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-repositories-and-state.md

Method signatures for TagState, including relationships and the composite key override for save queries.

```php
public function tag(): BelongsTo   // belongsTo(Tag::class)
public function user(): BelongsTo  // belongsTo(User::class)
protected function setKeysForSaveQuery($query)
```

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

### Register slug drivers in extend.php

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-slug-drivers.md

Registers the two slug drivers for the Tag model using Extend\ModelUrl. The 'default' driver is Utf8SlugDriver and 'id_with_slug' is IdWithSlugDriver.

```php
(new Extend\ModelUrl(Tag::class))
    ->addSlugDriver('default', Utf8SlugDriver::class)
    ->addSlugDriver('id_with_slug', IdWithSlugDriver::class),
```

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

### Saving event class constructor

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

Constructor for the Saving event, holding the Tag being updated, the acting User, and the request body data array.

```php
class Saving
{
    public function __construct(
        public Tag $tag,
        public User $actor,
        public array $data
    ) {}
}
```

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

### FulltextFilter class skeleton

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-content-search.md

Extends AbstractFulltextFilter to enable full-text search over tags. The constructor injects TagRepository, and the search method constrains the query to tag IDs whose name or slug begins with the search value.

```php
class FulltextFilter extends AbstractFulltextFilter
{
    public function __construct(protected TagRepository $tags) {}
    public function search(SearchState $state, string $value): void
}
```

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

### tagIcon helper: renders tag icon or placeholder

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Renders a tag's icon, or a colored placeholder span when the tag has no icon. The `useColor` setting (default `true`) controls whether the `--color` style is applied; a falsy tag adds the `untagged` class.

```js
export default function tagIcon(tag, attrs = {}, settings = {}) {
  const hasIcon = tag && tag.icon();
  const { useColor = true } = settings;
  // ...
  return hasIcon ? <Icon name={tag.icon()} {...attrs} /> : <span {...attrs} />;
}
```

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

### stateFor method

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-tag-model.md

Returns the TagState for the given user, using the loaded state relation if available, otherwise querying by user_id.

```php
public function stateFor(User $user): TagState
```

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

### POST /api/tags/order

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/endpoints.md

Reorders primary tags and their children. This endpoint is admin-only and returns an empty response on success.

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

### Description
Reorders primary tags and their children. This endpoint is admin-only and returns an empty response on success.

### Method
POST

### Endpoint
/api/tags/order

### Parameters
#### Request Body
- **order** (array) - Required - Ordered list of primary tags
- **order[].id** (number) - Required - Primary tag id
- **order[].children** (number[]) - Optional - Ordered child tag ids

### Request Example
{
  "order": [
    { "id": 1, "children": [5, 6] },
    { "id": 2, "children": [] }
  ]
}

### Response
#### Success Response (204)
Empty response.

#### Error Responses
- **403** - Actor is not an admin (PermissionDeniedException)
- **422** - `order` is missing/null

```

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

### TagSearcher class skeleton

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-content-search.md

Extends AbstractSearcher for the Tag model. The getQuery method returns a query for tags visible to the given actor, selecting all tag columns.

```php
class TagSearcher extends AbstractSearcher
{
    public function getQuery(User $actor): Builder
}
```

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

### tagIcon(tag, attrs = {}, settings = {})

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Renders a tag's icon, or a colored placeholder span when the tag has no icon. Accepts optional attributes and settings to control color usage.

```APIDOC
## tagIcon(tag, attrs = {}, settings = {})

### Description
Renders a tag's icon, or a colored placeholder span when the tag has no icon.

### Parameters
- **tag** (object) - Required - The tag object. If falsy, adds the `untagged` class.
- **attrs** (object) - Optional - Additional HTML attributes to apply to the rendered element.
- **settings** (object) - Optional - Configuration settings.
  - **useColor** (boolean) - Optional - Default `true`. When `false`, skips the `--color` style.

### Returns
- **JSX element** - The rendered icon or placeholder span.

### Example
```tsx
import tagIcon from 'flarum-tags/common/helpers/tagIcon';

const icon = tagIcon(tag, { className: 'Button-icon' });
```
```

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

### TagListState class definition

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Defines the TagListState class with its load and query methods. The load method returns cached tags if all requested includes are already loaded, otherwise it calls query. The query method runs app.store.find('tags', { include: includes.join(',') }) and records the loaded includes.

```typescript
export default class TagListState {
  loadedIncludes?: Set<string>;
  async load(includes: string[] = []): Promise<Tag[]>
  async query(includes: string[] = []): Promise<Tag[]>
}
```

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

### tagLabel(tag, attrs = {})

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-common.md

Renders a single tag label. If `attrs.link` is set, the label becomes a link to the tag route. Applies color classes and child tag styling.

```APIDOC
## tagLabel(tag, attrs = {})

### Description
Renders a single tag label. If `attrs.link` is set, the label becomes a link to the tag route. Applies color classes and child tag styling.

### Parameters
- **tag** (object) - Required - The tag object. If falsy, renders the "deleted tag" text with the `untagged` class.
- **attrs** (object) - Optional - Additional attributes. Extracts `link` property to make the label a link.

### Returns
- **JSX element** - The rendered tag label.

### Example
```tsx
import tagLabel from 'flarum-tags/common/helpers/tagLabel';

const label = tagLabel(tag, { link: true });
```
```

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

### scopeWhereHasPermission method

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-tag-model.md

Restricts the query to tags where the user has the given permission, handling admins, global permissions, and tag-scoped permissions.

```php
public function scopeWhereHasPermission(Builder $query, User $user, string $currPermission): Builder
```

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

### Handle method signature

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-api-resource.md

The handle method signature for the OrderTagsController. It accepts a ServerRequestInterface and returns a ResponseInterface.

```php
public function handle(ServerRequestInterface $request): ResponseInterface
```

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

### forum/extend.ts - Register routes, post type, and model attributes

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-extenders.md

Registers forum routes, the `discussionTagged` post type, and extends the `Discussion` model with `tags()` (hasMany) and `canTag()` attributes.

```typescript
export default [
  ...commonExtend,
  new Extend.Routes()
    .add('tags', '/tags', TagsPage)
    .add('tag', '/t/:tags', IndexPage)
    .helper('tag', (tag) => app.route('tag', { tags: tag.slug() })),
  new Extend.PostTypes().add('discussionTagged', DiscussionTaggedPost),
  new Extend.Model(Discussion)
    .hasMany<Tag>('tags')
    .attribute<boolean>('canTag'),
];
```

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

### DiscussionTaggedPost class signatures

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

Shows the type property and method signatures for the DiscussionTaggedPost class. The type is 'discussionTagged'. The saveAfter method merges with an adjacent same-user post, reply builds a new event post, and buildContent returns an array of old and new tag IDs.

```php
public static string $type = 'discussionTagged';

public function saveAfter(?Post $previous = null): static
public static function reply(int $discussionId, int $userId, array $oldTagIds, array $newTagIds): static
public static function buildContent(array $oldTagIds, array $newTagIds): array
```

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

### CreatePostWhenTagsAreChanged Listener Class

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

The listener class for handling the DiscussionWasTagged event. It is registered using Extend\Event.

```php
class CreatePostWhenTagsAreChanged
{
    public function handle(DiscussionWasTagged $event): void
}
```

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

### admin/extend.tsx - Register admin page, permissions, and settings

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/js-extenders.md

Registers the admin page, two permissions, and four settings entries.

```tsx
export default [
  ...commonExtend,
  new Extend.Admin()
    .page(TagsPage)
    .permission(() => ({ icon: 'fas fa-tag', label, permission: 'discussion.tag' }), 'moderate', 95)
    .permission(() => ({ icon: 'fas fa-tags', label, permission: 'bypassTagCounts' }), 'start', 89)
    .generalIndexItems('settings', () => [
      { id: 'flarum-tags.min_primary_tags', label, help },
      { id: 'flarum-tags.max_primary_tags', label, help },
      { id: 'flarum-tags.min_secondary_tags', label, help },
      { id: 'flarum-tags.max_secondary_tags', label, help },
    ]),
];
```

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

### Content\Tag class definition

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-content-search.md

Defines the Tag content controller for the /t/{slug} route. Injects API client, view factory, tag repository, translator, slug manager, and discussion resource. The __invoke method handles the request, and protected methods getApiDocument and getTagsDocument are declared.

```php
class Tag
{
    public function __construct(
        protected Client $api,
        protected Factory $view,
        protected TagRepository $tags,
        protected TranslatorInterface $translator,
        protected SlugManager $slugger,
        protected DiscussionResource $resource
    ) {}

    public function __invoke(Document $document, Request $request): Document
    protected function getApiDocument(Request $request, array $params): object
    protected function getTagsDocument(Request $request, string $slug): object
}
```

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

### DiscussionWasTagged event class constructor

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-events.md

Constructor for the DiscussionWasTagged event, holding the Discussion, the acting User, and the oldTags array. The oldTags property is annotated with @var Tag[].

```php
class DiscussionWasTagged
{
    public function __construct(
        public Discussion $discussion,
        public User $actor,
        /** @var Tag[] */
        public array $oldTags
    ) {}
}
```

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

### Tag model relations

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-tag-model.md

Defines the relationships for the Tag model: parent, children, last posted discussion/user, discussions, and state.

```php
public function parent(): BelongsTo
public function children(): HasMany            // hasMany(self, 'parent_id')
public function lastPostedDiscussion(): BelongsTo // FK: last_posted_discussion_id
public function lastPostedUser(): BelongsTo       // FK: last_posted_user_id
public function discussions(): BelongsToMany      // pivot: discussion_tag
public function state(): HasOne                   // -> TagState
```

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

### TagResource class definition

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-api-resource.md

Defines the TagResource class extending AbstractDatabaseResource. Includes constructor injection of SlugManager and method signatures for type, model, scope, find, endpoints, fields, and lifecycle hooks.

```php
class TagResource extends AbstractDatabaseResource
{
    public function __construct(protected SlugManager $slugManager) {}

    public function type(): string                     // 'tags'
    public function model(): string                    // Tag::class
    public function scope(Builder $query, Context $context): void
    public function find(string $id, Context $context): ?object
    public function endpoints(): array
    public function fields(): array
    public function creating(object $model, Context $context): ?object
    public function saving(object $model, Context $context): ?object
    public function deleting(object $model, Context $context): void
}
```

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

### SelectTagsSettingComponentOptions interface

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/types.md

Defines the options for the 'flarum-tags.select-tags' custom field type. The 'type' field is required and must be the literal string 'flarum-tags.select-tags'. The optional 'options' field passes extra attrs to the TagSelectionModal.

```typescript
export interface SelectTagsSettingComponentOptions extends CommonFieldOptions {
  type: 'flarum-tags.select-tags';
  options?: ITagSelectionModalAttrs;
}
```

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

### TagFilter class skeleton

Source: https://github.com/flarum/tags/blob/2.x/_autodocs/api-reference/php-content-search.md

Implements FilterInterface for filtering discussion searches by tag slug(s). Supports comma-separated slugs, 'untagged', negation, and OR groups. Resolves slugs to IDs via the active slug driver, with bulk resolution or per-slug fallback.

```php
class TagFilter implements FilterInterface
{
    use ValidateFilterTrait;
    public function __construct(protected SlugManager $slugManager) {}

    public function getFilterKey(): string            // 'tag'
    public function filter(SearchState $state, string|array $value, bool $negate): void
    protected function constrain(Builder $query, string|array $rawSlugs, bool $negate, User $actor): void
    protected function resolveSlugs(array $slugs, User $actor): Collection
}
```
Tokens:
Raw