flarum/docs

Flarum documentation.

About Flarum

Flarum is a delightfully simple discussion platform for your website. It's fast and easy to use, with all the features you need to run a successful community. It is designed to be:

• Fast and simple. No clutter, no bloat, no complex dependencies. Flarum is built with PHP so it’s quick and easy to deploy. The interface is powered by Mithril, a performant JavaScript framework with a tiny footprint.

• Beautiful and responsive. This is forum software for humans. Flarum is carefully designed to be consistent and intuitive across platforms, out-of-the-box.

• Powerful and extensible. Customize, extend, and integrate Flarum to suit your community. Flarum’s architecture is amazingly flexible, with a powerful Extension API.

Installation

Read the Installation guide to get started. For support, refer to the documentation, and ask questions on the community forum or Discord chat.

Contributing

Thank you for considering contributing to Flarum! Please read the Contributing guide to learn how you can help.

This repository only holds the Flarum skeleton application. Most development happens in flarum/core.

Security Vulnerabilities

If you discover a security vulnerability within Flarum, please follow our security policy so we can address it promptly.

License

Flarum is open-source software licensed under the MIT License.

docs's Issues

Improve Apache instructions for shared hosts

Hi, as for the issue flarum/framework#1689 I suggest to integrate informations on this post: https://discuss.flarum.org/d/17977-forum-public-why-not-just-forum/7

This works also on localhost, tested. The documentation given by Flarum Doc did not work or is too complicated.

SHC found the solution.

Index.md has link to installation.md

user/installation.md no longer exists.

Document model sluggability

New section "update policy, LTS etc"

Although we're currently releasing only beta's, we have to start a new section about our update policy before the stable release. We have to be transparent about what versions we will support and for how long. Are we going to do an LTS?

Currently our team is far too small to provide long(er) term support. I'd like to propose to clearly state that updates on older versions, including security updates, are not included. We will however always patch the latest version as soon as possible.

In addition we might need a security newsletter to inform people about important patches.

"Edit this page" link doesn't work for index pages

If you click "Edit this page" at https://flarum.org/docs/extend/ you will be taken to https://github.com/flarum/docs/edit/master/docs/extend/README.md instead of https://github.com/flarum/docs/edit/master/docs/extend/index.md

Same for https://flarum.org/docs/

Explain the choice for composer

Summarise this (private) discussion under the FAQ:

https://discuss.flarum.org/d/4369-rfc-drop-composer-simplify-project-structure

Documentation for REST API use

Even if it's as much as there previously was on the docs for beta 7, at least that'd be something which would include getting an API key and performing basic requests.

Add information on how to debug an extension

While talking to @tobscure he offered some advice on debugging extensions which use the front-end (mithrill) side:

• check whether your extension is loaded System.get('vendor/extension/main'); in the source of the page
• inspect the app
• in the console: System.get('path/to/module').default to inspect a module/class

Might need more than this. But this is a start.

Confusion js extenders

In my opinion I find the docs about the javascript extenders kinda confusing. And I'm not sure what the way to go is even.

Most extensions (still) have

import app from 'flarum/app';

app.initializers.add('foo-bar', function(app) {
//extend functions, etc
}

But in the docs it says

import { Extend } from '@flarum/core/forum';

export const extend = [
  // Your JavaScript extenders go here
];

Whats the difference? Can you use both in one index.js file? Is it possible to do like this below?

import app from 'flarum/app'; //not needed anymore then i guess?
import { Extend } from '@flarum/core/forum';
import { extend } from 'flarum/extend';
import Model from 'flarum/Model';
import Bar from './Bar';
//...

export const extend = [ //will probably error because there are 2 imports with the name "extend" ? Or can this be a variable of our choice?
    new Extend.Model('foo', Bar),
    new Extend.Model('users').hasMany('foo'),//should be the same model name as the line above?
    new Extend.Routes().add('/foobars', 'acme.foobars', <FooPage />),

    //assumingly equals to:
    //app.store.models.foo = Bar
    //User.prototype.foobars = Model.hasMany('foo')
    //app.routes.foobars = {path: '/foobars', component: FooPage.component()};

    extend(UserCard.prototype, 'infoItems', function(items) {
        //..
    }),

    extend(UserPage.prototype, 'sidebarItems', function(items) {
        //...
    }),

    extend(UserPage.prototype, 'show', function() {
        //...
    }),

    addOtherStuff(),

    override(DiscussionComposer.prototype, 'onsubmit', function(original) {
        // ...
    }),
];

Or are we in a situation where we can use "both worlds" but only the one or the other ? For me there's a bit more need for clarification overal. Not sure if anyone else thinks like me.

Add Flarum logo

Add Flarum logo to the navigation bar.

After researching some references, I came up with two proposals that follow below.

A) Brand mark

Inspired by Vue.js 3 documentation (VuePress).
Pull Request: #137

Preview:

B) Docs logo

Inspired by Netlify documentation (VuePress).
Pull Request: #138

Preview:

Assets recompilation only when debug mode is on

Hello,

Nowhere in the Contribution section was mentioned how to use the locally compiled assets. I was busting my head figuring this out and finally I realised that during development the debug mode in the configuration file must be set to true.

I haven't investigated what does debug: true includes as debugging as I am fan of the actual xdebug debugging but I never thought that would be something that relates so much to the assets, so I've never turned on this option.
Finally I turned it on and realised that this is a key option to make the assets to get recompiled on the page.

I think this part is very important to be documented for new contributors coming to help Flarum.

Also, when working on extensions' js files, I think that npm link ../../core/js is enough.

Section integrations

We need some documentation for developers on how to access the API outside of Flarum. So many questions revolve around using the master token and accessing the API directly.

Update version constraint guidelines

Our guidelines for version constraints (under require) need updating now that we are on Beta 12. Our new range should be Beta 11-Beta 13.

We should also have an anchor there so it's easy to direct users to this part of our docs.

Languages page is really out of date

The page https://flarum.org/docs/languages.html https://github.com/flarum/docs/blob/master/docs/languages.md seems to still show pre-composer instructions which are now completely irrelevant.

I'm not sure how to update the "Language Pack Installation" section but right now it can only cause confusion. Maybe just keep the very first sentence of that section and remove everything else ?

Move most Nginx configuration to flarum/flarum

As suggested by @uded in this comment.

Concepts link in Contribution page does not work

The contribution guidelines page has a link to Concepts which does not exist.

docs/docs/contributing.md

Line 7 in 21f10d5

This document is a guide for developers who want to contribute code to Flarum. If you're just getting started, we recommend that you read the [Concepts](/extend/concepts.md) documentation in the Extension docs to understand a bit more about how Flarum works.

Translating contribution?

Any way to translate?

Turkish character problem in URL

Some links have a Turkish character mismatch.

https://docs.flarum.org/tr/#flarum-hakk%C4%B1nda
https://docs.flarum.org/tr/code-of-conduct.html#davran%C4%B1s-kurallar%C4%B1

Some links are correct.

https://docs.flarum.org/tr/update.html#guncelleme

Turkish characters should change as follows in the link:

ç > c
ğ > g
ı > i
ş > s
ö > o
ü > u
Ç > C
Ğ > G
İ > I
Ş > S
Ö > O
Ü > U

Document Queue

Introduce official code-generated documentation for PHP and JS

It would be nice to convert http://api.flarum.dev/ into official documentation that we could reference from the vuepress docs.

Multi-language support?

I can translate documents into Chinese. Is there any plan to enable multi-language vuepress documents?

Document Display Name system

API Docs and create api keys through admin panel

If I can see correctly, you can make an api through the phpmyadmin or whatever you use.

• API Docs
• API Keys interface
• Saving Data to MySQL Database
  Could you make API Docs of how to use api keys?

Also can you make an API key Create interface.

Thanks 👍!

Document authentication

One of the more common support requests is from people looking to integrate their flarum forum with the rest of their site through shared user accounts / authentication. A documentation article explaining:

• How Flarum authentication currently works
• Flarum's APIs for federated / social login
• How Flarum might be extended to offboard authentication to an external server (or moreso, how global login might be implemented)

would go a huge way

documentation responsibilities

Let's use this issue for now to specify who will write what. We can split it up if necessary or create an issue in flarum/core if part of the documentation should be done before a certain milestone.

• /extend/distribution @franzliedke

Amazon SES instructions

In order to use the SES driver, the aws/aws-sdk-php package is needed.

In its time, Flagrow Mail Drivers had the following line in its README:

Before configuring the SES driver you need to install the Amazon SDK with composer require aws/aws-sdk-php:~3.0.

We should add it somewhere in the Flarum docs, though I don't know which place makes sense.

We could also make it a message inside Flarum itself when you select the SES driver though I'm not sure it's worth the hassle.

Rename repo to "flarum-docs"

Any chance? It would be nice to have more distinction in my local repo names against other docs projects I contribute to, which generally go by "{project}-docs" -- "docs" by itself is a little too generic.

Composer 2 does not allow project creation in current working directory

Bug Report

Current Behavior
I have been testing the Composer 2 preview for quite some time now and came across a peculiar error.

Steps to Reproduce

1. Install the latest Composer 2 preview with composer self-update --preview
2. Create a new directory to install a fresh Flarum project in.
3. Change to that directory.
4. Run composer create-project flarum/flarum . --stability=beta as per Flarum installation docs.

Expected Behavior
You should be able to create the Flarum composer project the same way as you were able to using Composer v1 where no path name was required.

Screenshots

Environment

• Flarum version: v0.1.0-beta.13
• Webserver: Apache
• OS: Windows 10 Pro
• PHP version: 7.4.8

Possible Solution
N/A

Additional Context
This issue isn't specific to Flarum, something changed in Composer 2 where specifying a path required now. This error seems to only appear on the Windows platform as I haven't tested it any other OS. I can also reproduce this with other packages such as Laravel as show below where I omit the typical path name that Laravel uses in it's installation docs.

The error message from the screenshot I provided can be found in the following Composer code.

This will only prove as an issue with users who do local development on Windows or for those that host their Flarum installs on Windows Server.

More routing clarification

On the page of extenders, the routing extender, I feel like there should also be information about the routing classes and the js side of routes as routing needs to be done server- and client side. Also include an example from flarum tags maybe too for server side routing and js side

If possible create a different section for only routing, because i feel it could be much

Document Search

Document how to add gambits, filters, search, and filter mutators.

We can leave search drivers and the frontend search component (which is currently broken anyways) for later.

Extenders are not using the same wording

When I look at the Routes extender the construct uses the variable $appName, the Frontend uses $frontend. I'm confused about the difference in naming. I know about Site vs App, but is this what was actually meant by them?

0.1.0-beta.8 upgrade/changelog

This issue houses all changes for beta 8. We can split the list up into different sections:

• Webmaster (people installing and upgrading Flarum)
• Developer (people maintaining a Flarum extension)

Webmaster

• The minimum PHP version will now be 7.1. It used to be 5.6.
• The minimum MySQL version will now be 5.6. It used to be 5.5.
• The skeleton flarum/flarum was updated:
  • public folder added
  • api.php and admin.php are removed
  • the .htaccess now directs all requests to non-existing files to index.php
  • The akismet extension has been unbundled.
• New discussion.hidePosts permissions, enabled by default (and via upgrade) for moderators.
  • Custom groups might need to be adapted as well.
  • See flarum/framework#1387 and flarum/framework#1466.

Developer

• Pretty much all namespaces changed.
• Events were moved from one global Event namespace to their respective namespaces, eg Flarum\Event\UserWillBeSaved > Flarum\User\Event\Saving
• FloodGate has been made extensible

Is this repo deprecated?

I was creating a PR but then found out there is also https://github.com/flarum/flarum.github.io

Order of parameters to javascript Extend.Routes.add does not match reality

At https://docs.flarum.org/extend/routes.html#frontend-routes we are shown the following javascript example:

export const extend = [
  new Extend.Routes()
    .add('/users', 'acme.users', <UsersPage />)
];

However in the source https://github.com/flarum/core/blob/master/js/src/common/extend/Routes.js we can see the signature:

add(name, path, component) {
    // [...]
}

This seems to be confirmed by me implementing this in my extension. I had to pass the name first and path second.

This differs from the parameter order in PHP where path is actually first and name second.

If someone could go through the documentation and check that we show the correct way to call it each time, that would be great! Otherwise I'll do it when I find some time.

New section "Security hardening"

As proposed by @kulga here, we should probably change our included Apache configuration (and the one for Nginx in the docs) to only include the bare essentials - or at least only things that cause no problems with other components.

(In this particular example, always stripping the Proxy request header might cause problems with reverse proxies.)

Instead, a section called "Security hardening" or something similar should contain further "recipes" with things that should be applied to secure the server configuration. (For things like the above, notes should make it clear that they should not be combined with certain setups, e.g. reverse proxies.)

Revisit structure for stable

@tobscure do we need to revisit the decided structure now that the whole extension api will be changed for stable or are we still good to go with this documentation structure?

Make installation page more user-friendly

I think the installation page looks a bit empty having just installation guides for Ubuntu and CentOS. I'd like to make the installation page hold a bit more information considering the stability and just the basic commands and configuration needed, and link to the guides before that (but after the stability warnings) in case the user is in fact using a VPS or dedicated server. I'd also like to modify the CentOS and Ubuntu installation guides a bit to make it a little more understandable and less cluttered. May I do this (sorry, this is kind of my first time doing something like this, so not exactly sure how it works)?

Missing Flarum's own utilities in Troubleshooting page

The Troubleshooting page does not contain a description of php flarum info or how to use it/what it does. This is our best diagnostic utility for troubleshooting, so we might as well promote it in our own docs pages.

Flarum requires php 7.2.9+ and not 7.2+

When trying to upgrade flarum to beta 13 composer didn't let me:

The cause is that version 3 of that package requires php 7.2.9

Raise PHP requirement from 7.1 to 7.2.9 (James Forrester)

And the php version i have is 7.2.5 - which means flarum isn't just 7.2+ but 7.2.9+

New section: "Shared hosts"

The default skeleton now requires pointing the webserver root to the public/ folder. This is not possible on most shared hosts.

For them, we need some additional instructions, they will mostly consist of:

• adding/moving one file (ping me for the exact code - I will do my best to keep the changes as small as possible)
• some necessary security-hardening (preventing access to certain files and directories, see flarum/framework#692)

Nginx docs: Protect composer.lock and .git folder

We need to update the documented nginx configuration, see

flarum/flarum#41 (comment)

Examples

I am planning to add an "examples" section, where each will go over creation of a simplified, proof of concept extension. A few that I'm planning right now:

• Adding a field to the User model
• Some basic example with a new model, where model instances can be added via the UI, and are all displayed on a page
• Creating language packs (link to weblate, talk about dayjs config)

I am very open to ideas of other things that need to be included.

Create section to address file ownership during installation

Users are often presented with an error during installation to chmod their files to 775, and many, upon completing it, find the error still persisting and Flarum not installing. This often stems from improper ownership/authority of the file owner and not the permissions of the file itself.

A section on the Installation page should be written to describe, in simple yet informative terms, what is occurring and what Flarum requires to proceed. In addition, we should include an example based on commonly advised setups (e.g. www-data as the php/webserver user) with a disclaimer that individual environments may vary.

Version constraints for beta.14

The getting started page in the Extend docs still suggests to use >=0.1.0-beta.12 <0.1.0-beta.14 as the flarum/core version constraint.

It should be updated now that beta.14 has been released.

Document validation

Add Dev README to Docs

@luceos had brought up that we should include the Dev intro README on Flarum Discuss into the docs officially. It would also clear up the number of stickies we have if we so choose to un-sticky the discussion.

The discussion in question can be found here:

https://discuss.flarum.org/d/1662-extension-developer-first-read

Document Post Types

Docs We Need

This is a living document, and will be updated as we determine the most critical areas in need of documentation.

• The currently empty pages
• Advanced Frontend Section
  • SubtreeRetainer
  • Fragment
  • Extending components/utils to be used by other extensions
• Backend
  • Policies and Permissions

Each section has an introduction

Each section has an introduction, let's specify a content guideline in this discussion:

• Who is the section for. Classify target groups; developers, administrators, end users.
• What is the section about.

Anything else we should cover in a section introduction?

0.1.0-beta.9 upgrade/changelog

Just to get this on the road as well.

• flarum/framework#1640 ups the illuminate components and all related packages to use 5.7