Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ A typical contribution workflow looks like this:
1. 🚦 **Test** your code.
* Add unit tests as necessary when fixing bugs or adding features.
* Run the test suite with `vendor/bin/phpunit` in the relevant package folder.

<!--
* See [here](link-to-core/tests/README.md) for more information about testing in Flarum.
-->
Expand Down
8 changes: 4 additions & 4 deletions docs/extend/authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Each of these is determined by unique criteria: in some cases a flag is sufficie

### How It Works

Authorization queries are made with 3 parameters, with logic contained in [`Flarum\User\Gate`](https://api.docs.flarum.org/php/master/flarum/user/gate):
Authorization queries are made with 3 parameters, with logic contained in [`Flarum\User\Gate`](https://api.docs.flarum.org/php/master/flarum/user/access/gate):

1. The actor: the user attempting to perform the action
2. The ability: a string representing the action the actor is attempting
Expand Down Expand Up @@ -195,7 +195,7 @@ return [
## Visibility Scoping

When a user visits the **All Discussions** page, we want to quickly show them the recent discussions that the user has access to.
We do this via the `whereVisibleTo` method, which is defined in `Flarum\Database\ScopeVisibilityTrait`, and available to [Eloquent models and queries](https://laravel.com/docs/6.x/queries) through [Eloquent scoping](https://laravel.com/docs/6.x/eloquent#local-scopes).
We do this via the `whereVisibleTo` method, which is defined in `Flarum\Database\ScopeVisibilityTrait`, and available to [Eloquent models and queries](https://laravel.com/docs/8.x/queries) through [Eloquent scoping](https://laravel.com/docs/8.x/eloquent#local-scopes).
For example:

```php
Expand Down Expand Up @@ -224,7 +224,7 @@ This call is handled by Flarum's general model visibility scoping system, which

The query will be run through all applicable scopers registered for the model of the query. Note that visibility scopers registered for a parent class (like `Flarum\Post\Post`) will also be applied to any child classes (like `Flarum\Post\CommentPost`).

Note that scopers don't need to return anything, but rather should perform in-place mutations on the [Eloquent query object](https://laravel.com/docs/6.x/queries).
Note that scopers don't need to return anything, but rather should perform in-place mutations on the [Eloquent query object](https://laravel.com/docs/8.x/queries).

### Custom Permission Strings

Expand Down Expand Up @@ -277,7 +277,7 @@ Think of calling `whereVisibleTo` with a custom ability as a way for extensions

### Custom Visibility Scoper Examples

Let's take a look at some examples from [Flarum Tags](https://github.com/flarum/tags/blob/master/src/Access/TagPolicy).
Let's take a look at some examples from [Flarum Tags](https://github.com/flarum/tags/blob/master/src/Access).

First, a scoper for the `Tag` model with the `view` ability:

Expand Down
4 changes: 2 additions & 2 deletions docs/extend/backend-events.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Backend Events

Often, an extension will want to react to some events occuring elsewhere in Flarum. For instance, we might want to increment a counter when a new discussion is posted, send a welcome email when a user logs in for the first time, or add tags to a discussion before saving it to the database. These events are known as **domain events**, and are broadcasted across the framework through [Laravel's event system](https://laravel.com/docs/6.x/events).
Often, an extension will want to react to some events occuring elsewhere in Flarum. For instance, we might want to increment a counter when a new discussion is posted, send a welcome email when a user logs in for the first time, or add tags to a discussion before saving it to the database. These events are known as **domain events**, and are broadcasted across the framework through [Laravel's event system](https://laravel.com/docs/8.x/events).

:::warning Old Event API
Historically, Flarum has used events for its extension API, emitting events like `GetDisplayName` or `ConfigureApiRoutes` to allow extensions to insert logic into various parts of Flarum. These events are gradually being phased out in favor of the declarative [extender system](start.md#extenders), and will be removed before stable. Domain events will not be removed.
Expand Down Expand Up @@ -43,7 +43,7 @@ class PostDeletedListener
}
```

As shown above, a listener class can be used instead of a callback. This allows you to [inject dependencies](https://laravel.com/docs/6.x/container) into your listener class via constructor parameters. In this example we resolve a translator instance, but we can inject anything we want/need.
As shown above, a listener class can be used instead of a callback. This allows you to [inject dependencies](https://laravel.com/docs/8.x/container) into your listener class via constructor parameters. In this example we resolve a translator instance, but we can inject anything we want/need.

You can also listen to multiple events at once via an event subscriber. This is useful for grouping common functionality; for instance, if you want to update some metadata on changes to posts:

Expand Down
10 changes: 5 additions & 5 deletions docs/extend/data.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Migrations live inside a folder suitably named `migrations` in your extension's

### Migration Structure

In Flarum, migration files should **return an array** with two functions: `up` and `down`. The `up` function is used to add new tables, columns, or indexes to your database, while the `down` function should reverse these operations. These functions receive an instance of the [Laravel schema builder](https://laravel.com/docs/6.x/migrations#creating-tables) which you can use to alter the database schema:
In Flarum, migration files should **return an array** with two functions: `up` and `down`. The `up` function is used to add new tables, columns, or indexes to your database, while the `down` function should reverse these operations. These functions receive an instance of the [Laravel schema builder](https://laravel.com/docs/8.x/migrations#creating-tables) which you can use to alter the database schema:

```php
<?php
Expand Down Expand Up @@ -68,7 +68,7 @@ return Migration::createTable('users', function (Blueprint $table) {
});
```

When creating the table, you may use any of the schema builder's [column methods](https://laravel.com/docs/6.x/migrations#creating-columns) to define the table's columns.
When creating the table, you may use any of the schema builder's [column methods](https://laravel.com/docs/8.x/migrations#creating-columns) to define the table's columns.

### Renaming Tables

Expand Down Expand Up @@ -101,13 +101,13 @@ return Migration::renameColumns('users', ['from' => 'to']);

### Data Migrations (Advanced)

A migration doesn't have to change database structure: you could use a migration to insert, update, or delete rows in a table. For instance, you could use migrations to assign [custom permissions](permissions.md) to groups other than Admin, or provide some initial data for a custom Eloquent model. Since you have access to the [Eloquent Schema Builder](https://laravel.com/docs/6.x/migrations#creating-tables), anything is possible (although of course, you should be extremely cautious and test your extension extensively).
A migration doesn't have to change database structure: you could use a migration to insert, update, or delete rows in a table. For instance, you could use migrations to assign [custom permissions](permissions.md) to groups other than Admin, or provide some initial data for a custom Eloquent model. Since you have access to the [Eloquent Schema Builder](https://laravel.com/docs/8.x/migrations#creating-tables), anything is possible (although of course, you should be extremely cautious and test your extension extensively).

Data migrations are the recommended way to specify default settings and permissions.

## Backend Models

With all your snazzy new database tables and columns, you're going to want a way to access the data in both the backend and the frontend. On the backend it's pretty straightforward – you just need to be familiar with [Eloquent](https://laravel.com/docs/6.x/eloquent).
With all your snazzy new database tables and columns, you're going to want a way to access the data in both the backend and the frontend. On the backend it's pretty straightforward – you just need to be familiar with [Eloquent](https://laravel.com/docs/8.x/eloquent).

### Adding New Models

Expand Down Expand Up @@ -141,7 +141,7 @@ return [

### Relationships

You can also add [relationships](https://laravel.com/docs/6.x/eloquent-relationships) to existing models using the `hasOne`, `belongsTo`, `hasMany`, `belongsToMany`and `relationship` methods on the `Model` extender. The first argument is the relationship name; the rest of the arguments are passed into the equivalent method on the model, so you can specify the related model name and optionally override table and key names:
You can also add [relationships](https://laravel.com/docs/8.x/eloquent-relationships) to existing models using the `hasOne`, `belongsTo`, `hasMany`, `belongsToMany`and `relationship` methods on the `Model` extender. The first argument is the relationship name; the rest of the arguments are passed into the equivalent method on the model, so you can specify the related model name and optionally override table and key names:

```php
new Extend\Model(User::class)
Expand Down
2 changes: 1 addition & 1 deletion docs/extend/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ Only one main JavaScript file per extension is permitted. If you need to include

### CSS

You can also add CSS and [LESS](http://lesscss.org/features/) assets to the frontend using the `Frontend` extender's `css` method:
You can also add CSS and [LESS](https://lesscss.org/features/) assets to the frontend using the `Frontend` extender's `css` method:

```php
(new Extend\Frontend('forum'))
Expand Down
12 changes: 6 additions & 6 deletions docs/extend/i18n.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ This shows the basic translation method, with no bells or whistles attached. Bel

## Including Variables

You can include variables in translations. As an example, let's look at the code that creates the first item in Flarum's [search results dropdown](https://github.com/flarum/core/blob/master/js/forum/src/components/DiscussionsSearchSource.js). This button quotes the search query entered by the user &mdash; information that is passed to the translator along with the translation key, as an additional parameter:
You can include variables in translations. As an example, let's look at the code that creates the first item in Flarum's [search results dropdown](https://github.com/flarum/core/blob/master/js/src/forum/components/DiscussionsSearchSource.js). This button quotes the search query entered by the user &mdash; information that is passed to the translator along with the translation key, as an additional parameter:

```jsx harmony
{LinkButton.component({
Expand Down Expand Up @@ -181,7 +181,7 @@ return app.translator.transChoice(
);
```

This example is from the [Choose Tags modal](https://github.com/flarum/tags/blob/master/js/forum/src/components/TagDiscussionModal.js) of the Tags extension, where it tells the user how many more primary tags can be selected. Note that the `remaining` variable is passed to the translator **twice**. First, it appears as itself, to condition the pluralization of the word "tags". Then it appears again as the value of the `count` parameter, which the translator can use to insert that value in the translation.
This example is from the [Choose Tags modal](https://github.com/flarum/tags/blob/master/js/src/forum/components/TagDiscussionModal.js) of the Tags extension, where it tells the user how many more primary tags can be selected. Note that the `remaining` variable is passed to the translator **twice**. First, it appears as itself, to condition the pluralization of the word "tags". Then it appears again as the value of the `count` parameter, which the translator can use to insert that value in the translation.

When the `app.translator.transChoice()` method is called, the translator scans the translation for a variant that matches the sort of pluralization required by the value of the variable. These variants need to be listed serially &mdash; singular form first, then plural forms in order of increasing magnitude &mdash; and separated using the vertical line (`|`) character. Here's the English translation for the above code:

Expand Down Expand Up @@ -360,7 +360,7 @@ core:

It would very easy to change the translation for the header link without realizing that you're also changing things in the Log In modal &mdash; to say nothing of any extensions that might also be referencing that key! This sort of thing will be less likely to occur if you keep your reused translations in the `ref` namespace.

For this reason, any key references in the [core resources](https://github.com/flarum/lang-english/blob/master/locale/core.yml) **must** point to keys in the `core.ref` namespace. Key references in the resources for bundled extensions may point to either of two locations:
For this reason, any key references in the [core resources](https://github.com/flarum/core/blob/master/locale/core.yml) **must** point to keys in the `core.ref` namespace. Key references in the resources for bundled extensions may point to either of two locations:

- Extension-specific translations should go in the `ref` namespace of the extension's locale file.

Expand Down Expand Up @@ -402,7 +402,7 @@ Generally speaking, any displayed text that isn't supplied by a variable or the

Hardcoded text isn't the only way that code can create problems for localizers. Hardcoded syntax issues occur when the code forces words into a specific order that just won't work in other languages. They are generally the result of using two translations where just one would be more appropriate.

For an example, let's look at the line of text that's printed near the bottom of the [Log In modal](https://github.com/flarum/core/blob/master/js/forum/src/components/LogInModal.js):
For an example, let's look at the line of text that's printed near the bottom of the [Log In modal](https://github.com/flarum/core/blob/master/js/src/forum/components/LogInModal.js):

> Don't have an account? [Sign Up](#)

Expand Down Expand Up @@ -439,9 +439,9 @@ They are surprisingly easy to overlook. Of course, the need for pluralization su
> You like this.
> Toby and Franz like this.

And the situation is complicated by the presence of the second-person pronoun, since it always takes the plural form in English, even when we're talking about one person. That's why the `app.translator` call is so complicated in the code that outputs the above sentences for the [Likes extension](https://github.com/flarum/likes/blob/master/js/forum/src/addLikesList.js).
And the situation is complicated by the presence of the second-person pronoun, since it always takes the plural form in English, even when we're talking about one person. That's why the `app.translator` call is so complicated in the code that outputs the above sentences for the [Likes extension](https://github.com/flarum/likes/blob/master/js/src/forum/addLikesList.js).

Now look at this similar set of sentences, output by similar code in the [Mentions extension](https://github.com/flarum/mentions/blob/master/js/forum/src/addMentionedByList.js):
Now look at this similar set of sentences, output by similar code in the [Mentions extension](https://github.com/flarum/mentions/blob/master/js/src/forum/addMentionedByList.js):

> Toby replied to this.
> You replied to this.
Expand Down
4 changes: 2 additions & 2 deletions docs/extend/interactive-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ More information about methods available to override is available in our [API do

Since Flarum is a forum, we need tools for users to be able to create and edit posts and discussions. Flarum accomplishes this through the floating composer component.

The composer is managed by a global instance of [`ComposerState`]([https://api.docs.flarum.org/js/master/class/src/common/states/modalmanagerstate.js~modalmanagerstate), which is accessible via `app.composer` on the `forum` frontend. Its most important public methods are:
The composer is managed by a global instance of [`ComposerState`](https://api.docs.flarum.org/js/master/class/src/common/states/modalmanagerstate.js~modalmanagerstate), which is accessible via `app.composer` on the `forum` frontend. Its most important public methods are:

- `app.composer.load(componentClass, attrs)` will load in a new composer type. If a composer is already active, it will be replaced.
- `app.composer.show()` will show the composer if it is currently hidden.
Expand All @@ -84,5 +84,5 @@ This is done by splitting code for each usage into a subclass of `flarum/forum/c
### Composer Editor

The actual editor is yet another component, [`flarum/common/components/TextEditor`](https://api.docs.flarum.org/js/master/class/src/common/components/texteditor.js~texteditor).
Its state can be programatically accessed via an "editor driver", which implements [`EditorDriverInterface`](https://github.com/flarum/core/blob/7d79912d3651f49e045302946b99a562f791b730/js/src/common/utils/EditorDriverInterface.ts).
Its state can be programatically accessed via an "editor driver", which implements [`EditorDriverInterface`](https://github.com/flarum/core/blob/master/js/src/common/utils/EditorDriverInterface.ts).
This is globally available for the current composer via `app.composer.editor`, and allows extensions to programatically read, insert, and modify the current contents, selections, and cursor position of the active composer's text editor.
2 changes: 1 addition & 1 deletion docs/extend/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ In addition to registering our notification to send by email, if we actually wan
To do this, your notification blueprint should implement [`Flarum\Notification\MailableInterface`](https://api.docs.flarum.org/php/master/flarum/notification/mailableinterface) in addition to [`Flarum\Notification\Blueprint\BlueprintInterface`](https://api.docs.flarum.org/php/master/flarum/notification/blueprint/blueprintinterface).
This comes with 2 additional methods:

- `getEmailView()` should return an array of email type to [Blade View](https://laravel.com/docs/6.x/blade) names. The namespaces for these views must [first be registered](routes.md#views). These will be used to generate the body of the email.
- `getEmailView()` should return an array of email type to [Blade View](https://laravel.com/docs/8.x/blade) names. The namespaces for these views must [first be registered](routes.md#views). These will be used to generate the body of the email.
- `getEmailSubject(TranslatorInterface $translator)` should return a string for the email subject. An instance of the translator is passed in to enable translated notification emails.

Let's take a look at an example from [Flarum Mentions](https://github.com/flarum/mentions/blob/master/src/Notification/PostMentionedBlueprint.php)
Expand Down
4 changes: 2 additions & 2 deletions docs/extend/routes.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ class HelloWorldController implements RequestHandlerInterface
}
```

Controllers are resolved from the [container](https://laravel.com/docs/6.x/container) so you can inject dependencies into their constructors.
Controllers are resolved from the [container](https://laravel.com/docs/8.x/container) so you can inject dependencies into their constructors.

:::tip What are Controllers?
The `handle` method of a Controller is the code that runs when someone visits your route (or sends data to it via a form submission). Generally speaking, Controller implementations follow the pattern:
Expand Down Expand Up @@ -97,7 +97,7 @@ $url = $this->url->to('forum')->route('acme.user', ['id' => 123, 'foo' => 'bar']

### Views

You can inject Laravel's [View](https://laravel.com/docs/6.x/views) factory into your controller. This will allow you to render a [Blade template](https://laravel.com/docs/6.x/blade) into your controller's response.
You can inject Laravel's [View](https://laravel.com/docs/8.x/views) factory into your controller. This will allow you to render a [Blade template](https://laravel.com/docs/8.x/blade) into your controller's response.

First, you will need to tell the view factory where it can find your extension's view files by adding a `View` extender to `extend.php`:

Expand Down
Loading