github-mirror/framework
github-mirror/framework
2
0
Fork 0
mirror of https://github.com/flarum/framework.git synced 2025-02-21 11:31:27 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Backend cleanup (#2859)

Browse Source 
* 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>
This commit is contained in:
Sami Mazouz 2021-05-13 15:26:24 +01:00 committed by GitHub
parent e3f506817b
commit 7bceda976b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
59 changed files with 655 additions and 174 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/SECURITY.md vendored
View File

@ -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

9
src/Api/Controller/AbstractSerializeController.php
View File

@ -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])) {

10
src/Api/Serializer/AbstractSerializer.php
View File

@ -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;
}

9
src/Database/AbstractModel.php
View File

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

3
src/Database/Migrator.php
View File

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

110
src/Extend/ApiController.php
View File

@ -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);

12
src/Extend/ApiSerializer.php
View File

@ -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;

25
src/Extend/Auth.php
View File

@ -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:
* - `true` if the given password is valid.
* - `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`.
*
* The callable should accept:
* - $user: An instance of the User model.
* - $password: A string.
*
* The callable should return:
* - `true` if the given password is valid.
* - `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;

10
src/Extend/Console.php
View File

@ -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');

3
src/Extend/Csrf.php
View File

@ -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;

23
src/Extend/ErrorHandling.php
View File

@ -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;

23
src/Extend/Event.php
View File

@ -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:
* - 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 string $event: Name of the event, can be the ::class attribute of the event class.
* @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;

27
src/Extend/Filesystem.php
View File

@ -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|callable $callback: A callback or invokable class name with parameters:
* - \Flarum\Foundation\Paths $paths
* - \Flarum\Http\UrlGenerator $url
* which returns a Laravel disk config array.
* The `driver` key is not necessary for this array, and will be ignored.
* @param string $name: The name of the disk.
* @param string|callable $callback
*
* The callback can be a closure or an invokable class, and should accept:
* - \Flarum\Foundation\Paths $paths
* - \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;

11
src/Extend/Filter.php
View File

@ -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;

16
src/Extend/Formatter.php
View File

@ -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;

66
src/Extend/Frontend.php
View File

@ -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
* @return $this
* Modify the content of the frontend.
*
* @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;

2
src/Extend/LanguagePack.php
View File

@ -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')
{

5
src/Extend/Locales.php
View File

@ -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;
}

7
src/Extend/Mail.php
View File

@ -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 $driver ::class attribute of driver class, which must implement Flarum\Mail\DriverInterface
* @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.
* @return self
*/
public function driver(string $identifier, $driver)
public function driver(string $identifier, string $driver): self
{
$this->drivers[$identifier] = $driver;

53
src/Extend/Middleware.php
View File

@ -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;

16
src/Extend/Model.php
View File

@ -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;

4
src/Extend/ModelPrivate.php
View File

@ -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;

8
src/Extend/ModelUrl.php
View File

@ -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 $driver ::class attribute of driver class, which must implement Flarum\Http\SlugDriverInterface
* @param string $identifier: Identifier for slug driver.
* @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;

12
src/Extend/ModelVisibility.php
View File

@ -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;

26
src/Extend/Notification.php
View File

@ -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 $driver The ::class attribute of the driver class.
* @param string $driverName: The name of the notification driver.
* @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;

12
src/Extend/Policy.php
View File

@ -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] = [];

3
src/Extend/Post.php
View File

@ -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;

121
src/Extend/Routes.php
View File

@ -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;

6
src/Extend/ServiceProvider.php
View File

@ -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;

11
src/Extend/Settings.php
View File

@ -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');

18
src/Extend/SimpleFlarumSearch.php
View File

@ -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\Query\QueryCriteria $criteria
* - \Flarum\Search\SearchState $search
* - \Flarum\Query\QueryCriteria $criteria
*
* The callback should return void.
*
* @return self
*/
public function addSearchMutator($callback)
public function addSearchMutator($callback): self
{
$this->searchMutators[] = $callback;

5
src/Extend/ThrottleApi.php
View File

@ -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;

16
src/Extend/User.php
View File

@ -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 $driver ::class attribute of driver class, which must implement Flarum\User\DisplayName\DriverInterface
* @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
* @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');

12
src/Extend/Validator.php
View File

@ -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;

6
src/Extend/View.php
View File

@ -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;

37
src/Extension/Extension.php
View File

@ -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()) {

11
src/Extension/ExtensionManager.php
View File

@ -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)
{

12
src/Formatter/Formatter.php
View File

@ -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;

3
src/Forum/ValidateCustomLess.php
View File

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

3
src/Foundation/Application.php
View File

@ -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);

3
src/Frontend/AddLocaleAssets.php
View File

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

3
src/Frontend/AddTranslations.php
View File

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

2
src/Frontend/Assets.php
View File

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

3
src/Frontend/Compiler/JsCompiler.php
View File

@ -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

3
src/Frontend/Compiler/LessCompiler.php
View File

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

3
src/Frontend/Compiler/RevisionCompiler.php
View File

@ -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';

3
src/Frontend/Compiler/Source/FileSource.php
View File

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

3
src/Frontend/Compiler/Source/SourceCollector.php
View File

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

3
src/Frontend/Compiler/Source/StringSource.php
View File

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

3
src/Frontend/RecompileFrontendAssets.php
View File

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

3
src/Http/RouteCollection.php
View File

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

3
src/Http/RouteCollectionUrlGenerator.php
View File

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

3
src/Http/RouteHandlerFactory.php
View File

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

2
src/Install/Steps/WriteSettings.php
View File

@ -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',
];
}

4
src/Notification/MailableInterface.php
View File

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

6
src/Notification/NotificationSyncer.php
View File

@ -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
{

2
src/Post/Post.php
View File

@ -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)
{

3
src/User/Access/Gate.php
View File

@ -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 = [

6
src/User/User.php
View File

@ -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)
{