Flarum Documentation

https://docs.flarum.org/2.x/extend
Admin
Flarum is a highly extensible open-source forum software, providing a flexible framework with rich...
Tokens:107,855
Snippets:1,054
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Installing and Running Development Build

Source: https://docs.flarum.org/2.x/extend/frontend

Commands to install npm dependencies and start the development transpiler, which watches for source file changes and recompiles JavaScript.

```bash
npm install
npm run dev
```

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

### Installing an Extension via Composer

Source: https://docs.flarum.org/2.x/extend/distribution

Users can install your extension using the composer require command with the package name.

```bash
composer require vendor/package
```

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

### Integration Test Case Setup

Source: https://docs.flarum.org/2.x/extend/testing

Demonstrates how to set up a Flarum integration test case using the TestCase class. It shows overriding settings, enabling extensions, preparing the database with custom data, and testing extenders. Ensure all setup is done before the Flarum app boots.

```php
<?php  

/*  
 * This file is part of Flarum.  
 *  
 * For detailed copyright and license information, please view the  
 * LICENSE file that was distributed with this source code.  
 */  

namespace CoolExtension\Tests\integration;  

use Flarum\Testing\integration\RetrievesAuthorizedUsers;  
use Flarum\Testing\integration\TestCase;  
use PHPUnit\Framework\Attributes\Test;  

class SomeTest extends TestCase  
{
    use RetrievesAuthorizedUsers;  

    public function setUp(): void  
    {
        parent::setUp();  

        $this->setting('my.custom.setting', true);  

        // Let's assume our extension depends on tags.  
        // Note that tags will need to be in your extension's composer.json's `require-dev`.  
        // Also, make sure you include the ID of the extension currently being tested, unless you're  
        // testing the baseline without your extension.  
        $this->extension('flarum-tags', 'my-cool-extension');  

        // Note that this input isn't validated: make sure you're populating with valid, representative data.  
        $this->prepareDatabase([
            'users' => [
                $this->normalUser() // Available for convenience.  
            ],
            'discussions' => [
                ['id' => 1, 'title' => 'some title', 'created_at' => Carbon::now(), 'last_posted_at' => Carbon::now(), 'user_id' => 1, 'first_post_id' => 1, 'comment_count' => 1]
            ],
            'posts' => [
                ['id' => 1, 'number' => 1, 'discussion_id' => 1, 'created_at' => Carbon::now(), 'user_id' => 1, 'type' => 'comment', 'content' => '<t><p>something</p></t>']
            ]
        ]);  

        // Most test cases won't need to test extenders, but if you want to, you can.  
        $this->extend((new CoolExtensionExtender)->doSomething('hello world'));  
    }

    #[Test]
    public function some_phpunit_test_case()
    {
        // ...
    }

    // ...
}

```

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

### Define Forum Route with GET Method

Source: https://docs.flarum.org/2.x/extend/routes

Use the Routes extender to define a GET route for the 'forum' collection. This example registers a '/hello-world' path handled by the HelloWorldController.

```php
<?php  

use Flarum\Extend;
use Acme\HelloWorld\HelloWorldController;  

return [  
    (new Extend\Routes('forum'))  
        ->get('/hello-world', 'acme.hello-world', HelloWorldController::class)  
];  
```

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

### Install Flarum Testing Package

Source: https://docs.flarum.org/2.x/extend/testing

Install the flarum/testing package as a development dependency using Composer.

```bash
composer require --dev flarum/testing:^2.0
```

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

### Basic Translation Key Example

Source: https://docs.flarum.org/2.x/extend/i18n

Demonstrates the basic format for a translation key and its corresponding text in a locale file.

```yaml
sample_key: This is a sample translation.  
```

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

### Verify Flarum CLI Installation

Source: https://docs.flarum.org/2.x/extend/cli

Confirm the installation and check the version of each Flarum CLI instance by running the `flarum info` command with their respective aliases.

```bash
fl1 flarum info
```

```bash
fl2 flarum info
```

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

### Integration Test Setup Script

Source: https://docs.flarum.org/2.x/extend/testing

This script is executed to set up the testing database and file structure for integration tests.

```php
<?php
  
use Flarum\Testing\integration\Setup\SetupScript;  
  
require __DIR__.'/../../vendor/autoload.php';  
  
$setup = new SetupScript();  
  
$setup->run();  
```

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

### Custom Post Throttler Example

Source: https://docs.flarum.org/2.x/extend/api-throttling

This example demonstrates a custom throttler for post creation routes. It bypasses throttling if the user has the 'postWithoutThrottle' permission. Otherwise, it checks if a post was created by the user within the last 10 seconds.

```php
use DateTime;

use Flarum\Http\RequestUtil;

use Flarum\Post\Post;

function ($request) {
    if (! in_array($request->getAttribute('routeName'), ['discussions.create', 'posts.create'])) {
        return;
    }

    $actor = RequestUtil::getActor($request);

    if ($actor->can('postWithoutThrottle')) {
        return false;
    }

    if (Post::where('user_id', $actor->id)->where('created_at', '>=', new DateTime('-10 seconds'))->exists()) {
        return true;
    }
};
```

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

### Install Flarum CLI for Frontend Testing Infrastructure

Source: https://docs.flarum.org/2.x/extend/testing

Use the Flarum CLI to automatically set up frontend testing infrastructure. This command initializes the necessary configurations.

```bash
$ flarum-cli infra frontendTesting  
```

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

### Install Multiple Flarum CLI Versions

Source: https://docs.flarum.org/2.x/extend/cli

Install specific versions of the Flarum CLI globally using npm, aliasing them for easy access. Use `--force` if necessary.

```bash
npm install -g fl1@npm:@flarum/cli@2 --force
```

```bash
npm install -g fl2@npm:@flarum/cli@3 --force
```

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

### Flarum Extension Initializer Example

Source: https://docs.flarum.org/2.x/extend/frontend

Defines an extension's entry point using an initializer, which runs after the core has booted. This is where your main extension logic is typically placed.

```javascript
import { extend, override } from 'flarum/common/extend';

// We provide our extension code in the form of an "initializer".
// This is a callback that will run after the core has booted.
app.initializers.add('acme-flarum-hello-world', function(app) {
  // Your Extension Code Here
  console.log("EXTENSION NAME is working!");
});

```

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

### Example LabelResource API Definition

Source: https://docs.flarum.org/2.x/extend/api

This example demonstrates how to define a `LabelResource` class, including its type, model, scope, endpoints, and fields.

```APIDOC
## LabelResource Example

This example shows a `LabelResource` class that defines API endpoints and fields for a `Label` model.

### Class Definition

```php
namespace Acme\Api;

use Acme\Label;
use Flarum\Api\Context;
use Flarum\Api\Endpoint;
use Flarum\Api\Resource\AbstractDatabaseResource;
use Flarum\Api\Schema;

/** @extends AbstractDatabaseResource<Label> */
class LabelResource extends AbstractDatabaseResource
{
    public function type(): string
    {
        return 'labels';
    }

    public function model(): string
    {
        return Label::class;
    }

    public function scope(Builder $query, Context $context): void
    {
        $query->whereVisibleTo($context->getActor());
    }

    public function endpoints(): array
    {
        return [
            Endpoint\Show::make(),
            Endpoint\Create::make()
                ->authenticated()
                ->can('createLabel'),
            Endpoint\Update::make()
                ->authenticated()
                ->can('edit'),
            Endpoint\Delete::make()
                ->authenticated()
                ->can('delete'),
            Endpoint\Index::make()
                ->defaultInclude(['parent'])
        ];
    }

    /*
     * This is only for endpoint processing and serialization.
     * You still have to create a database migration to add the table/columns.
     */
    public function fields(): array
    {
        return [
            Schema\Str::make('name')
                ->requiredOnCreate()
                ->writable(),
            Schema\Str::make('description')
                ->writable()
                ->maxLength(700)
                ->nullable(),
            Schema\Str::make('slug')
                ->requiredOnCreate()
                ->writable()
                ->unique('labels', 'slug', true)
                ->regex('/^[^\/\\ ]*$/i'),
            Schema\Str::make('color')
                ->writable()
                ->nullable()
                ->rule('hex_color'),
            Schema\Str::make('icon')
                ->writable()
                ->nullable(),
            Schema\Boolean::make('isActive')
                ->writable(),
            Schema\DateTime::make('createdAt'),
            Schema\Boolean::make('canAddToDiscussion')
                ->get(fn (Tag $tag, FlarumContext $context) => $context->getActor()->can('addToDiscussion', $tag)),

            Schema\Relationship\ToOne::make('user')
                ->type('users')
                ->includable(),
            Schema\Relationship\ToOne::make('parent')
                ->type('labels')
                ->includable(),
            Schema\Relationship\ToMany::make('children')
                ->type('labels')
                ->includable()
        ];
    }

    public function sorts(): array
    {
        return [
            SortColumn::make('createdAt')
        ];
    }

}
```
```

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

### Create Post Programmatically

Source: https://docs.flarum.org/2.x/extend/api

This example demonstrates how to programmatically create the first post of a discussion using the JsonApi object and a request context.

```APIDOC
## Programmatic Post Creation

### Description
This example shows how to internally execute the logic for creating a post, similar to how Flarum creates the first post of a discussion.

### Method
Internal API Call (via `JsonApi` object)

### Endpoint
`create` endpoint for `PostResource`

### Parameters
#### Request Body
- **data** (object) - Required - The payload for the post creation.
  - **attributes** (object) - Required - Attributes of the post.
    - **content** (string) - Required - The content of the post.
  - **relationships** (object) - Required - Relationships for the post.
    - **discussion** (object) - Required - The discussion the post belongs to.
      - **data** (object) - Required - Discussion data.
        - **type** (string) - Required - Type of the relationship (e.g., 'discussions').
        - **id** (string) - Required - ID of the discussion.

#### Options
- **isFirstPost** (boolean) - Optional - Flag to indicate if this is the first post.

### Request Example
```json
{
  "data": {
    "attributes": {
      "content": "Post content here"
    },
    "relationships": {
      "discussion": {
        "data": {
          "type": "discussions",
          "id": "1"
        }
      }
    }
  }
}
```

### Response
#### Success Response
Returns the created `Post` object.
```

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

### Install Flarum CLI for Flarum 2.x

Source: https://docs.flarum.org/2.x/extend/update-2_0

Install version 3 of the Flarum CLI globally. This version is specifically compatible with Flarum v2.x.

```bash
npm install -g @flarum/cli@3
```

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

### Install Local Flarum Extension with Composer

Source: https://docs.flarum.org/2.x/extend/start

Installs a locally developed Flarum extension into your Flarum installation using Composer. Ensure the extension's `composer.json` is correctly configured and the package is in a location Composer can access.

```bash
composer require acme/flarum-hello-world *@dev
```

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

### Create Frontend Model with Flarum CLI

Source: https://docs.flarum.org/2.x/extend/models

Use this command to automatically generate a frontend model using the Flarum CLI. Ensure the CLI is installed and configured.

```bash
$ flarum-cli make frontend model  
```

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

### Create Backend Model with Flarum CLI

Source: https://docs.flarum.org/2.x/extend/models

Use this command to automatically generate a backend model using the Flarum CLI. Ensure the CLI is installed and configured.

```bash
$ flarum-cli make backend model  
```

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

### Register Custom Storage Driver

Source: https://docs.flarum.org/2.x/extend/filesystem

Implement the `Flarum\Filesystem\DriverInterface` and register it using the `Filesystem` extender. This example registers an 'aws-with-cdn' driver.

```php
use Flarum\Extend;


return [
    (new Extend\Filesystem)
        ->driver('aws-with-cdn', AwsWithCdnDriver::class);


```

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

### PHPUnit Unit Test Configuration

Source: https://docs.flarum.org/2.x/extend/testing

Example PHPUnit configuration file for unit tests. This configuration can be tweaked as needed.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../vendor/phpunit/phpunit/phpunit.xsd"
    backupGlobals="false"
    backupStaticProperties="false"
    cacheDirectory=".phpunit.cache"
    colors="true"
    processIsolation="false"
    stopOnFailure="false">
  
    <testsuites>
        <testsuite name="Flarum Unit Tests">
            <directory suffix="Test.php">./unit</directory>
        </testsuite>
    </testsuites>
</phpunit>
```

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

### Register Admin Page, Settings, and Permissions

Source: https://docs.flarum.org/2.x/extend/admin

A complete `admin/extend.ts` example demonstrating how to register a custom admin page, a boolean setting, and a permission. Settings and permissions are registered using translator keys.

```typescript
import Extend from 'flarum/common/extenders';
import app from 'flarum/admin/app';
import SettingsPage from './components/SettingsPage';

export default [
  new Extend.Admin()
    .page(SettingsPage)
    .setting(() => ({
      setting: 'acme-interstellar.coordinates',
      label: app.translator.trans('acme-interstellar.admin.coordinates_label', {}, true),
      type: 'boolean',
    }))
    .permission(
      () => ({
        icon: 'fas fa-rocket',
        label: app.translator.trans('acme-interstellar.admin.permissions.launch_label'),
        permission: 'acme-interstellar.launch',
      }),
      'moderate',
      90
    ),
];

```

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

### PHPUnit Integration Test Configuration

Source: https://docs.flarum.org/2.x/extend/testing

Example PHPUnit configuration file for integration tests. Ensure backupGlobals, backupStaticProperties, and processIsolation remain unchanged.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../vendor/phpunit/phpunit/phpunit.xsd"
    backupGlobals="false"
    backupStaticProperties="false"
    cacheDirectory=".phpunit.cache"
    colors="true"
    processIsolation="true"
    stopOnFailure="false">
  
    <testsuites>
        <testsuite name="Flarum Integration Tests">
            <directory suffix="Test.php">./integration</directory>
        </testsuite>
    </testsuites>
</phpunit>
```

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

### Create Group Programmatically

Source: https://docs.flarum.org/2.x/extend/api

This example shows how to programmatically create a new user group using the JsonApi object when the request context is not available.

```APIDOC
## Programmatic Group Creation

### Description
This example demonstrates how to programmatically create a user group using the `JsonApi` object when direct access to the `Flarum\Api\Context` object is not available.

### Method
Internal API Call (via `JsonApi` object)

### Endpoint
`create` endpoint for `GroupResource`

### Parameters
#### Request Body
- **data** (object) - Required - The payload for the group creation.
  - **attributes** (object) - Required - Attributes of the group.
    - **nameSingular** (string) - Required - The singular name of the group.
    - **namePlural** (string) - Required - The plural name of the group.
    - **color** (string) - Optional - The color for the group (e.g., '#000000').
    - **icon** (string) - Optional - The icon for the group (e.g., 'fas fa-crown').

#### Options
- **actor** (User) - Optional - The user performing the action.

### Request Example
```json
{
  "data": {
    "attributes": {
      "nameSingular": "test group",
      "namePlural": "test groups",
      "color": "#000000",
      "icon": "fas fa-crown"
    }
  }
}
```

### Response
#### Success Response
Returns the created `Group` object.
```

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

### Flarum Frontend Test File Structure

Source: https://docs.flarum.org/2.x/extend/testing

Example file structure for organizing frontend tests within a Flarum extension. It includes directories for unit and integration tests.

```text
js
├── dist
├── src
├── tests
│   ├── unit
│   │   └── functionTest.test.js
│   ├── integration
│   │   └── componentTest.test.js
├── package.json
├── tsconfig.json
├── tsconfig.test.json
├── jest.config.cjs
└── webpack.config.cjs  
```

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

### Customizing Getters and Setters

Source: https://docs.flarum.org/2.x/extend/api

Shows how to use `get` and `set` methods to customize how attribute values are read from and written to the model.

```APIDOC
## Customizing Getters and Setters

### Description
This section explains how to override the default behavior of reading and writing model attributes. The `get` method allows custom logic for retrieving a value, and the `set` method allows custom logic for persisting a value, both accepting closures.

### Code Example
```php
use Flarum\Api\Context;
use Flarum\Api\Schema;

public function fields(): array
{
    return [
        Schema\Str::make('name')
            ->get(fn (Label $label) => strtoupper($label->name))
            ->set(function (Label $label, string $value, Context $context) {
                $label->name = strtolower($value);
            }),
    ];
}
```
```

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

### Add Fields Before and After Existing Fields

Source: https://docs.flarum.org/2.x/extend/api

This example shows how to add custom fields to a resource, specifically before and after an existing field like 'email'. It utilizes the fieldsBefore and fieldsAfter methods.

```php
use Flarum\Api\Resource;
use Flarum\Api\Schema;
use Flarum\Extend;

return [
    (new Extend\ApiResource(Resource\UserResource::class))
        ->fields(fn () => [
            Schema\Str::make('customField'),
            Schema\Relationship\ToOne::make('customRelation')
                ->type('customRelationType'),
        ])
        ->fieldsBefore('email', fn () => [
            Schema\Str::make('customFieldBeforeEmail'),
        ])
        ->fieldsAfter('email', fn () => [
            Schema\Str::make('customFieldAfterEmail'),
        ]),
]
```

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

### Extend Component Methods with Haptics

Source: https://docs.flarum.org/2.x/extend/haptic-feedback

Add haptic feedback to a component method by extending its prototype using `extend()`. This example shows triggering haptics when a post is expanded.

```javascript
import { extend } from 'flarum/common/extend';
import haptic from 'flarum/common/utils/haptic';
import CommentPost from 'flarum/forum/components/CommentPost';

app.initializers.add('my-extension', () => {
  // Example: haptic when user expands a collapsed post
  extend(CommentPost.prototype, 'toggleContent', function () {
    haptic('light');
  });
});
```

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

### Reactions Extension Haptic Example

Source: https://docs.flarum.org/2.x/extend/haptic-feedback

Integrate haptic feedback into a reactions extension, mapping different reaction types to specific haptic presets. The `haptic` function is called with the determined preset.

```javascript
import haptic from 'flarum/common/utils/haptic';

// Map reaction types to haptic presets
const reactionHaptics = {
  like: 'success',
  love: 'success',
  haha: 'light',
  angry: 'heavy',
  sad: 'medium',
};

function onReactionSelected(reactionType, post) {
  const preset = reactionHaptics[reactionType] ?? 'light';
  haptic(preset);
  
  post.save({ reaction: reactionType });
}
```

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

### Install Jest Config Dev Dependency

Source: https://docs.flarum.org/2.x/extend/testing

Install the Jest configuration as a development dependency using Yarn. This package provides the necessary setup for Jest.

```bash
$ yarn add --dev @flarum/jest-config  
```

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

### Listening to ApplicationBooted Event

Source: https://docs.flarum.org/2.x/extend/backend-events

Use the `Extend\Event` class to register a listener for the `ApplicationBooted` event. This is the earliest reliable point to perform setup after all extensions are loaded but before any HTTP request is handled. Be mindful that this event fires on every request; implement safeguards for one-time operations.

```php
use Flarum\Extend;
use Flarum\Foundation\Event\ApplicationBooted;

return [
    (new Extend\Event())
        ->listen(ApplicationBooted::class, function () {
            // Everything is booted. Safe to resolve any binding or read any setting.
        }),
];
```

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

### Flarum 1.x Draft Count Accessor

Source: https://docs.flarum.org/2.x/extend/update-2_0-api

Example of a `get` accessor in Flarum 1.x for retrieving a count, which is less efficient than Flarum 2.x's `countRelation`.

```php
->get(fn (User $user, Context $context) => Draft::where('user_id', $context->getActor()->id)->count()
```

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

### Example Model Policy for Flarum Tags

Source: https://docs.flarum.org/2.x/extend/authorization

This policy defines access control for starting and adding tags to discussions based on tag restrictions and user permissions.

```php
<?php  

namespace Flarum\Tags\Access;  

use Flarum\Tags\Tag;  
use Flarum\User\Access\AbstractPolicy;  
use Flarum\User\User;  

class TagPolicy extends AbstractPolicy  
{
    /**  
     * @param User $actor  
     * @param Tag $tag  
     * @return bool|null  
     */  
    public function startDiscussion(User $actor, Tag $tag)
    {
        if ($tag->is_restricted) {
            return $actor->hasPermission('tag'.$tag->id.'.startDiscussion') ? $this->allow() : $this->deny();
        }
    }

    /**  
     * @param User $actor  
     * @param Tag $tag  
     * @return bool|null  
     */  
    public function addToDiscussion(User $actor, Tag $tag)
    {
        return $this->startDiscussion($actor, $tag);
    }

}

```

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

### Example Global Policy for Flarum Tags

Source: https://docs.flarum.org/2.x/extend/authorization

This global policy checks if a user has sufficient primary and secondary tags to perform actions like viewing the forum or starting a discussion, based on site settings.

```php
<?php  

namespace Flarum\Tags\Access;  

use Flarum\Settings\SettingsRepositoryInterface;  
use Flarum\Tags\Tag;  
use Flarum\User\Access\AbstractPolicy;  
use Flarum\User\User;  

class GlobalPolicy extends AbstractPolicy  
{
    /**  
     * @var SettingsRepositoryInterface  
     */  
    protected $settings;

    public function __construct(SettingsRepositoryInterface $settings)
    {
        $this->settings = $settings;
    }

    /**  
     * @param Flarum\User\User $actor  
     * @param string $ability  
     * @return bool|void  
     */  
    public function can(User $actor, string $ability)
    {
        if (in_array($ability, ['viewForum', 'startDiscussion'])) {
            $enoughPrimary = count(Tag::getIdsWhereCan($actor, $ability, true, false)) >= $this->settings->get('min_primary_tags');
            $enoughSecondary = count(Tag::getIdsWhereCan($actor, $ability, false, true)) >= $this->settings->get('min_secondary_tags');

            if ($enoughPrimary && $enoughSecondary) {
                return $this->allow();
            } else {
                return $this->deny();
            }
        }
    }

}

```

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

### Add, Remove, Insert, and Replace Middleware

Source: https://docs.flarum.org/2.x/extend/middleware

Demonstrates how to add middleware to different stacks, and how to remove, insert before, insert after, or replace existing middleware. Remember that middleware order matters.

```php
use Flarum\Extend;
use Flarum\Http\Middleware\CheckCsrfToken;

return [
    // Add middleware to forum frontend
    (new Extend\Middleware('forum'))->add(YourMiddleware::class),

    // Admin frontend
    (new Extend\Middleware('admin'))->add(YourMiddleware::class),

    // API frontend
    (new Extend\Middleware('api'))->add(YourMiddleware::class),

    (new Extend\Middleware('forum'))
        // remove a middleware (e.g. remove CSRF token check 😱)
        ->remove(CheckCsrfToken::class)
        // insert before another middleware (e.g. before a CSRF token check)
        ->insertBefore(CheckCsrfToken::class, YourMiddleware::class)
        // insert after another middleware (e.g. after a CSRF token check)
        ->insertAfter(CheckCsrfToken::class, YourMiddleware::class)
        // replace a middleware (e.g. replace the CSRF check with your own implementation)
        ->replace(CheckCsrfToken::class, YourMiddleware::class)
];

```

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

### Initialize Extension Scaffolding with Flarum CLI

Source: https://docs.flarum.org/2.x/extend/start

Use the Flarum CLI to automatically generate the basic file structure and configuration for a new extension.

```bash
$ flarum-cli init
```

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

### Tagging a Release with Git

Source: https://docs.flarum.org/2.x/extend/distribution

Tag your first version of the extension and push it to the remote repository.

```bash
git tag v0.1.0
```

```bash
git push && git push --tags
```

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

### Running Production Build

Source: https://docs.flarum.org/2.x/extend/frontend

Command to build the extension's JavaScript in production mode, optimizing for size and speed.

```bash
npm run build
```

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

### Create a Custom Console Command in PHP

Source: https://docs.flarum.org/2.x/extend/console

Define a new console command by extending `Flarum\Console\AbstractCommand` and implementing the `configure` and `fire` methods. The `configure` method sets the command name and description, while `fire` contains the command's logic.

```php
use Flarum\Console\AbstractCommand;

class YourCommand extends AbstractCommand {
  protected function configure()
  {
      $this
          ->setName('YOUR COMMAND NAME')
          ->setDescription('YOUR COMMAND DESCRIPTION');
  }

  protected function fire(): int
  {
    // Your logic here!

    return 0;
  }

}
```

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

### Payload Example (1.x)

Source: https://docs.flarum.org/2.x/extend/update-2_0-api

An example of the JSON payload structure sent from the frontend in Flarum 1.x when saving vote data. Note that the 'attributes' array format is not compatible with Flarum 2.0.

```json
{  

  "data": {  

    "type": "posts",  

    "attributes": [  

      true,  

      false,  

      "vote"  

    ],  

    "id": "199067"  

  }  

}
```

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

### Custom Flarum Component Example

Source: https://docs.flarum.org/2.x/extend/frontend

Extend `flarum/common/Component` to create custom Flarum components. Remember to call `super` in lifecycle methods. This example demonstrates a simple counter component with an incrementing button.

```javascript
import Component from 'flarum/common/Component';

class Counter extends Component {
  oninit(vnode) {
    super.oninit(vnode);

    this.count = 0;
  }
  
  view() {
    return (
      <div>
        Count: {this.count}
        <button onclick={e => this.count++}>
          {this.attrs.buttonLabel}
        </button>
      </div>
    );
  }
  
  oncreate(vnode) {
    super.oncreate(vnode);

    // We aren't actually doing anything here, but this would
    // be a good place to attach event handlers, initialize libraries
    // like sortable, or make other DOM modifications.
    $element = this.$();
    $button = this.$('button');
  }

}

m.mount(document.body, <MyComponent buttonLabel="Increment" />);

```

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

### Custom Getter and Setter for Fields

Source: https://docs.flarum.org/2.x/extend/api

Customizes how a field's value is read (get) and written (set). The 'get' method transforms the value to uppercase, and the 'set' method converts it to lowercase before saving.

```PHP
use Flarum\Api\Context;
use Flarum\Api\Schema;

public function fields(): array
{
    return [
        Schema\Str::make('name')
            ->get(fn (Label $label) => strtoupper($label->name))
            ->set(function (Label $label, string $value, Context $context) {
                $label->name = strtolower($value);
            }),
    ];
}
```

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

### Showing, Creating, Updating, and Deleting Resources

Source: https://docs.flarum.org/2.x/extend/api

The `Show`, `Create`, `Update`, and `Delete` endpoints allow for retrieving, creating, modifying, and removing single model instances respectively. These can be used directly if the resource extends `AbstractDatabaseResource`, or by implementing specific interfaces if extending `AbstractResource`.

```APIDOC
## Showing, Creating, Updating, and Deleting Resources

The `Show`, `Create`, `Update`, and `Delete` endpoints are used to get, create, update, and delete a single model instance, respectively.

If your resource class extends the `AbstractDatabaseResource` class, you can directly use the endpoints.

```php
use Flarum\Api\Endpoint;

public function endpoints(): array
{
    return [
        Endpoint\Show::make(),
        Endpoint\Create::make(),
        Endpoint\Update::make(),
        Endpoint\Delete::make(),
    ];
}
```

If your resource class extends the `AbstractResource` class, you must implement the appropriate interfaces.

```php
use Flarum\Api\Resource\Contracts::
    Countable,
    Creatable,
    Deletable,
    Findable,
    Listable,
    Paginatable,
    Updatable
;

class CustomResource extends AbstractResource implements
    Findable, // Show endpoint
    Listable, // Index endpoint
    Countable, // Optional for Index endpoints total result count
    Paginatable, // Optional if paginating Index endpoint results
    Creatable, // Create endpoint
    Updatable, // Update endpoint
    Deletable // Delete endpoint
{
    // ...
}
```
```

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

### Individual Flarum CLI Version Check

Source: https://docs.flarum.org/2.x/extend/cli

Check the version of specific Flarum CLI installations using their individual aliases (`fl1` for v2, `fl2` for v3). This allows for precise verification of each installed version.

```bash
$ fl1 flarum info

Flarum version: 1.x
CLI version: 2.0.2
```

```bash
$ fl2 flarum info

Flarum version: 2.x
CLI version: 3.0.1
```

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

### Switch Between Flarum CLI Versions

Source: https://docs.flarum.org/2.x/extend/cli

Use the `fl flarum change` command to install the counterpart version of the Flarum CLI and switch between v2 and v3. This command also sets the default `fl` binary to the newly installed version.

```bash
fl flarum change
```

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

### Import and Use Haptic Utility

Source: https://docs.flarum.org/2.x/extend/haptic-feedback

Import the haptic utility from 'flarum/common/utils/haptic' and call it to trigger default or named presets. Ensure calls are within a synchronous user gesture context.

```javascript
import haptic from 'flarum/common/utils/haptic';

// Trigger the default preset (light)
haptic();

// Trigger a named preset
haptic('success');
```

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

### Flarum API Resource Example

Source: https://docs.flarum.org/2.x/extend/api

An example of a Flarum API Resource for a 'Label' model. It defines the resource type, associated model, visibility scoping, available endpoints (Show, Create, Update, Delete, Index), and detailed field schemas with validation rules and relationships.

```php
namespace Acme\Api;  
  
use Acme\Label;  
use Flarum\Api\Context;  
use Flarum\Api\Endpoint;  
use Flarum\Api\Resource\AbstractDatabaseResource;  
use Flarum\Api\Schema;  
  
/** @extends AbstractDatabaseResource<Label> */  
class LabelResource extends AbstractDatabaseResource  
{  
    public function type(): string  
    {  
        return 'labels';  
    }  
  
    public function model(): string  
    {  
        return Label::class;  
    }  
  
    public function scope(Builder $query, Context $context): void  
    {  
        $query->whereVisibleTo($context->getActor());  
    }  
  
    public function endpoints(): array  
    {  
        return [  
            Endpoint\Show::make(),  
            Endpoint\Create::make()  
                ->authenticated()  
                ->can('createLabel'),  
            Endpoint\Update::make()  
                ->authenticated()  
                ->can('edit'),  
            Endpoint\Delete::make()  
                ->authenticated()  
                ->can('delete'),  
            Endpoint\Index::make()  
                ->defaultInclude(['parent']),  
        ];  
    }  
  
    /*  
     * This is only for endpoint processing and serialization.  
     * You still have to create a database migration to add the table/columns.  
     */  
    public function fields(): array  
    {  
        return [  
            Schema\Str::make('name')  
                ->requiredOnCreate()  
                ->writable(),  
            Schema\Str::make('description')  
                ->writable()  
                ->maxLength(700)  
                ->nullable(),  
            Schema\Str::make('slug')  
                ->requiredOnCreate()  
                ->writable()  
                ->unique('labels', 'slug', true)  
                ->regex('/^[^\/\\ ]*$/i'),  
            Schema\Str::make('color')  
                ->writable()  
                ->nullable()  
                ->rule('hex_color'),  
            Schema\Str::make('icon')  
                ->writable()  
                ->nullable(),  
            Schema\Boolean::make('isActive')  
                ->writable(),  
            Schema\DateTime::make('createdAt'),  
            Schema\Boolean::make('canAddToDiscussion')  
                ->get(fn (Tag $tag, FlarumContext $context) => $context->getActor()->can('addToDiscussion', $tag)),  
  
            Schema\Relationship\ToOne::make('user')  
                ->type('users')  
                ->includable(),  
            Schema\Relationship\ToOne::make('parent')  
                ->type('labels')  
                ->includable(),  
            Schema\Relationship\ToMany::make('children')  
                ->type('labels')  
                ->includable(),  
        ];  
    }  
      
    public function sorts(): array  
    {  
        return [  
            SortColumn::make('createdAt'),  
        ];  
    }  

}

```

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

### Require Flarum PHPStan Package

Source: https://docs.flarum.org/2.x/extend/static-code-analysis

Install the Flarum PHPStan package as a development dependency in your extension.

```bash
composer require --dev flarum/phpstan:^2.0
```

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

### Update Flysystem Adapter Initialization

Source: https://docs.flarum.org/2.x/extend/update-2_0

When using Flysystem directly, the `FilesystemAdapter` constructor now requires the adapter instance as the second argument. Use `LocalFilesystemAdapter` instead of the removed `Local` adapter.

```PHP
// Before
new FilesystemAdapter(new Filesystem(new LocalAdapter($path)));

// After
$adapter = new LocalFilesystemAdapter($path);
new FilesystemAdapter(new Filesystem($adapter), $adapter);
```

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

### Find Discussions with Unread Gambit

Source: https://docs.flarum.org/2.x/extend/search

Example of using the `is:unread` gambit to find unread discussions via the store.

```javascript
app.store.find('discussions', { q: 'is:unread' });
```

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

### Run Static Analysis

Source: https://docs.flarum.org/2.x/extend/static-code-analysis

Execute the static analysis for your extension using the defined composer script.

```bash
composer analyse:phpstan
```

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

### Configure Frontend GitHub Actions Workflow

Source: https://docs.flarum.org/2.x/extend/github-actions

Set up the `.github/workflows/frontend.yml` file for frontend tasks like bundling, formatting, and testing. This workflow reuses a predefined workflow from the Flarum framework and supports various JavaScript package managers.

```yaml
name: Frontend  
  
on: [workflow_dispatch, push, pull_request]  
  
jobs:
  run:
    uses: flarum/framework/.github/workflows/REUSABLE_frontend.yml@main
    with:
      enable_bundlewatch: false
      enable_prettier: true
      enable_typescript: false

      frontend_directory: ./js
      backend_directory: .
      js_package_manager: yarn
      main_git_branch: main

    secrets:
      bundlewatch_github_token: ${{ secrets.BUNDLEWATCH_GITHUB_TOKEN }}
```

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

### Add Endpoints Before, After, and All

Source: https://docs.flarum.org/2.x/extend/api

This snippet demonstrates adding custom endpoints to a resource at various positions: before a specific endpoint ('show'), after a specific endpoint ('show'), and before all existing endpoints. It uses the endpointsBefore, endpointsAfter, and endpointsBeforeAll methods.

```php
use Flarum\Api\Context;
use Flarum\Api\Resource;
use Flarum\Api\Endpoint;
use Flarum\Extend;

return [
    (new Extend\ApiResource(Resource\UserResource::class))
        ->endpoints(fn () => [
            Endpoint\Endpoint::make('custom')
                ->route('GET', '/{id}/custom')
                ->action(function (Context $context) {
                    $user = $context->model;
                      
                    // logic...
                }),
        ])
        ->endpointsBefore('show', fn () => [
            Endpoint\Endpoint::make('customBeforeShow')
                ->route('GET', '/customBeforeShow')
                ->action(function (Context $context) {
                    // logic ...
                }),
        ])
        ->endpointsAfter('show', fn () => [
            Endpoint\Endpoint::make('customAfterShow')
                ->route('GET', '/customAfterShow')
                ->action(function (Context $context) {
                    // logic ...
                }),
        ])
        ->endpointsBeforeAll(fn () => [
            Endpoint\Endpoint::make('customBeforeAll')
                ->route('GET', '/customBeforeAll')
                ->action(function (Context $context) {
                    // logic ...
                }),
        ])
];
```

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

### Manually Create Model Instance Using Factory

Source: https://docs.flarum.org/2.x/extend/testing

After the application has booted, you can manually create model instances using their factories. This is typically done within test methods.

```php
<?php

namespace CoolExtension\Tests\integration;

use Flarum\Testing\integration\RetrievesAuthorizedUsers;
use Flarum\Testing\integration\TestCase;
use Flarum\User\User;
use PHPUnit\Framework\Attributes\Test;

class SomeTest extends TestCase
{
    use RetrievesAuthorizedUsers;

    #[Test]
    public function some_phpunit_test_case()
    {
        $this->app();
          
        $user = User::factory()->create();
    }

}
```

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

### Listing Resources (Index Endpoint)

Source: https://docs.flarum.org/2.x/extend/api

The `Index` endpoint is used to list model instances. It supports pagination and sorting. The `Endpoint\Index::make()` method initializes this endpoint.

```APIDOC
## Listing Resources

The `Index` endpoint lists the model instances.

```php
use Flarum\Api\Endpoint;

public function endpoints(): array
{
    return [
        Endpoint\Index::make(),
    ];
}
```

### Pagination

You can paginate the resources being **listed** to by specifying the `limit` and `maxLimit` through the `paginate` method:

```php
use Flarum\Api\Endpoint;

public function endpoints(): array
{
    return [
        Endpoint\Index::make()
            ->paginate(20, 50), // these are the default values, so you may omit these arguments.
    ];
}
```

### Sorting

You can specify sort columns through the `sorts` method. For example the following will permit two sorting options: `createdAt` (in ascending order) and `-createdAt` (in descending order):

```php
use Flarum\Api\Sort\SortColumn;

public function sorts(): array
{
    return [
        SortColumn::make('createdAt'),
    ];
}
```

You can specify the default sort through the `defaultSort` method on the `Index` endpoint:

```php
use Flarum\Api\Endpoint;

public function endpoints(): array
{
    return [
        Endpoint\Index::make()
            ->defaultSort('-createdAt')
            ->paginate(),
    ];
}
```

### Searching and Filtering

Read our searching and filtering guide for more information!
```

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

### Chaining Admin Extender Methods

Source: https://docs.flarum.org/2.x/extend/admin

Illustrates how multiple extender methods like 'setting' and 'permission' can be chained together within a single Admin extender instance.

```javascript
import Extend from 'flarum/common/extenders';
import app from 'flarum/admin/app';

export default [
  new Extend.Admin()
    .setting(...)
    .permission(...)
    .permission(...)
    .permission(...)
    .setting(...)
    .setting(...)
];

```

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

### Enable Gambit Based on User Permissions

Source: https://docs.flarum.org/2.x/extend/search

Example of the `enabled` method in a gambit, checking if the current user has permission to use the gambit (e.g., `is:suspended`).

```typescript
enabled(): bool {
  return !!app.session.user && app.forum.attribute('canSuspendUsers');
}
```

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

### Loading Async Composer

Source: https://docs.flarum.org/2.x/extend/code-splitting

Load and show a custom composer asynchronously by passing a promise-returning callback to `app.composer.load`. The composer is displayed after successful loading.

```javascript
app.composer.load(() => import('flarum/forum/components/DiscussionComposer'), { user: app.session.user }).then(() => app.composer.show());  
```

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

### Handle Tag Gambit Predicates

Source: https://docs.flarum.org/2.x/extend/search

Example of how the `tag` gambit handles multiple values using logical operators, translating to a nested filter structure.

```json
{
  "tag": [
    "foo,bar", 
    "baz"
  ]
}
```

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

### Implement AcmeSearcher for Database Search

Source: https://docs.flarum.org/2.x/extend/search

Extend `AbstractSearcher` to define how your custom model is queried for search results. This example selects all columns from the 'acmes' table.

```php
namespace YourPackage\Search;  
  
use Flarum\Search\Database\AbstractSearcher;  
use YourPackage\Model\Acme;  
  
class AcmeSearcher extends AbstractSearcher  
{
    public function getQuery(User $actor): Builder  
    {
        return Acme::query()->select('acmes.*'); // The selection is recommended to avoid conflicts with other extensions.  
    }

}
```

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

### Create a Custom Service Provider

Source: https://docs.flarum.org/2.x/extend/service-provider

Extend AbstractServiceProvider to create custom logic for Flarum's registration and boot processes. The register method runs early in the boot sequence, while boot runs later. Use $this->container for access within register, and type-hint arguments in boot.

```php
<?php  

  
use Flarum\Foundation\AbstractServiceProvider;  
use Illuminate\Contracts\Container\Container;  
  
class CustomServiceProvider extends AbstractServiceProvider  
{
    public function register()  
    {
        // custom logic here, for example:  
        $this->container->resolving(SomeClass::class, function ($container) {  

            return new SomeClass($container->make('some.binding'));  

        });  

    }
  
    public function boot(Container $container)  
    {
        // custom logic here  

    }

}

```

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

### Configure Backend GitHub Actions Workflow

Source: https://docs.flarum.org/2.x/extend/github-actions

Set up the `.github/workflows/backend.yml` file to enable backend testing and static code analysis. This workflow reuses a predefined workflow from the Flarum framework.

```yaml
name: Backend  
  
on: [workflow_dispatch, push, pull_request]  
  
jobs:
  run:
    uses: flarum/framework/.github/workflows/REUSABLE_backend.yml@main
    with:
      # Different types of jobs
      enable_backend_testing: true
      enable_phpstan: false

      # Additional parameters
      backend_directory: .
```

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

### Set and Get Page State Data

Source: https://docs.flarum.org/2.x/extend/frontend-pages

Use `app.current.set(KEY, DATA)` to store data and `app.current.get(KEY)` to retrieve it from the current page state.

```javascript
app.current.set(KEY, DATA);

app.current.get(KEY);
```

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

### Mocking Settings Repository for Unit Tests

Source: https://docs.flarum.org/2.x/extend/testing

This snippet demonstrates how to mock the SettingsRepositoryInterface to control setting values for testing. Construct your class under test by passing the mocked repository.

```php
public function setUp(): void  

{
    parent::setUp();  

    // example - if our setting needs settings, we can mock the settings repository  

    $settingsRepo = m::mock(SettingsRepositoryInterface::class);
    
    // and then control specific return values for each setting key  

    $settingsRepo->shouldReceive('get')->with('some-plugin-key')->andReturn('some-value-useful-for-testing');  

    // construct your class under test, passing mocked services as needed  

    $this->serializer = new YourClassUnderTest($settingsRepo);

}

```

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

### Basic Private Post Filtering

Source: https://docs.flarum.org/2.x/extend/model-visibility

This snippet demonstrates a basic way to filter out private posts. It's a starting point before considering extension needs.

```php
$query->where('posts.is_private', false);
```

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

### Create New Resource

Source: https://docs.flarum.org/2.x/extend/models

Create a new resource by first instantiating a model using `app.store.createRecord` and then calling `save` on the new instance.

```javascript
const discussion = app.store.createRecord('discussions');  
  
discussion.save({ title: 'Hello, world!' }).then(console.log);  
```

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

### Create Table Migration

Source: https://docs.flarum.org/2.x/extend/models

Uses the `Migration::createTable` helper to define a new database table and its initial schema.

```php
use Flarum\Database\Migration;
use Illuminate\Database\Schema\Blueprint;

return Migration::createTable('users', function (Blueprint $table) {
    $table->increments('id');
});

```

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

### Remove Fields from a Resource

Source: https://docs.flarum.org/2.x/extend/api

This example shows how to remove one or more fields from an API resource using the removeFields method. It takes an array of field names to be removed.

```php
use Flarum\Api\Resource;
use Flarum\Extend;

return [
    (new Extend\ApiResource(Resource\UserResource::class))
        ->removeFields(['email']),
];
```

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

### Modify Route-Specific Document Title

Source: https://docs.flarum.org/2.x/extend/routes

Customize the document's title for a specific frontend route registration. This example sets the title to 'Users' for the '/users' route.

```php
return [
    (new Extend\Frontend('forum'))
        ->route('/users', 'acme.users', function (Document $document, Request $request) {
            $document->title = 'Users';
        })
];

```

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

### Efficiently Counting Relations in Flarum 2.x

Source: https://docs.flarum.org/2.x/extend/update-2_0-api

Demonstrates using the `countRelation` method in Flarum 2.x for efficient relation counting, as opposed to a simple `get` accessor.

```php
->countRelation('drafts', function (Builder $query, Context $context) {  
    $query->whereVisibleTo($context->getActor()); // visibility scope ;)  
})
```

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

### Add Backend Testing Infrastructure

Source: https://docs.flarum.org/2.x/extend/testing

Use the Flarum CLI to automatically add and update backend testing infrastructure to your extension.

```bash
$ flarum-cli infra backendTesting
```
Tokens:
Raw