Backend cleanup (#2859)

* Extender docblocks cleanup
* Excplicit type hinting in extenders
* Bring method under constructor
* Mark some classes and methods as internal
* Remove beta references

Co-authored-by: Clark Winkelmann <clark.winkelmann@gmail.com>

.github/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported Versions
 
-During the beta phase, we will only patch security vulnerabilities in the latest beta release.
+We will only patch security vulnerabilities in the stable 1.x release.
 
 ## Reporting a Vulnerability
 

src/Api/Controller/AbstractSerializeController.php

@@ -371,6 +371,8 @@ abstract class AbstractSerializeController implements RequestHandlerInterface
 
     /**
      * @param Container $container
+     *
+     * @internal
      */
     public static function setContainer(Container $container)
     {
@@ -380,6 +382,8 @@ abstract class AbstractSerializeController implements RequestHandlerInterface
     /**
      * @param string $controllerClass
      * @param callable $callback
+     *
+     * @internal
      */
     public static function addDataPreparationCallback(string $controllerClass, callable $callback)
     {
@@ -393,6 +397,8 @@ abstract class AbstractSerializeController implements RequestHandlerInterface
     /**
      * @param string $controllerClass
      * @param callable $callback
+     *
+     * @internal
      */
     public static function addSerializationPreparationCallback(string $controllerClass, callable $callback)
     {
@@ -403,6 +409,9 @@ abstract class AbstractSerializeController implements RequestHandlerInterface
         static::$beforeSerializationCallbacks[$controllerClass][] = $callback;
     }
 
+    /**
+     * @internal
+     */
     public static function setLoadRelations(string $controllerClass, array $relations)
     {
         if (! isset(static::$loadRelations[$controllerClass])) {

src/Api/Serializer/AbstractSerializer.php

@@ -274,6 +274,8 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
 
     /**
      * @param Container $container
+     *
+     * @internal
      */
     public static function setContainer(Container $container)
     {
@@ -283,8 +285,10 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
     /**
      * @param string $serializerClass
      * @param callable $callback
+     *
+     * @internal
      */
-    public static function addAttributeMutator(string $serializerClass, callable $callback)
+    public static function addAttributeMutator(string $serializerClass, callable $callback): void
     {
         if (! isset(static::$attributeMutators[$serializerClass])) {
             static::$attributeMutators[$serializerClass] = [];
@@ -297,8 +301,10 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
      * @param string $serializerClass
      * @param string $relation
      * @param callable $callback
+     *
+     * @internal
      */
-    public static function setRelationship(string $serializerClass, string $relation, callable $callback)
+    public static function setRelationship(string $serializerClass, string $relation, callable $callback): void
     {
         static::$customRelations[$serializerClass][$relation] = $callback;
     }

src/Database/AbstractModel.php

@@ -44,10 +44,19 @@ abstract class AbstractModel extends Eloquent
      */
     protected $afterDeleteCallbacks = [];
 
+    /**
+     * @internal
+     */
     public static $customRelations = [];
 
+    /**
+     * @internal
+     */
     public static $dateAttributes = [];
 
+    /**
+     * @internal
+     */
     public static $defaults = [];
 
     /**

src/Database/Migrator.php

@@ -19,6 +19,9 @@ use Illuminate\Filesystem\Filesystem;
 use InvalidArgumentException;
 use Symfony\Component\Console\Output\OutputInterface;
 
+/**
+ * @internal
+ */
 class Migrator
 {
     /**

src/Extend/ApiController.php

@@ -32,7 +32,7 @@ class ApiController implements ExtenderInterface
     private $load = [];
 
     /**
-     * @param string $controllerClass The ::class attribute of the controller you are modifying.
+     * @param string $controllerClass: The ::class attribute of the controller you are modifying.
      *                                This controller should extend from \Flarum\Api\Controller\AbstractSerializeController.
      */
     public function __construct(string $controllerClass)
@@ -48,7 +48,7 @@ class ApiController implements ExtenderInterface
      *
      * @return self
      */
-    public function prepareDataQuery($callback)
+    public function prepareDataQuery($callback): self
     {
         $this->beforeDataCallbacks[] = $callback;
 
@@ -70,7 +70,7 @@ class ApiController implements ExtenderInterface
      *
      * @return self
      */
-    public function prepareDataForSerialization($callback)
+    public function prepareDataForSerialization($callback): self
     {
         $this->beforeSerializationCallbacks[] = $callback;
 
@@ -80,11 +80,18 @@ class ApiController implements ExtenderInterface
     /**
      * Set the serializer that will serialize data for the endpoint.
      *
-     * @param string $serializerClass
+     * @param string $serializerClass: The ::class attribute of the serializer.
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function setSerializer(string $serializerClass, $callback = null)
+    public function setSerializer(string $serializerClass, $callback = null): self
     {
         $this->serializer = [$serializerClass, $callback];
 
@@ -94,11 +101,18 @@ class ApiController implements ExtenderInterface
     /**
      * Include the given relationship by default.
      *
-     * @param string|array $name
+     * @param string|array $name: The name of the relation.
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function addInclude($name, $callback = null)
+    public function addInclude($name, $callback = null): self
     {
         $this->addIncludes[] = [$name, $callback];
 
@@ -108,11 +122,18 @@ class ApiController implements ExtenderInterface
     /**
      * Don't include the given relationship by default.
      *
-     * @param string|array $name
+     * @param string|array $name: The name of the relation.
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function removeInclude($name, $callback = null)
+    public function removeInclude($name, $callback = null): self
     {
         $this->removeIncludes[] = [$name, $callback];
 
@@ -122,11 +143,18 @@ class ApiController implements ExtenderInterface
     /**
      * Make the given relationship available for inclusion.
      *
-     * @param string|array $name
+     * @param string|array $name: The name of the relation.
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function addOptionalInclude($name, $callback = null)
+    public function addOptionalInclude($name, $callback = null): self
     {
         $this->addOptionalIncludes[] = [$name, $callback];
 
@@ -136,11 +164,18 @@ class ApiController implements ExtenderInterface
     /**
      * Don't allow the given relationship to be included.
      *
-     * @param string|array $name
+     * @param string|array $name: The name of the relation.
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function removeOptionalInclude($name, $callback = null)
+    public function removeOptionalInclude($name, $callback = null): self
     {
         $this->removeOptionalIncludes[] = [$name, $callback];
 
@@ -152,9 +187,16 @@ class ApiController implements ExtenderInterface
      *
      * @param int $limit
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function setLimit(int $limit, $callback = null)
+    public function setLimit(int $limit, $callback = null): self
     {
         $this->limit = [$limit, $callback];
 
@@ -166,9 +208,16 @@ class ApiController implements ExtenderInterface
      *
      * @param int $max
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function setMaxLimit(int $max, $callback = null)
+    public function setMaxLimit(int $max, $callback = null): self
     {
         $this->maxLimit = [$max, $callback];
 
@@ -180,9 +229,16 @@ class ApiController implements ExtenderInterface
      *
      * @param string|array $field
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function addSortField($field, $callback = null)
+    public function addSortField($field, $callback = null): self
     {
         $this->addSortFields[] = [$field, $callback];
 
@@ -194,9 +250,16 @@ class ApiController implements ExtenderInterface
      *
      * @param string|array $field
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function removeSortField($field, $callback = null)
+    public function removeSortField($field, $callback = null): self
     {
         $this->removeSortFields[] = [$field, $callback];
 
@@ -208,9 +271,16 @@ class ApiController implements ExtenderInterface
      *
      * @param array $sort
      * @param callable|string|null $callback
+     *
+     * The optional callback can be a closure or an invokable class, and should accept:
+     * - $controller: An instance of this controller.
+     *
+     * The callable should return:
+     * - A boolean value to determine if this applies.
+     *
      * @return self
      */
-    public function setSort(array $sort, $callback = null)
+    public function setSort(array $sort, $callback = null): self
     {
         $this->sort = [$sort, $callback];
 
@@ -228,10 +298,10 @@ class ApiController implements ExtenderInterface
      * To force load the relationship, both levels have to be specified,
      * example: ['relation', 'relation.subRelation'].
      *
-     * @param string|array
+     * @param string|string[] $relations
      * @return self
      */
-    public function load($relations)
+    public function load($relations): self
     {
         $this->load = array_merge($this->load, (array) $relations);
 

src/Extend/ApiSerializer.php

@@ -31,6 +31,8 @@ class ApiSerializer implements ExtenderInterface
     }
 
     /**
+     * Add a single attribute to this serializer.
+     *
      * @param string $name: The name of the attribute.
      * @param callable|string $callback
      *
@@ -44,7 +46,7 @@ class ApiSerializer implements ExtenderInterface
      *
      * @return self
      */
-    public function attribute(string $name, $callback)
+    public function attribute(string $name, $callback): self
     {
         $this->attribute[$name] = $callback;
 
@@ -67,7 +69,7 @@ class ApiSerializer implements ExtenderInterface
      *
      * @return self
      */
-    public function attributes($callback)
+    public function attributes($callback): self
     {
         $this->attributes[] = $callback;
 
@@ -84,7 +86,7 @@ class ApiSerializer implements ExtenderInterface
      *                                 This serializer should extend from \Flarum\Api\Serializer\AbstractSerializer.
      * @return self
      */
-    public function hasOne(string $name, string $serializerClass)
+    public function hasOne(string $name, string $serializerClass): self
     {
         return $this->relationship($name, function (AbstractSerializer $serializer, $model) use ($serializerClass, $name) {
             return $serializer->hasOne($model, $serializerClass, $name);
@@ -101,7 +103,7 @@ class ApiSerializer implements ExtenderInterface
      *                                 This serializer should extend from \Flarum\Api\Serializer\AbstractSerializer.
      * @return self
      */
-    public function hasMany(string $name, string $serializerClass)
+    public function hasMany(string $name, string $serializerClass): self
     {
         return $this->relationship($name, function (AbstractSerializer $serializer, $model) use ($serializerClass, $name) {
             return $serializer->hasMany($model, $serializerClass, $name);
@@ -124,7 +126,7 @@ class ApiSerializer implements ExtenderInterface
      *
      * @return self
      */
-    public function relationship(string $name, $callback)
+    public function relationship(string $name, $callback): self
     {
         $this->relationships[$this->serializerClass][$name] = $callback;
 

src/Extend/Auth.php

@@ -23,17 +23,22 @@ class Auth implements ExtenderInterface
      *
      * @param string $identifier: Unique identifier for password checker.
      * @param callable|string $callback: A closure or invokable class that contains the logic of the password checker.
-     *                                 Arguments are a User $object and string $password.
+     *
-     *                                 It should return:
+     * The callable should accept:
-     *                                   - `true` if the given password is valid.
+     * - $user: An instance of the User model.
-     *                                   - `null` (or not return anything) if the given password is invalid, or this checker does not apply.
+     * - $password: A string.
-     *                                             Generally, `null` should be returned instead of `false` so that other
+     *
-     *                                             password checkers can run.
+     * The callable should return:
-     *                                   - `false` if the given password is invalid, and no other checkers should be considered.
+     * - `true` if the given password is valid.
-     *                                              Evaluation will be immediately halted if any checkers return `false`.
+     * - `null` (or not return anything) if the given password is invalid, or this checker does not apply.
+     *           Generally, `null` should be returned instead of `false` so that other
+     *           password checkers can run.
+     * - `false` if the given password is invalid, and no other checkers should be considered.
+     *            Evaluation will be immediately halted if any checkers return `false`.
+     *
      * @return self
      */
-    public function addPasswordChecker(string $identifier, $callback)
+    public function addPasswordChecker(string $identifier, $callback): self
     {
         $this->addPasswordCheckers[$identifier] = $callback;
 
@@ -46,7 +51,7 @@ class Auth implements ExtenderInterface
      * @param string $identifier: The unique identifier of the password checker to remove.
      * @return self
      */
-    public function removePasswordChecker(string $identifier)
+    public function removePasswordChecker(string $identifier): self
     {
         $this->removePasswordCheckers[] = $identifier;
 

src/Extend/Console.php

@@ -20,9 +20,10 @@ class Console implements ExtenderInterface
     /**
      * Add a command to the console.
      *
-     * @param string $command ::class attribute of command class, which must extend Flarum\Console\AbstractCommand
+     * @param string $command: ::class attribute of command class, which must extend Flarum\Console\AbstractCommand.
+     * @return self
      */
-    public function command($command)
+    public function command(string $command): self
     {
         $this->addCommands[] = $command;
 
@@ -32,7 +33,7 @@ class Console implements ExtenderInterface
     /**
      * Schedule a command to run on an interval.
      *
-     * @param string $command ::class attribute of command class, which must extend Flarum\Console\AbstractCommand
+     * @param string $command: ::class attribute of command class, which must extend Flarum\Console\AbstractCommand.
      * @param callable|string $callback
      *
      * The callback can be a closure or invokable class, and should accept:
@@ -45,8 +46,9 @@ class Console implements ExtenderInterface
      * for more information on available methods and what they do.
      *
      * @param array $args An array of args to call the command with.
+     * @return self
      */
-    public function schedule(string $command, $callback, $args = [])
+    public function schedule(string $command, $callback, $args = []): self
     {
         $this->scheduled[] = compact('args', 'callback', 'command');
 

src/Extend/Csrf.php

@@ -20,8 +20,9 @@ class Csrf implements ExtenderInterface
      * Exempt a named route from CSRF checks.
      *
      * @param string $routeName
+     * @return self
      */
-    public function exemptRoute(string $routeName)
+    public function exemptRoute(string $routeName): self
     {
         $this->csrfExemptRoutes[] = $routeName;
 

src/Extend/ErrorHandling.php

@@ -29,8 +29,12 @@ class ErrorHandling implements ExtenderInterface
      * itself (if it implements {@see \Flarum\Foundation\KnownError}), or
      * explicitly defined by using the {@see type} method (useful for exception
      * classes not under your control).
+     *
+     * @param string $errorType: Type of the error.
+     * @param int $httpStatus: The status code for this error.
+     * @return self
      */
-    public function status(string $errorType, int $httpStatus)
+    public function status(string $errorType, int $httpStatus): self
     {
         $this->statuses[$errorType] = $httpStatus;
 
@@ -45,8 +49,12 @@ class ErrorHandling implements ExtenderInterface
      * interface and define the type there. This method should only be used for
      * third-party exceptions, e.g. when integrating another package that
      * already defines its own exception classes.
+     *
+     * @param string $exceptionClass: The ::class attribute of the exception class.
+     * @param string $errorType: Type of the error.
+     * @return self
      */
-    public function type(string $exceptionClass, string $errorType)
+    public function type(string $exceptionClass, string $errorType): self
     {
         $this->types[$exceptionClass] = $errorType;
 
@@ -66,8 +74,12 @@ class ErrorHandling implements ExtenderInterface
      * returns a {@see \Flarum\Foundation\ErrorHandling\HandledError} instance.
      * Besides the usual type and HTTP status code, such an object can also
      * contain "details" - arbitrary data with more context for to the error.
+     *
+     * @param string $exceptionClass: The ::class attribute of the exception class.
+     * @param string $errorType: The ::class attribute of the handler class.
+     * @return self
      */
-    public function handler(string $exceptionClass, string $handlerClass)
+    public function handler(string $exceptionClass, string $handlerClass): self
     {
         $this->handlers[$exceptionClass] = $handlerClass;
 
@@ -85,8 +97,11 @@ class ErrorHandling implements ExtenderInterface
      *
      * When passing in a reporter class, make sure that it implements the
      * {@see \Flarum\Foundation\ErrorHandling\Reporter} interface.
+     *
+     * @param string $reporterClass: The ::class attribute of the reporter class.
+     * @return self
      */
-    public function reporter(string $reporterClass)
+    public function reporter(string $reporterClass): self
     {
         $this->reporters[] = $reporterClass;
 

src/Extend/Event.php

@@ -21,16 +21,18 @@ class Event implements ExtenderInterface
     /**
      * Add a listener to a domain event dispatched by flarum or a flarum extension.
      *
-     * The listener can either be:
+     * @param string $event: Name of the event, can be the ::class attribute of the event class.
-     *  - a callback function
-     *  - the class attribute of a class with a public `handle` method, which accepts an instance of the event as a parameter
-     *  - an array, where the first argument is an object or class name, and the second argument is the method on the
-     *    first argument that should be executed as the listener
-     *
-     * @param string $event
      * @param callable|string $listener
+     *
+     * The listener can either be:
+     *  - A callback function that accepts an instance of the event as a parameter.
+     *  - The ::class attribute of a class with a public `handle` method, which accepts an instance of the event as a parameter.
+     *  - An array, where the first argument is an object or class name, and the second argument is the method on the
+     *    first argument that should be executed as the listener.
+     *
+     * @return self
      */
-    public function listen(string $event, $listener)
+    public function listen(string $event, $listener): self
     {
         $this->listeners[] = [$event, $listener];
 
@@ -44,9 +46,10 @@ class Event implements ExtenderInterface
      *
      * @see https://laravel.com/docs/8.x/events#writing-event-subscribers
      *
-     * @param string $subscriber: The class attribute of the subscriber class
+     * @param string $subscriber: The ::class attribute of the subscriber class.
+     * @return self
      */
-    public function subscribe(string $subscriber)
+    public function subscribe(string $subscriber): self
     {
         $this->subscribers[] = $subscriber;
 

src/Extend/Filesystem.php

@@ -28,12 +28,16 @@ class Filesystem implements ExtenderInterface
      *
      * To declare a new disk, you must provide default configuration a "local" driver.
      *
-     * @param string $name: The name of the disk
+     * @param string $name: The name of the disk.
-     * @param string|callable $callback: A callback or invokable class name with parameters:
+     * @param string|callable $callback
-     *                           - \Flarum\Foundation\Paths $paths
+     *
-     *                           - \Flarum\Http\UrlGenerator $url
+     * The callback can be a closure or an invokable class, and should accept:
-     *                         which returns a Laravel disk config array.
+     *  - \Flarum\Foundation\Paths $paths
-     *                         The `driver` key is not necessary for this array, and will be ignored.
+     *  - \Flarum\Http\UrlGenerator $url
+     *
+     * The callable should return:
+     * - A Laravel disk config array,
+     *   The `driver` key is not necessary for this array, and will be ignored.
      *
      * @example
      * ```
@@ -46,8 +50,10 @@ class Filesystem implements ExtenderInterface
      * ```
      *
      * @see https://laravel.com/docs/8.x/filesystem#configuration
+     *
+     * @return self
      */
-    public function disk(string $name, $callback)
+    public function disk(string $name, $callback): self
     {
         $this->disks[$name] = $callback;
 
@@ -56,12 +62,13 @@ class Filesystem implements ExtenderInterface
 
     /**
      * Register a new filesystem driver.
-     * Drivers must implement `\Flarum\Filesystem\DriverInterface`.
      *
-     * @param string $name: The name of the driver
+     * @param string $name: The name of the driver.
      * @param string $driverClass: The ::class attribute of the driver.
+     *                             Driver must implement `\Flarum\Filesystem\DriverInterface`.
+     * @return self
      */
-    public function driver(string $name, string $driverClass)
+    public function driver(string $name, string $driverClass): self
     {
         $this->drivers[$name] = $driverClass;
 

src/Extend/Filter.php

@@ -19,7 +19,7 @@ class Filter implements ExtenderInterface
     private $filterMutators = [];
 
     /**
-     * @param string $filtererClass: The ::class attribute of the filterer to extend
+     * @param string $filtererClass: The ::class attribute of the filterer to extend.
      */
     public function __construct($filtererClass)
     {
@@ -30,8 +30,9 @@ class Filter implements ExtenderInterface
      * Add a filter to run when the filtererClass is filtered.
      *
      * @param string $filterClass: The ::class attribute of the filter you are adding.
+     * @return self
      */
-    public function addFilter(string $filterClass)
+    public function addFilter(string $filterClass): self
     {
         $this->filters[] = $filterClass;
 
@@ -46,8 +47,12 @@ class Filter implements ExtenderInterface
      * The callback can be a closure or an invokable class, and should accept:
      * - Flarum\Filter\FilterState $filter
      * - Flarum\Query\QueryCriteria $criteria
+     *
+     * The callable should return void.
+     *
+     * @return self
      */
-    public function addFilterMutator($callback)
+    public function addFilterMutator($callback): self
     {
         $this->filterMutators[] = $callback;
 

src/Extend/Formatter.php

@@ -30,8 +30,12 @@ class Formatter implements ExtenderInterface, LifecycleInterface
      *
      * The callback can be a closure or invokable class, and should accept:
      * - \s9e\TextFormatter\Configurator $configurator
+     *
+     * The callable should return void.
+     *
+     * @return self
      */
-    public function configure($callback)
+    public function configure($callback): self
     {
         $this->configurationCallbacks[] = $callback;
 
@@ -51,8 +55,10 @@ class Formatter implements ExtenderInterface, LifecycleInterface
      *
      * The callback should return:
      * - string $text: The text to be parsed.
+     *
+     * @return self
      */
-    public function parse($callback)
+    public function parse($callback): self
     {
         $this->parsingCallbacks[] = $callback;
 
@@ -74,7 +80,7 @@ class Formatter implements ExtenderInterface, LifecycleInterface
      *
      * @return self
      */
-    public function unparse($callback)
+    public function unparse($callback): self
     {
         $this->unparsingCallbacks[] = $callback;
 
@@ -95,8 +101,10 @@ class Formatter implements ExtenderInterface, LifecycleInterface
      *
      * The callback should return:
      * - string $xml: The xml to be rendered.
+     *
+     * @return self
      */
-    public function render($callback)
+    public function render($callback): self
     {
         $this->renderingCallbacks[] = $callback;
 

src/Extend/Frontend.php

@@ -34,33 +34,70 @@ class Frontend implements ExtenderInterface
     private $removedRoutes = [];
     private $content = [];
 
+    /**
+     * @param string $frontend: The name of the frontend.
+     */
     public function __construct(string $frontend)
     {
         $this->frontend = $frontend;
     }
 
-    public function css(string $path)
+    /**
+     * Add a CSS file to load in the frontend.
+     *
+     * @param string $path: The path to the CSS file.
+     * @return self
+     */
+    public function css(string $path): self
     {
         $this->css[] = $path;
 
         return $this;
     }
 
-    public function js(string $path)
+    /**
+     * Add a JavaScript file to load in the frontend.
+     *
+     * @param string $path: The path to the JavaScript file.
+     * @return self
+     */
+    public function js(string $path): self
     {
         $this->js = $path;
 
         return $this;
     }
 
-    public function route(string $path, string $name, $content = null)
+    /**
+     * Add a route to the frontend.
+     *
+     * @param string $path: The path of the route.
+     * @param string $name: The name of the route, must be unique.
+     * @param callable|string|null $content
+     *
+     * The content can be a closure or an invokable class, and should accept:
+     * - \Flarum\Frontend\Document $document
+     * - \Psr\Http\Message\ServerRequestInterface $request
+     *
+     * The callable should return void.
+     *
+     * @return self
+     */
+    public function route(string $path, string $name, $content = null): self
     {
         $this->routes[] = compact('path', 'name', 'content');
 
         return $this;
     }
 
-    public function removeRoute(string $name)
+    /**
+     * Remove a route from the frontend.
+     * This is necessary before overriding a route.
+     *
+     * @param string $name: The name of the route.
+     * @return self
+     */
+    public function removeRoute(string $name): self
     {
         $this->removedRoutes[] = $name;
 
@@ -68,10 +105,19 @@ class Frontend implements ExtenderInterface
     }
 
     /**
-     * @param callable|string $callback
+     * Modify the content of the frontend.
-     * @return $this
+     *
+     * @param callable|string|null $content
+     *
+     * The content can be a closure or an invokable class, and should accept:
+     * - \Flarum\Frontend\Document $document
+     * - \Psr\Http\Message\ServerRequestInterface $request
+     *
+     * The callable should return void.
+     *
+     * @return self
      */
-    public function content($callback)
+    public function content($callback): self
     {
         $this->content[] = $callback;
 
@@ -85,7 +131,7 @@ class Frontend implements ExtenderInterface
         $this->registerContent($container);
     }
 
-    private function registerAssets(Container $container, string $moduleName)
+    private function registerAssets(Container $container, string $moduleName): void
     {
         if (empty($this->css) && empty($this->js)) {
             return;
@@ -147,7 +193,7 @@ class Frontend implements ExtenderInterface
         }
     }
 
-    private function registerRoutes(Container $container)
+    private function registerRoutes(Container $container): void
     {
         if (empty($this->routes) && empty($this->removedRoutes)) {
             return;
@@ -174,7 +220,7 @@ class Frontend implements ExtenderInterface
         );
     }
 
-    private function registerContent(Container $container)
+    private function registerContent(Container $container): void
     {
         if (empty($this->content)) {
             return;

src/Extend/LanguagePack.php

@@ -31,7 +31,7 @@ class LanguagePack implements ExtenderInterface, LifecycleInterface
     /**
      * LanguagePack constructor.
      *
-     * @param string|null $path Path to yaml language files.
+     * @param string|null $path: Path to yaml language files.
      */
     public function __construct(string $path = '/locale')
     {

src/Extend/Locales.php

@@ -19,7 +19,10 @@ class Locales implements ExtenderInterface, LifecycleInterface
 {
     private $directory;
 
-    public function __construct($directory)
+    /**
+     * @param string $directory: Directory of the locale files.
+     */
+    public function __construct(string $directory)
     {
         $this->directory = $directory;
     }

src/Extend/Mail.php

@@ -19,10 +19,11 @@ class Mail implements ExtenderInterface
     /**
      * Add a mail driver.
      *
-     * @param string $identifier Identifier for mail driver. E.g. 'smtp' for SmtpDriver
+     * @param string $identifier: Identifier for mail driver. E.g. 'smtp' for SmtpDriver.
-     * @param string $driver ::class attribute of driver class, which must implement Flarum\Mail\DriverInterface
+     * @param string $driver: ::class attribute of driver class, which must implement Flarum\Mail\DriverInterface.
+     * @return self
      */
-    public function driver(string $identifier, $driver)
+    public function driver(string $identifier, string $driver): self
     {
         $this->drivers[$identifier] = $driver;
 

src/Extend/Middleware.php

@@ -21,40 +21,83 @@ class Middleware implements ExtenderInterface
     private $insertAfterMiddlewares = [];
     private $frontend;
 
+    /**
+     * @param string $frontend: The name of the frontend.
+     */
     public function __construct(string $frontend)
     {
         $this->frontend = $frontend;
     }
 
-    public function add($middleware)
+    /**
+     * Adds a new middleware to the frontend.
+     *
+     * @param string $middleware: ::class attribute of the middleware class.
+     *                            Must implement \Psr\Http\Server\MiddlewareInterface.
+     * @return self
+     */
+    public function add(string $middleware): self
     {
         $this->addMiddlewares[] = $middleware;
 
         return $this;
     }
 
-    public function replace($originalMiddleware, $newMiddleware)
+    /**
+     * Replaces an existing middleware of the frontend.
+     *
+     * @param string $originalMiddleware: ::class attribute of the original middleware class.
+     *                                    Or container binding name.
+     * @param string $middleware: ::class attribute of the middleware class.
+     *                            Must implement \Psr\Http\Server\MiddlewareInterface.
+     * @return self
+     */
+    public function replace(string $originalMiddleware, string $newMiddleware): self
     {
         $this->replaceMiddlewares[$originalMiddleware] = $newMiddleware;
 
         return $this;
     }
 
-    public function remove($middleware)
+    /**
+     * Removes a middleware from the frontend.
+     *
+     * @param string $middleware: ::class attribute of the middleware class.
+     * @return self
+     */
+    public function remove(string $middleware): self
     {
         $this->removeMiddlewares[] = $middleware;
 
         return $this;
     }
 
-    public function insertBefore($originalMiddleware, $newMiddleware)
+    /**
+     * Inserts a middleware before an existing middleware.
+     *
+     * @param string $originalMiddleware: ::class attribute of the original middleware class.
+     *                                    Or container binding name.
+     * @param string $middleware: ::class attribute of the middleware class.
+     *                            Must implement \Psr\Http\Server\MiddlewareInterface.
+     * @return self
+     */
+    public function insertBefore(string $originalMiddleware, string $newMiddleware): self
     {
         $this->insertBeforeMiddlewares[$originalMiddleware] = $newMiddleware;
 
         return $this;
     }
 
-    public function insertAfter($originalMiddleware, $newMiddleware)
+    /**
+     * Inserts a middleware after an existing middleware.
+     *
+     * @param string $originalMiddleware: ::class attribute of the original middleware class.
+     *                                    Or container binding name.
+     * @param string $middleware: ::class attribute of the middleware class.
+     *                            Must implement \Psr\Http\Server\MiddlewareInterface.
+     * @return self
+     */
+    public function insertAfter(string $originalMiddleware, string $newMiddleware): self
     {
         $this->insertAfterMiddlewares[$originalMiddleware] = $newMiddleware;
 

src/Extend/Model.php

@@ -21,7 +21,7 @@ class Model implements ExtenderInterface
     private $customRelations = [];
 
     /**
-     * @param string $modelClass The ::class attribute of the model you are modifying.
+     * @param string $modelClass: The ::class attribute of the model you are modifying.
      *                           This model should extend from \Flarum\Database\AbstractModel.
      */
     public function __construct(string $modelClass)
@@ -35,7 +35,7 @@ class Model implements ExtenderInterface
      * @param string $attribute
      * @return self
      */
-    public function dateAttribute(string $attribute)
+    public function dateAttribute(string $attribute): self
     {
         Arr::set(
             AbstractModel::$dateAttributes,
@@ -58,7 +58,7 @@ class Model implements ExtenderInterface
      * @param mixed $value
      * @return self
      */
-    public function default(string $attribute, $value)
+    public function default(string $attribute, $value): self
     {
         Arr::set(AbstractModel::$defaults, "$this->modelClass.$attribute", $value);
 
@@ -78,7 +78,7 @@ class Model implements ExtenderInterface
      * @param string $ownerKey: The primary key attribute of the parent model.
      * @return self
      */
-    public function belongsTo(string $name, string $related, string $foreignKey = null, string $ownerKey = null)
+    public function belongsTo(string $name, string $related, string $foreignKey = null, string $ownerKey = null): self
     {
         return $this->relationship($name, function (AbstractModel $model) use ($related, $foreignKey, $ownerKey, $name) {
             return $model->belongsTo($related, $foreignKey, $ownerKey, $name);
@@ -109,7 +109,7 @@ class Model implements ExtenderInterface
         string $relatedPivotKey = null,
         string $parentKey = null,
         string $relatedKey = null
-    ) {
+    ): self {
         return $this->relationship($name, function (AbstractModel $model) use ($related, $table, $foreignPivotKey, $relatedPivotKey, $parentKey, $relatedKey, $name) {
             return $model->belongsToMany($related, $table, $foreignPivotKey, $relatedPivotKey, $parentKey, $relatedKey, $name);
         });
@@ -128,7 +128,7 @@ class Model implements ExtenderInterface
      * @param string $localKey: The primary key attribute of the parent model.
      * @return self
      */
-    public function hasOne(string $name, string $related, string $foreignKey = null, string $localKey = null)
+    public function hasOne(string $name, string $related, string $foreignKey = null, string $localKey = null): self
     {
         return $this->relationship($name, function (AbstractModel $model) use ($related, $foreignKey, $localKey) {
             return $model->hasOne($related, $foreignKey, $localKey);
@@ -148,7 +148,7 @@ class Model implements ExtenderInterface
      * @param string $localKey: The primary key attribute of the parent model.
      * @return self
      */
-    public function hasMany(string $name, string $related, string $foreignKey = null, string $localKey = null)
+    public function hasMany(string $name, string $related, string $foreignKey = null, string $localKey = null): self
     {
         return $this->relationship($name, function (AbstractModel $model) use ($related, $foreignKey, $localKey) {
             return $model->hasMany($related, $foreignKey, $localKey);
@@ -172,7 +172,7 @@ class Model implements ExtenderInterface
      *
      * @return self
      */
-    public function relationship(string $name, $callback)
+    public function relationship(string $name, $callback): self
     {
         $this->customRelations[$name] = $callback;
 

src/Extend/ModelPrivate.php

@@ -37,7 +37,7 @@ class ModelPrivate implements ExtenderInterface
     private $checkers = [];
 
     /**
-     * @param string $modelClass The ::class attribute of the model you are applying private checkers to.
+     * @param string $modelClass: The ::class attribute of the model you are applying private checkers to.
      *                           This model must have a `is_private` field.
      */
     public function __construct(string $modelClass)
@@ -57,7 +57,7 @@ class ModelPrivate implements ExtenderInterface
      *
      * @return self
      */
-    public function checker($callback)
+    public function checker($callback): self
     {
         $this->checkers[] = $callback;
 

src/Extend/ModelUrl.php

@@ -19,7 +19,7 @@ class ModelUrl implements ExtenderInterface
     private $slugDrivers = [];
 
     /**
-     * @param string $modelClass The ::class attribute of the model you are modifying.
+     * @param string $modelClass: The ::class attribute of the model you are modifying.
      *                           This model should extend from \Flarum\Database\AbstractModel.
      */
     public function __construct(string $modelClass)
@@ -30,11 +30,11 @@ class ModelUrl implements ExtenderInterface
     /**
      * Add a slug driver.
      *
-     * @param string $identifier Identifier for slug driver.
+     * @param string $identifier: Identifier for slug driver.
-     * @param string $driver ::class attribute of driver class, which must implement Flarum\Http\SlugDriverInterface
+     * @param string $driver: ::class attribute of driver class, which must implement Flarum\Http\SlugDriverInterface.
      * @return self
      */
-    public function addSlugDriver(string $identifier, string $driver)
+    public function addSlugDriver(string $identifier, string $driver): self
     {
         $this->slugDrivers[$identifier] = $driver;
 

src/Extend/ModelVisibility.php

@@ -36,7 +36,7 @@ class ModelVisibility implements ExtenderInterface
     private $allScopers = [];
 
     /**
-     * @param string $modelClass The ::class attribute of the model you are applying scopers to.
+     * @param string $modelClass: The ::class attribute of the model you are applying scopers to.
      *                           This model must extend from \Flarum\Database\AbstractModel,
      *                           and use \Flarum\Database\ScopeVisibilityTrait.
      */
@@ -53,15 +53,17 @@ class ModelVisibility implements ExtenderInterface
      * Add a scoper for a given ability.
      *
      * @param callable|string $callback
-     * @param string $ability, defaults to 'view'
+     * @param string $ability: Defaults to 'view'.
      *
      * The callback can be a closure or invokable class, and should accept:
      * - \Flarum\User\User $actor
      * - \Illuminate\Database\Eloquent\Builder $query
      *
+     * The callback should return void.
+     *
      * @return self
      */
-    public function scope($callback, $ability = 'view')
+    public function scope($callback, string $ability = 'view'): self
     {
         $this->scopers[$ability][] = $callback;
 
@@ -78,9 +80,11 @@ class ModelVisibility implements ExtenderInterface
      * - \Illuminate\Database\Eloquent\Builder $query
      * - string $ability
      *
+     * The callback should return void.
+     *
      * @return self
      */
-    public function scopeAll($callback)
+    public function scopeAll($callback): self
     {
         $this->allScopers[] = $callback;
 

src/Extend/Notification.php

@@ -23,15 +23,15 @@ class Notification implements ExtenderInterface
     private $beforeSendingCallbacks = [];
 
     /**
-     * @param string $blueprint The ::class attribute of the blueprint class.
+     * @param string $blueprint: The ::class attribute of the blueprint class.
      *                          This blueprint should implement \Flarum\Notification\Blueprint\BlueprintInterface.
-     * @param string $serializer The ::class attribute of the serializer class.
+     * @param string $serializer: The ::class attribute of the serializer class.
      *                           This serializer should extend from \Flarum\Api\Serializer\AbstractSerializer.
-     * @param string[] $driversEnabledByDefault The names of the drivers enabled by default for this notification type.
+     * @param string[] $driversEnabledByDefault: The names of the drivers enabled by default for this notification type.
      *                                       (example: alert, email).
      * @return self
      */
-    public function type(string $blueprint, string $serializer, array $driversEnabledByDefault = [])
+    public function type(string $blueprint, string $serializer, array $driversEnabledByDefault = []): self
     {
         $this->blueprints[$blueprint] = $driversEnabledByDefault;
         $this->serializers[$blueprint::getType()] = $serializer;
@@ -40,13 +40,13 @@ class Notification implements ExtenderInterface
     }
 
     /**
-     * @param string $driverName The name of the notification driver.
+     * @param string $driverName: The name of the notification driver.
-     * @param string $driver The ::class attribute of the driver class.
+     * @param string $driver: The ::class attribute of the driver class.
      *                       This driver should implement \Flarum\Notification\Driver\NotificationDriverInterface.
-     * @param string[] $typesEnabledByDefault The names of blueprint classes of types enabled by default for this driver.
+     * @param string[] $typesEnabledByDefault: The names of blueprint classes of types enabled by default for this driver.
      * @return self
      */
-    public function driver(string $driverName, string $driver, array $typesEnabledByDefault = [])
+    public function driver(string $driverName, string $driver, array $typesEnabledByDefault = []): self
     {
         $this->drivers[$driverName] = $driver;
         $this->typesEnabledByDefault[$driverName] = $typesEnabledByDefault;
@@ -56,9 +56,17 @@ class Notification implements ExtenderInterface
 
     /**
      * @param callable|string $callback
+     *
+     * The callback can be a closure or an invokable class, and should accept:
+     * - \Flarum\Notification\Blueprint\BlueprintInterface $blueprint
+     * - \Flarum\User\User[] $newRecipients
+     *
+     * The callable should return an array of recipients.
+     * - \Flarum\User\User[] $newRecipients
+     *
      * @return self
      */
-    public function beforeSending($callback)
+    public function beforeSending($callback): self
     {
         $this->beforeSendingCallbacks[] = $callback;
 

src/Extend/Policy.php

@@ -21,9 +21,10 @@ class Policy implements ExtenderInterface
     /**
      * Add a custom policy for when an ability check is ran without a model instance.
      *
-     * @param string $policy ::class attribute of policy class, which must extend Flarum\User\Access\AbstractPolicy
+     * @param string $policy: ::class attribute of policy class, which must extend Flarum\User\Access\AbstractPolicy
+     * @return self
      */
-    public function globalPolicy(string $policy)
+    public function globalPolicy(string $policy): self
     {
         $this->globalPolicies[] = $policy;
 
@@ -33,11 +34,12 @@ class Policy implements ExtenderInterface
     /**
      * Add a custom policy for when an ability check is ran on an instance of a model.
      *
-     * @param string $modelClass The ::class attribute of the model you are applying policies to.
+     * @param string $modelClass: The ::class attribute of the model you are applying policies to.
      *                           This model should extend from \Flarum\Database\AbstractModel.
-     * @param string $policy ::class attribute of policy class, which must extend Flarum\User\Access\AbstractPolicy
+     * @param string $policy: ::class attribute of policy class, which must extend Flarum\User\Access\AbstractPolicy
+     * @return self
      */
-    public function modelPolicy(string $modelClass, string $policy)
+    public function modelPolicy(string $modelClass, string $policy): self
     {
         if (! array_key_exists($modelClass, $this->modelPolicies)) {
             $this->modelPolicies[$modelClass] = [];

src/Extend/Post.php

@@ -22,8 +22,9 @@ class Post implements ExtenderInterface
      * such as those that appear when a discussion is renamed.
      *
      * @param string $postType: The ::class attribute of the custom Post type that is being added.
+     * @return self
      */
-    public function type(string $postType)
+    public function type(string $postType): self
     {
         $this->postTypes[] = $postType;
 

src/Extend/Routes.php

@@ -21,37 +21,135 @@ class Routes implements ExtenderInterface
     private $routes = [];
     private $removedRoutes = [];
 
-    public function __construct($appName)
+    /**
+     * @param string $appName: Name of the app (api, forum, admin).
+     */
+    public function __construct(string $appName)
     {
         $this->appName = $appName;
     }
 
-    public function get($path, $name, $handler)
+    /**
+     * Add a GET route.
+     *
+     * @param string $path: The path of the route
+     * @param string $name: The name of the route, must be unique.
+     * @param callable|string $handler: ::class attribute of the controller class, or a closure.
+     *
+     * If the handler is a controller class, it should implement \Psr\Http\Server\RequestHandlerInterface,
+     * or extend one of the Flarum Api controllers within \Flarum\Api\Controller.
+     *
+     * The handler should accept:
+     * - \Psr\Http\Message\ServerRequestInterface $request
+     * - \Tobscure\JsonApi\Document $document: If it extends one of the Flarum Api controllers.
+     *
+     * The handler should return:
+     * - \Psr\Http\Message\ResponseInterface $response
+     *
+     * @return self
+     */
+    public function get(string $path, string $name, $handler): self
     {
         return $this->route('GET', $path, $name, $handler);
     }
 
-    public function post($path, $name, $handler)
+    /**
+     * Add a POST route.
+     *
+     * @param string $path: The path of the route
+     * @param string $name: The name of the route, must be unique.
+     * @param callable|string $handler: ::class attribute of the controller class, or a closure.
+     *
+     * If the handler is a controller class, it should implement \Psr\Http\Server\RequestHandlerInterface,
+     * or extend one of the Flarum Api controllers within \Flarum\Api\Controller.
+     *
+     * The handler should accept:
+     * - \Psr\Http\Message\ServerRequestInterface $request
+     * - \Tobscure\JsonApi\Document $document: If it extends one of the Flarum Api controllers.
+     *
+     * The handler should return:
+     * - \Psr\Http\Message\ResponseInterface $response
+     *
+     * @return self
+     */
+    public function post(string $path, string $name, $handler): self
     {
         return $this->route('POST', $path, $name, $handler);
     }
 
-    public function put($path, $name, $handler)
+    /**
+     * Add a PUT route.
+     *
+     * @param string $path: The path of the route
+     * @param string $name: The name of the route, must be unique.
+     * @param callable|string $handler: ::class attribute of the controller class, or a closure.
+     *
+     * If the handler is a controller class, it should implement \Psr\Http\Server\RequestHandlerInterface,
+     * or extend one of the Flarum Api controllers within \Flarum\Api\Controller.
+     *
+     * The handler should accept:
+     * - \Psr\Http\Message\ServerRequestInterface $request
+     * - \Tobscure\JsonApi\Document $document: If it extends one of the Flarum Api controllers.
+     *
+     * The handler should return:
+     * - \Psr\Http\Message\ResponseInterface $response
+     *
+     * @return self
+     */
+    public function put(string $path, string $name, $handler): self
     {
         return $this->route('PUT', $path, $name, $handler);
     }
 
-    public function patch($path, $name, $handler)
+    /**
+     * Add a PATCH route.
+     *
+     * @param string $path: The path of the route
+     * @param string $name: The name of the route, must be unique.
+     * @param callable|string $handler: ::class attribute of the controller class, or a closure.
+     *
+     * If the handler is a controller class, it should implement \Psr\Http\Server\RequestHandlerInterface,
+     * or extend one of the Flarum Api controllers within \Flarum\Api\Controller.
+     *
+     * The handler should accept:
+     * - \Psr\Http\Message\ServerRequestInterface $request
+     * - \Tobscure\JsonApi\Document $document: If it extends one of the Flarum Api controllers.
+     *
+     * The handler should return:
+     * - \Psr\Http\Message\ResponseInterface $response
+     *
+     * @return self
+     */
+    public function patch(string $path, string $name, $handler): self
     {
         return $this->route('PATCH', $path, $name, $handler);
     }
 
-    public function delete($path, $name, $handler)
+    /**
+     * Add a DELETE route.
+     *
+     * @param string $path: The path of the route
+     * @param string $name: The name of the route, must be unique.
+     * @param callable|string $handler: ::class attribute of the controller class, or a closure.
+     *
+     * If the handler is a controller class, it should implement \Psr\Http\Server\RequestHandlerInterface,
+     * or extend one of the Flarum Api controllers within \Flarum\Api\Controller.
+     *
+     * The handler should accept:
+     * - \Psr\Http\Message\ServerRequestInterface $request
+     * - \Tobscure\JsonApi\Document $document: If it extends one of the Flarum Api controllers.
+     *
+     * The handler should return:
+     * - \Psr\Http\Message\ResponseInterface $response
+     *
+     * @return self
+     */
+    public function delete(string $path, string $name, $handler): self
     {
         return $this->route('DELETE', $path, $name, $handler);
     }
 
-    private function route($httpMethod, $path, $name, $handler)
+    private function route(string $httpMethod, string $path, string $name, $handler): self
     {
         $this->routes[] = [
             'method' => $httpMethod,
@@ -63,7 +161,14 @@ class Routes implements ExtenderInterface
         return $this;
     }
 
-    public function remove(string $name)
+    /**
+     * Remove an existing route.
+     * Necessary before overriding a route.
+     *
+     * @param string $name: The name of the route.
+     * @return self
+     */
+    public function remove(string $name): self
     {
         $this->removedRoutes[] = $name;
 

src/Extend/ServiceProvider.php

@@ -19,10 +19,14 @@ class ServiceProvider implements ExtenderInterface
     /**
      * Register a service provider.
      *
+     * Service providers are an advanced feature and might give access to Flarum internals that do not come with backward compatibility.
+     * Please read our documentation about service providers for recommendations.
+     * @see https://docs.flarum.org/extend/service-provider.html
+     *
      * @param string $serviceProviderClass The ::class attribute of the service provider class.
      * @return self
      */
-    public function register(string $serviceProviderClass)
+    public function register(string $serviceProviderClass): self
     {
         $this->providers[] = $serviceProviderClass;
 

src/Extend/Settings.php

@@ -26,10 +26,17 @@ class Settings implements ExtenderInterface
      * @param string $attributeName: The attribute name to be used in the ForumSerializer attributes array.
      * @param string $key: The key of the setting.
      * @param string|callable|null $callback: Optional callback to modify the value before serialization.
+     *
+     * The callback can be a closure or an invokable class, and should accept:
+     * - mixed $value: The value of the setting.
+     *
+     * The callable should return:
+     * - mixed $value: The modified value.
+     *
      * @param mixed $default: Optional default serialized value. Will be run through the optional callback.
-     * @return $this
+     * @return self
      */
-    public function serializeToForum(string $attributeName, string $key, $callback = null, $default = null)
+    public function serializeToForum(string $attributeName, string $key, $callback = null, $default = null): self
     {
         $this->settings[$key] = compact('attributeName', 'callback', 'default');
 

src/Extend/SimpleFlarumSearch.php

@@ -23,7 +23,7 @@ class SimpleFlarumSearch implements ExtenderInterface
      * @param string $searcherClass: The ::class attribute of the Searcher you are modifying.
      *                               This searcher must extend \Flarum\Search\AbstractSearcher.
      */
-    public function __construct($searcherClass)
+    public function __construct(string $searcherClass)
     {
         $this->searcher = $searcherClass;
     }
@@ -33,8 +33,9 @@ class SimpleFlarumSearch implements ExtenderInterface
      *
      * @param string $gambitClass: The ::class attribute of the gambit you are adding.
      *                             This gambit must extend \Flarum\Search\AbstractRegexGambit
+     * @return self
      */
-    public function addGambit($gambitClass)
+    public function addGambit(string $gambitClass): self
     {
         $this->gambits[] = $gambitClass;
 
@@ -46,8 +47,9 @@ class SimpleFlarumSearch implements ExtenderInterface
      *
      * @param string $gambitClass: The ::class attribute of the full test gambit you are adding.
      *                             This gambit must implement \Flarum\Search\GambitInterface
+     * @return self
      */
-    public function setFullTextGambit($gambitClass)
+    public function setFullTextGambit(string $gambitClass): self
     {
         $this->fullTextGambit = $gambitClass;
 
@@ -60,10 +62,14 @@ class SimpleFlarumSearch implements ExtenderInterface
      * @param callable|string $callback
      *
      * The callback can be a closure or an invokable class, and should accept:
-     * - Flarum\Search\SearchState $search
+     * - \Flarum\Search\SearchState $search
-     * - Flarum\Query\QueryCriteria $criteria
+     * - \Flarum\Query\QueryCriteria $criteria
+     *
+     * The callback should return void.
+     *
+     * @return self
      */
-    public function addSearchMutator($callback)
+    public function addSearchMutator($callback): self
     {
         $this->searchMutators[] = $callback;
 

src/Extend/ThrottleApi.php

@@ -38,7 +38,7 @@ class ThrottleApi implements ExtenderInterface
      *
      * @return self
      */
-    public function set(string $name, $callback)
+    public function set(string $name, $callback): self
     {
         $this->setThrottlers[$name] = $callback;
 
@@ -49,10 +49,9 @@ class ThrottleApi implements ExtenderInterface
      * Remove a throttler registered with this name.
      *
      * @param string $name: The name of the throttler to remove.
-     *
      * @return self
      */
-    public function remove(string $name)
+    public function remove(string $name): self
     {
         $this->removeThrottlers[] = $name;
 

src/Extend/User.php

@@ -22,10 +22,11 @@ class User implements ExtenderInterface
     /**
      * Add a display name driver.
      *
-     * @param string $identifier Identifier for display name driver. E.g. 'username' for UserNameDriver
+     * @param string $identifier: Identifier for display name driver. E.g. 'username' for UserNameDriver
-     * @param string $driver ::class attribute of driver class, which must implement Flarum\User\DisplayName\DriverInterface
+     * @param string $driver: ::class attribute of driver class, which must implement Flarum\User\DisplayName\DriverInterface
+     * @return self
      */
-    public function displayNameDriver(string $identifier, $driver)
+    public function displayNameDriver(string $identifier, string $driver): self
     {
         $this->displayNameDrivers[$identifier] = $driver;
 
@@ -45,8 +46,10 @@ class User implements ExtenderInterface
      *
      * The callable should return:
      * - array $groupIds: an array of ids for the groups the user belongs to.
+     *
+     * @return self
      */
-    public function permissionGroups($callback)
+    public function permissionGroups($callback): self
     {
         $this->groupProcessors[] = $callback;
 
@@ -58,9 +61,10 @@ class User implements ExtenderInterface
      *
      * @param string $key
      * @param callable $transformer
-     * @param $default
+     * @param mixed|null $default
+     * @return self
      */
-    public function registerPreference(string $key, callable $transformer = null, $default = null)
+    public function registerPreference(string $key, callable $transformer = null, $default = null): self
     {
         $this->preferences[$key] = compact('transformer', 'default');
 

src/Extend/Validator.php

@@ -22,7 +22,7 @@ class Validator implements ExtenderInterface
      * @param string $validatorClass: The ::class attribute of the validator you are modifying.
      *                                The validator should inherit from \Flarum\Foundation\AbstractValidator.
      */
-    public function __construct($validatorClass)
+    public function __construct(string $validatorClass)
     {
         $this->validator = $validatorClass;
     }
@@ -31,13 +31,17 @@ class Validator implements ExtenderInterface
      * Configure the validator. This is often used to adjust validation rules, but can be
      * used to make other changes to the validator as well.
      *
-     * @param callable $callable
+     * @param callable $callback
      *
-     * The callable can be a closure or invokable class, and should accept:
+     * The callback can be a closure or invokable class, and should accept:
      * - \Flarum\Foundation\AbstractValidator $flarumValidator: The Flarum validator wrapper
      * - \Illuminate\Validation\Validator $validator: The Laravel validator instance
+     *
+     * The callback should return void.
+     *
+     * @return self
      */
-    public function configure($callback)
+    public function configure($callback): self
     {
         $this->configurationCallbacks[] = $callback;
 

src/Extend/View.php

@@ -30,11 +30,11 @@ class View implements ExtenderInterface, LifecycleInterface
      * You can also pass variables into a view: for more information, see https://laravel.com/api/8.x/Illuminate/View/Factory.html#method_make
      *
      * @param  string  $namespace: The name of the namespace.
-     * @param  string|array  $hints: This is a path (or an array of paths) to the folder(s)
+     * @param  string|string[]  $hints: This is a path (or an array of paths) to the folder(s)
      *                               where view files are stored, relative to the extend.php file.
-     * @return $this
+     * @return self
      */
-    public function namespace($namespace, $hints)
+    public function namespace(string $namespace, $hints): self
     {
         $this->namespaces[$namespace] = $hints;
 

src/Extension/Extension.php

@@ -50,14 +50,6 @@ class Extension implements Arrayable
         'jpg' => 'image/jpeg',
     ];
 
-    protected static function nameToId($name)
-    {
-        [$vendor, $package] = explode('/', $name);
-        $package = str_replace(['flarum-ext-', 'flarum-'], '', $package);
-
-        return "$vendor-$package";
-    }
-
     /**
      * Unique Id of the extension.
      *
@@ -122,6 +114,14 @@ class Extension implements Arrayable
         $this->assignId();
     }
 
+    protected static function nameToId($name)
+    {
+        [$vendor, $package] = explode('/', $name);
+        $package = str_replace(['flarum-ext-', 'flarum-'], '', $package);
+
+        return "$vendor-$package";
+    }
+
     /**
      * Assigns the id for the extension used globally.
      */
@@ -130,6 +130,9 @@ class Extension implements Arrayable
         $this->id = static::nameToId($this->name);
     }
 
+    /**
+     * @internal
+     */
     public function extend(Container $container)
     {
         foreach ($this->getExtenders() as $extender) {
@@ -173,6 +176,8 @@ class Extension implements Arrayable
     /**
      * @param bool $installed
      * @return Extension
+     *
+     * @internal
      */
     public function setInstalled($installed)
     {
@@ -192,6 +197,8 @@ class Extension implements Arrayable
     /**
      * @param string $version
      * @return Extension
+     *
+     * @internal
      */
     public function setVersion($version)
     {
@@ -208,6 +215,8 @@ class Extension implements Arrayable
      *                             are flarum extensions.
      * @param array $enabledIds:   An associative array where keys are the composer package names
      *                             of enabled extensions. Used to figure out optional dependencies.
+     *
+     * @internal
      */
     public function calculateDependencies($extensionSet, $enabledIds)
     {
@@ -270,6 +279,9 @@ class Extension implements Arrayable
         return $icon;
     }
 
+    /**
+     * @internal
+     */
     public function enable(Container $container)
     {
         foreach ($this->getLifecycleExtenders() as $extender) {
@@ -277,6 +289,9 @@ class Extension implements Arrayable
         }
     }
 
+    /**
+     * @internal
+     */
     public function disable(Container $container)
     {
         foreach ($this->getLifecycleExtenders() as $extender) {
@@ -425,6 +440,9 @@ class Extension implements Arrayable
         return realpath($this->path.'/assets/') !== false;
     }
 
+    /**
+     * @internal
+     */
     public function copyAssetsTo(FilesystemInterface $target)
     {
         if (! $this->hasAssets()) {
@@ -451,6 +469,9 @@ class Extension implements Arrayable
         return realpath($this->path.'/migrations/') !== false;
     }
 
+    /**
+     * @internal
+     */
     public function migrate(Migrator $migrator, $direction = 'up')
     {
         if (! $this->hasMigrations()) {

src/Extension/ExtensionManager.php

@@ -154,6 +154,8 @@ class ExtensionManager
      * Enables the extension.
      *
      * @param string $name
+     *
+     * @internal
      */
     public function enable($name)
     {
@@ -194,6 +196,8 @@ class ExtensionManager
      * Disables an extension.
      *
      * @param string $name
+     *
+     * @internal
      */
     public function disable($name)
     {
@@ -230,6 +234,7 @@ class ExtensionManager
      * Uninstalls an extension.
      *
      * @param string $name
+     * @internal
      */
     public function uninstall($name)
     {
@@ -294,6 +299,8 @@ class ExtensionManager
      * @param Extension $extension
      * @param string $direction
      * @return void
+     *
+     * @internal
      */
     public function migrate(Extension $extension, $direction = 'up')
     {
@@ -309,6 +316,8 @@ class ExtensionManager
      *
      * @param Extension $extension
      * @return array Notes from the migrator.
+     *
+     * @internal
      */
     public function migrateDown(Extension $extension)
     {
@@ -419,6 +428,8 @@ class ExtensionManager
      *                                to missing dependencies, in the format extension id => array of missing dependency IDs.
      *                            'circularDependencies' points to an array of extensions ids of extensions
      *                                that cannot be processed due to circular dependencies
+     *
+     * @internal
      */
     public static function resolveExtensionOrder($extensionList)
     {

src/Formatter/Formatter.php

@@ -44,21 +44,33 @@ class Formatter
         $this->cacheDir = $cacheDir;
     }
 
+    /**
+     * @internal
+     */
     public function addConfigurationCallback($callback)
     {
         $this->configurationCallbacks[] = $callback;
     }
 
+    /**
+     * @internal
+     */
     public function addParsingCallback($callback)
     {
         $this->parsingCallbacks[] = $callback;
     }
 
+    /**
+     * @internal
+     */
     public function addUnparsingCallback($callback)
     {
         $this->unparsingCallbacks[] = $callback;
     }
 
+    /**
+     * @internal
+     */
     public function addRenderingCallback($callback)
     {
         $this->renderingCallbacks[] = $callback;

src/Forum/ValidateCustomLess.php

@@ -22,6 +22,9 @@ use League\Flysystem\Adapter\NullAdapter;
 use League\Flysystem\Filesystem;
 use Less_Exception_Parser;
 
+/**
+ * @internal
+ */
 class ValidateCustomLess
 {
     /**

src/Foundation/Application.php

@@ -136,7 +136,8 @@ class Application
         \Illuminate\Container\Container::setInstance($this->container);
 
         /**
-         * @deprecated beta 16, remove beta 17
+         * Needed for the laravel framework code.
+         * Use container inside flarum instead.
          */
         $this->container->instance('app', $this->container);
         $this->container->alias('app', \Illluminate\Container\Container::class);

src/Frontend/AddLocaleAssets.php

@@ -12,6 +12,9 @@ namespace Flarum\Frontend;
 use Flarum\Frontend\Compiler\Source\SourceCollector;
 use Flarum\Locale\LocaleManager;
 
+/**
+ * @internal
+ */
 class AddLocaleAssets
 {
     /**

src/Frontend/AddTranslations.php

@@ -13,6 +13,9 @@ use Flarum\Frontend\Compiler\Source\SourceCollector;
 use Flarum\Locale\LocaleManager;
 use Illuminate\Support\Arr;
 
+/**
+ * @internal
+ */
 class AddTranslations
 {
     /**

src/Frontend/Assets.php

@@ -17,6 +17,8 @@ use Illuminate\Contracts\Filesystem\Filesystem;
 
 /**
  * A factory class for creating frontend asset compilers.
+ *
+ * @internal
  */
 class Assets
 {

src/Frontend/Compiler/JsCompiler.php

@@ -12,6 +12,9 @@ namespace Flarum\Frontend\Compiler;
 use axy\sourcemap\SourceMap;
 use Flarum\Frontend\Compiler\Source\FileSource;
 
+/**
+ * @internal
+ */
 class JsCompiler extends RevisionCompiler
 {
     protected function save(string $file, array $sources): bool

src/Frontend/Compiler/LessCompiler.php

@@ -12,6 +12,9 @@ namespace Flarum\Frontend\Compiler;
 use Flarum\Frontend\Compiler\Source\FileSource;
 use Less_Parser;
 
+/**
+ * @internal
+ */
 class LessCompiler extends RevisionCompiler
 {
     /**

src/Frontend/Compiler/RevisionCompiler.php

@@ -14,6 +14,9 @@ use Flarum\Frontend\Compiler\Source\SourceInterface;
 use Illuminate\Contracts\Filesystem\Filesystem;
 use Illuminate\Support\Arr;
 
+/**
+ * @internal
+ */
 class RevisionCompiler implements CompilerInterface
 {
     const REV_MANIFEST = 'rev-manifest.json';

src/Frontend/Compiler/Source/FileSource.php

@@ -11,6 +11,9 @@ namespace Flarum\Frontend\Compiler\Source;
 
 use InvalidArgumentException;
 
+/**
+ * @internal
+ */
 class FileSource implements SourceInterface
 {
     /**

src/Frontend/Compiler/Source/SourceCollector.php

@@ -9,6 +9,9 @@
 
 namespace Flarum\Frontend\Compiler\Source;
 
+/**
+ * @internal
+ */
 class SourceCollector
 {
     /**

src/Frontend/Compiler/Source/StringSource.php

@@ -9,6 +9,9 @@
 
 namespace Flarum\Frontend\Compiler\Source;
 
+/**
+ * @internal
+ */
 class StringSource implements SourceInterface
 {
     /**

src/Frontend/RecompileFrontendAssets.php

@@ -12,6 +12,9 @@ namespace Flarum\Frontend;
 use Flarum\Locale\LocaleManager;
 use Flarum\Settings\Event\Saved;
 
+/**
+ * @internal
+ */
 class RecompileFrontendAssets
 {
     /**

src/Http/RouteCollection.php

@@ -13,6 +13,9 @@ use FastRoute\DataGenerator;
 use FastRoute\RouteParser;
 use Illuminate\Support\Arr;
 
+/**
+ * @internal
+ */
 class RouteCollection
 {
     /**

src/Http/RouteCollectionUrlGenerator.php

@@ -9,6 +9,9 @@
 
 namespace Flarum\Http;
 
+/**
+ * @internal
+ */
 class RouteCollectionUrlGenerator
 {
     /**

src/Http/RouteHandlerFactory.php

@@ -16,6 +16,9 @@ use InvalidArgumentException;
 use Psr\Http\Message\ServerRequestInterface as Request;
 use Psr\Http\Server\RequestHandlerInterface as Handler;
 
+/**
+ * @internal
+ */
 class RouteHandlerFactory
 {
     /**

src/Install/Steps/WriteSettings.php

@@ -71,7 +71,7 @@ class WriteSettings implements Step
             'theme_dark_mode' => '0',
             'theme_primary_color' => '#4D698E',
             'theme_secondary_color' => '#4D698E',
-            'welcome_message' => 'This is beta software and you should not use it in production.',
+            'welcome_message' => 'Enjoy your new forum! Hop over to discuss.flarum.org if you have any questions, or to join our community!',
             'welcome_title' => 'Welcome to Flarum',
         ];
     }

src/Notification/MailableInterface.php

@@ -27,7 +27,5 @@ interface MailableInterface
      *
      * @return string
      */
-    // Uncomment beta 17. Commented as temporary BC layer since Symfony changed
+    public function getEmailSubject(TranslatorInterface $translator);
-    // the namespace of their translator interface
-    // public function getEmailSubject(TranslatorInterface $translator);
 }

src/Notification/NotificationSyncer.php

@@ -166,8 +166,10 @@ class NotificationSyncer
      *
      * @param string $driverName
      * @param NotificationDriverInterface $driver
+     *
+     * @internal
      */
-    public static function addNotificationDriver(string $driverName, NotificationDriverInterface $driver)
+    public static function addNotificationDriver(string $driverName, NotificationDriverInterface $driver): void
     {
         static::$notificationDrivers[$driverName] = $driver;
     }
@@ -182,6 +184,8 @@ class NotificationSyncer
 
     /**
      * @param callable|string $callback
+     *
+     * @internal
      */
     public static function beforeSending($callback): void
     {

src/Post/Post.php

@@ -210,6 +210,8 @@ class Post extends AbstractModel
      * @param string $type The post type.
      * @param string $model The class name of the model for that type.
      * @return void
+     *
+     * @internal
      */
     public static function setModel(string $type, string $model)
     {

src/User/Access/Gate.php

@@ -14,6 +14,9 @@ use Flarum\User\User;
 use Illuminate\Contracts\Container\Container;
 use Illuminate\Support\Arr;
 
+/**
+ * @internal
+ */
 class Gate
 {
     protected const EVALUATION_CRITERIA_PRIORITY = [

src/User/User.php

@@ -789,6 +789,8 @@ class User extends AbstractModel
      * Set the hasher with which to hash passwords.
      *
      * @param Hasher $hasher
+     *
+     * @internal
      */
     public static function setHasher(Hasher $hasher)
     {
@@ -801,6 +803,8 @@ class User extends AbstractModel
      * @param string $key
      * @param callable $transformer
      * @param mixed $default
+     *
+     * @internal
      */
     public static function registerPreference($key, callable $transformer = null, $default = null)
     {
@@ -812,6 +816,8 @@ class User extends AbstractModel
      *
      * @param callable $callback
      * @return array $groupIds
+     *
+     * @internal
      */
     public static function addGroupProcessor($callback)
     {