Flarum

https://docs.flarum.org
Admin
Flarum is a fast, free, and simple discussion platform for websites, offering a delightful user...
Tokens:612,475
Snippets:4,137
Trust Score:9.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### Example Flarum extension test case setup

Source: https://docs.flarum.org/de/extend/testing/

A complete PHPUnit test class for a Flarum extension, demonstrating the use of setting(), extension(), prepareDatabase(), and extend() in setUp(). Note that the app boots on first call to app(), so all setup must occur before that. The example assumes a dependency on the flarum-tags extension and includes a normal user via the RetrievesAuthorizedUsers trait.

```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()
    {
        // ...
    }

    // ...
}
```

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

### setup.php script

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

Script to set up a testing database and file structure.

```php
<?php

use Flarum\Testing\integration\Setup\SetupScript;

require __DIR__.'/../../vendor/autoload.php';

$setup = new SetupScript();

$setup->run();
```

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

### Watch JavaScript files for extensions during development

Source: https://docs.flarum.org/contributing/

Starts the Yarn development watcher for extension JavaScript files, using the tags extension as an example.

```bash
cd extensions/tags/js
yarn dev
```

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

### Use version-specific bins fl1 and fl2 after switching

Source: https://docs.flarum.org/de/extend/cli/

After switching, you can still use the individual version-specific bins. This example shows the output of fl1 and fl2 info commands, confirming that fl1 points to the v2 CLI and fl2 to the v3 CLI.

```bash
$ fl1 flarum info
Flarum version: 1.x
CLI version: 2.0.2
$ fl2 flarum info
Flarum version: 2.x
CLI version: 3.0.1
```

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

### Get Flarum info: php flarum info

Source: https://docs.flarum.org/console/

Displays information about Flarum's core and installed extensions. Useful for debugging and should be shared when requesting support.

```bash
php flarum info
```

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

### Example config.php with all default options

Source: https://docs.flarum.org/config/

Shows the full structure of a typical config.php file with comments explaining each key. The 'debug' key enables or disables debug mode, 'offline' can be 'none', 'high', 'low', or 'safe', and the database block includes driver, host, database name, credentials, charset, collation, prefix, port, and strict mode. The 'url' key should be changed when the domain changes, and the 'queue' driver defaults to 'sync' if omitted.

```php
<?php return array (
  'debug' => false, // enables or disables debug mode, used to troubleshoot issues
  'offline' => false, // none, high, low or safe.
  'database' =>
  array (
    'driver' => 'mysql', // the database driver, i.e. MySQL, MariaDB, PostgreSQL, SQLite
    'host' => 'localhost', // the host of the connection, localhost in most cases unless using an external service
    'database' => 'flarum', // the name of the database in the instance
    'username' => 'root', // database username
    'password' => '', // database password
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => '', // the prefix for the tables, useful if you are sharing the same database with another service
    'port' => '3306', // the port of the connection, defaults to 3306 with MySQL
    'strict' => false,
  ),
  'url' => 'https://flarum.localhost', // the URL installation, you will want to change this if you change domains
  'paths' =>
  array (
    'api' => 'api', // /api goes to the API
    'admin' => 'admin', // /admin goes to the admin
  ),
  'queue' =>
  array (
    'driver' => 'sync', // Use the standard sync queue. Omitting this will entirely will have the same effect
  ),
  'fontawesome' =>
  array (
    'source' => 'local', // Use the bundled FontAwesome Free v7 icons. See below for other config options
  )
);
```

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

### Enable and start systemd service for realtime

Source: https://docs.flarum.org/de/extensions/realtime/

After creating the systemd unit, run these commands to reload systemd, start the service, check its status, and enable it to start on boot.

```bash
sudo systemctl daemon-reload
sudo systemctl start flarum-realtime.service
sudo systemctl status flarum-realtime.service
sudo systemctl enable flarum-realtime.service
```

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

### tinker: Resolve a service from the container

Source: https://docs.flarum.org/console/

Demonstrates resolving a service from the container using `resolve()`. This example resolves the `UrlGenerator` and calls `to('forum')->base()` to get the forum base URL.

```php
>>> resolve(Flarum\Http\UrlGenerator::class)->to('forum')->base();
=> "https://my-forum.example.com"
```

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

### HTTP Request with Default Includes

Source: https://docs.flarum.org/de/extend/api/

Example GET request that combines explicit includes with default includes by adding `withDefaultIncludes=1`. This is used by the forum's post lists to load default relationships.

```text
GET /api/posts?include=user,discussion&withDefaultIncludes=1
```

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

### Example of switching CLI versions with output

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

Shows the interactive prompt and output when switching from CLI 3.x to CLI 2.x, and the resulting version info.

```shell
$ fl flarum info
Flarum version: 2.x
CLI version: 3.0.1
$ fl flarum change
Currently using CLI 3.x compatible with Flarum 2.x

✔ Switch to CLI 2.x compatible with Flarum 1.x? … yes
$ fl flarum info
Flarum version: 1.x
CLI version: 2.0.2
```

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

### Transpilation commands for npm, yarn, and pnpm

Source: https://docs.flarum.org/de/extend/frontend/

Run these commands in the js directory to install dependencies and start the dev watcher. The build script (e.g., npm run build) is used for production builds.

```bash
# npm
npm install
npm run dev

# yarn
yarn install
yarn dev

# pnpm
pnpm install
pnpm dev
```

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

### Mocking Flarum Settings Repository in setUp

Source: https://docs.flarum.org/de/extend/testing/

In the setUp method, mock the SettingsRepositoryInterface to control return values for specific setting keys, then construct the class under test with the mocked service. This is useful for unit tests that require settings.

```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);
}
```

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

### Declare a hard dependency on another extension in composer.json

Source: https://docs.flarum.org/extend/extending-extensions/

Add the other extension to the 'require' section of your extension's composer.json. This ensures the dependency is installed and enabled before yours, cannot be disabled while yours is enabled, and is booted first. The example requires 'flarum/core' and 'flarum/tags'.

```json
{
  // ...
  "require": {
    "flarum/core": "^2.0",  // Since all extensions need to require core.
    "flarum/tags": "*"  // This tells Flarum to treat tags as a dependency of your extension.
  },
  // ...
}
```

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

### Create Flarum project with Composer

Source: https://docs.flarum.org/de/install/

Run this command in an empty directory to install Flarum 2.x. While it runs, configure your web server to point the webroot to /path/to/your/forum/public and set up URL rewriting.

```bash
composer create-project flarum/flarum:^2.0.0 .
```

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

### List discussions endpoint (GET /api/discussions)

Source: https://docs.flarum.org/de/rest-api/

Example JSON response from the Flarum API for listing discussions. The response includes pagination links, discussion data with attributes and relationships, and included related resources like users, tags, and posts. JSON is truncated for readability.

```json
{
  "links": {
    "first": "https://flarum.tld/api/discussions",
    "next": "https://flarum.tld/api/discussions?page%5Boffset%5D=20"
  },
  "data": [
    {
      "type": "discussions",
      "id": "234",
      "attributes": {
        "title": "Lorem Ipsum",
        "slug": "234-lorem-ipsum",
        "commentCount": 10,
        "participantCount": 3,
        "createdAt": "2022-01-01T10:20:30+00:00",
        "lastPostedAt": "2022-01-05T10:20:30+00:00",
        "lastPostNumber": 10,
        "canReply": true,
        "canRename": true,
        "canDelete": true,
        "canHide": true,
        "isHidden": true,
        "hiddenAt": "2022-01-06T10:20:30+00:00",
        "lastReadAt": "2022-01-02T10:20:30+00:00",
        "lastReadPostNumber": 2,
        "isApproved": true,
        "canTag": true,
        "isLocked": false,
        "canLock": true,
        "isSticky": false,
        "canSticky": true,
        "canMerge": true,
        "subscription": null
      },
      "relationships": {
        "user": {
          "data": {
            "type": "users",
            "id": "1"
          }
        },
        "lastPostedUser": {
          "data": {
            "type": "users",
            "id": "64"
          }
        },
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "3"
            }
          ]
        },
        "firstPost": {
          "data": {
            "type": "posts",
            "id": "668"
          }
        }
      }
    },
    {
      "type": "discussions",
      "id": "234",
      "attributes": {
        // [...]
      },
      "relationships": {
        // [...]
      }
    },
    // [...] more discussions
  ],
  "included": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "Admin",
        "displayName": "Admin",
        "avatarUrl": null,
        "slug": "1"
      }
    },
    {
      "type": "users",
      "id": "64",
      "attributes": {
        "username": "Flarum",
        "displayName": "Flarum",
        "avatarUrl": "https://flarum.tld/assets/avatars/Z4hEncw0ndVqZ8be.png",
        "slug": "64"
      }
    },
    {
      "type": "tags",
      "id": "3",
      "attributes": {
        "name": "Welcome",
        "description": "Post interesting things here",
        "slug": "welcome",
        "color": "#888",
        "backgroundUrl": null,
        "backgroundMode": null,
        "icon": "fas fa-bullhorn",
        "discussionCount": 30,
        "position": 1,
        "defaultSort": null,
        "isChild": false,
        "isHidden": false,
        "lastPostedAt": "2022-01-05T10:20:30+00:00",
        "canStartDiscussion": true,
        "canAddToDiscussion": true,
        "isRestricted": false
      }
    },
    {
      "type": "posts",
      "id": "668",
      "attributes": {
        "number": 1,
        "createdAt": "2022-01-01T10:20:30+00:00",
        "contentType": "comment",
        "contentHtml": "<p>Hello World</p>"
      }
    },
    // [...] more includes for the other discussions
  ]
}
```

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

### Prepare database data with model factories in Flarum integration test

Source: https://docs.flarum.org/de/extend/testing/

Uses model classes as table keys in prepareDatabase to generate default values via factories. The example shows a test setup with User, Discussion, and Post models, where fields like created_at are filled by the factory.

```php
<?php

namespace CoolExtension\Tests\integration;

use Flarum\Testing\integration\RetrievesAuthorizedUsers;
use Flarum\Testing\integration\TestCase;
use Flarum\User\User;
use Flarum\Discussion\Discussion;
use Flarum\Post\Post;

class SomeTest extends TestCase
{
    use RetrievesAuthorizedUsers;

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

        $this->prepareDatabase([
            User::class => [
                $this->normalUser(),
            ],
            Discussion::class => [
                // For example, created_at will be filled by the model factory.
                ['id' => 1, 'title' => 'some title', 'last_posted_at' => Carbon::now(), 'user_id' => 1, 'first_post_id' => 1]
            ],
            Post::class => [
                ['id' => 1, 'number' => 1, 'discussion_id' => 1, 'user_id' => 1, 'type' => 'comment']
            ],
        ]);
    }
}
```

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

### Load and check supervisor configuration

Source: https://docs.flarum.org/de/extensions/realtime/

After creating the supervisor configuration, run these commands to load it and verify the realtime process is running.

```bash
sudo supervisorctl update
sudo supervisorctl status
```

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

### Flarum TestCase request and send example

Source: https://docs.flarum.org/it/extend/testing/

Shows how to use TestCase's request() and send() methods to test API endpoints. Includes two test methods: can_search_users (GET with query parameters) and can_create_user (POST with JSON body). Note that query parameters must be added with withQueryParams, not in the path.

```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\TestCase;
use PHPUnit\Framework\Attributes\Test;

class SomeTest extends TestCase
{
    #[Test]
    public function can_search_users()
    {
        $response = $this->send(
          $this->request('GET', '/api/users', ['authenticatedAs' => 1])
               ->withQueryParams(['filter' => ['q' => 'john group:1'], 'sort' => 'username'])
        );

        $this->assertEquals(200, $response->getStatusCode());
    }

    #[Test]
    public function can_create_user()
    {
        $response = $this->send(
          $this->request(
                'POST',
                '/api/users',
                [
                    'authenticatedAs' => 1,
                    'json' => [
                        'data' => [
                            'attributes' => [
                                'username' => 'test',
                                'password' => 'too-obscure',
                                'email' => '[email protected]'
                            ]
                        ]
                    ]
                ]
            )
        );

        $this->assertEquals(200, $response->getStatusCode());
    }

    // ...
}
```
Tokens:
Raw