diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 08c11029f..f1c4e73aa 100644 --- a/.github/SECURITY.md +++ b/.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 diff --git a/src/Api/Controller/AbstractSerializeController.php b/src/Api/Controller/AbstractSerializeController.php index 015a42667..06b53ced3 100644 --- a/src/Api/Controller/AbstractSerializeController.php +++ b/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])) { diff --git a/src/Api/Serializer/AbstractSerializer.php b/src/Api/Serializer/AbstractSerializer.php index ebd7b799f..a6892f129 100644 --- a/src/Api/Serializer/AbstractSerializer.php +++ b/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; } diff --git a/src/Database/AbstractModel.php b/src/Database/AbstractModel.php index 7e5013a0d..6da46666a 100644 --- a/src/Database/AbstractModel.php +++ b/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 = []; /** diff --git a/src/Database/Migrator.php b/src/Database/Migrator.php index f8f0c8d54..7bf06f07b 100644 --- a/src/Database/Migrator.php +++ b/src/Database/Migrator.php @@ -19,6 +19,9 @@ use Illuminate\Filesystem\Filesystem; use InvalidArgumentException; use Symfony\Component\Console\Output\OutputInterface; +/** + * @internal + */ class Migrator { /** diff --git a/src/Extend/ApiController.php b/src/Extend/ApiController.php index be7848879..251bed9d8 100644 --- a/src/Extend/ApiController.php +++ b/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); diff --git a/src/Extend/ApiSerializer.php b/src/Extend/ApiSerializer.php index 95bf4e030..a72e91df7 100644 --- a/src/Extend/ApiSerializer.php +++ b/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; diff --git a/src/Extend/Auth.php b/src/Extend/Auth.php index a69db6ef6..66f5e764c 100644 --- a/src/Extend/Auth.php +++ b/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: - * - `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; diff --git a/src/Extend/Console.php b/src/Extend/Console.php index 044cca66c..dfa1945a2 100644 --- a/src/Extend/Console.php +++ b/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'); diff --git a/src/Extend/Csrf.php b/src/Extend/Csrf.php index 5df93ac97..d4d6d2e0f 100644 --- a/src/Extend/Csrf.php +++ b/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; diff --git a/src/Extend/ErrorHandling.php b/src/Extend/ErrorHandling.php index 5277a96d5..7d75465d4 100644 --- a/src/Extend/ErrorHandling.php +++ b/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; diff --git a/src/Extend/Event.php b/src/Extend/Event.php index cade05483..734bad5d5 100644 --- a/src/Extend/Event.php +++ b/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: - * - 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; diff --git a/src/Extend/Filesystem.php b/src/Extend/Filesystem.php index d3c75bbb4..4e2f2ec59 100644 --- a/src/Extend/Filesystem.php +++ b/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|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; diff --git a/src/Extend/Filter.php b/src/Extend/Filter.php index ef694565e..3fa0d1d50 100644 --- a/src/Extend/Filter.php +++ b/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; diff --git a/src/Extend/Formatter.php b/src/Extend/Formatter.php index f1d742cc0..0eb79a9ff 100644 --- a/src/Extend/Formatter.php +++ b/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; diff --git a/src/Extend/Frontend.php b/src/Extend/Frontend.php index 1726307d9..0cf2938e3 100644 --- a/src/Extend/Frontend.php +++ b/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 - * @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; diff --git a/src/Extend/LanguagePack.php b/src/Extend/LanguagePack.php index 70a0b2a8c..9807ce978 100644 --- a/src/Extend/LanguagePack.php +++ b/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') { diff --git a/src/Extend/Locales.php b/src/Extend/Locales.php index c316d5726..9ad953420 100644 --- a/src/Extend/Locales.php +++ b/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; } diff --git a/src/Extend/Mail.php b/src/Extend/Mail.php index d9e133523..217c5da77 100644 --- a/src/Extend/Mail.php +++ b/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 $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; diff --git a/src/Extend/Middleware.php b/src/Extend/Middleware.php index 4022f7908..e7fe119be 100644 --- a/src/Extend/Middleware.php +++ b/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; diff --git a/src/Extend/Model.php b/src/Extend/Model.php index b0912fded..07b0d1b7e 100644 --- a/src/Extend/Model.php +++ b/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; diff --git a/src/Extend/ModelPrivate.php b/src/Extend/ModelPrivate.php index b20bf34e7..9b64c5c37 100644 --- a/src/Extend/ModelPrivate.php +++ b/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; diff --git a/src/Extend/ModelUrl.php b/src/Extend/ModelUrl.php index 7c410dfd6..c03b3516d 100644 --- a/src/Extend/ModelUrl.php +++ b/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 $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; diff --git a/src/Extend/ModelVisibility.php b/src/Extend/ModelVisibility.php index 3313b0ea8..6110d89c8 100644 --- a/src/Extend/ModelVisibility.php +++ b/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; diff --git a/src/Extend/Notification.php b/src/Extend/Notification.php index 1a6a9cbfa..72abf1f8d 100644 --- a/src/Extend/Notification.php +++ b/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 $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; diff --git a/src/Extend/Policy.php b/src/Extend/Policy.php index 481f85bcc..f44f6f793 100644 --- a/src/Extend/Policy.php +++ b/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] = []; diff --git a/src/Extend/Post.php b/src/Extend/Post.php index f750dbe2a..3e10dba5f 100644 --- a/src/Extend/Post.php +++ b/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; diff --git a/src/Extend/Routes.php b/src/Extend/Routes.php index e78099823..bb92e3518 100644 --- a/src/Extend/Routes.php +++ b/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; diff --git a/src/Extend/ServiceProvider.php b/src/Extend/ServiceProvider.php index b2767cdcb..b9441077e 100644 --- a/src/Extend/ServiceProvider.php +++ b/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; diff --git a/src/Extend/Settings.php b/src/Extend/Settings.php index 18212e7f7..e100e94b0 100644 --- a/src/Extend/Settings.php +++ b/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'); diff --git a/src/Extend/SimpleFlarumSearch.php b/src/Extend/SimpleFlarumSearch.php index 57e441a8e..9249ae9cb 100644 --- a/src/Extend/SimpleFlarumSearch.php +++ b/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\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; diff --git a/src/Extend/ThrottleApi.php b/src/Extend/ThrottleApi.php index 474b4ef38..747f0deea 100644 --- a/src/Extend/ThrottleApi.php +++ b/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; diff --git a/src/Extend/User.php b/src/Extend/User.php index 1664dc3e7..3357474e1 100644 --- a/src/Extend/User.php +++ b/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 $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'); diff --git a/src/Extend/Validator.php b/src/Extend/Validator.php index 4b8d2a619..817367c00 100644 --- a/src/Extend/Validator.php +++ b/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; diff --git a/src/Extend/View.php b/src/Extend/View.php index 9c8cfce75..176eb021e 100644 --- a/src/Extend/View.php +++ b/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; diff --git a/src/Extension/Extension.php b/src/Extension/Extension.php index 1f1fdb5a4..a705578fb 100644 --- a/src/Extension/Extension.php +++ b/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()) { diff --git a/src/Extension/ExtensionManager.php b/src/Extension/ExtensionManager.php index 8ff03c905..c55a461be 100644 --- a/src/Extension/ExtensionManager.php +++ b/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) { diff --git a/src/Formatter/Formatter.php b/src/Formatter/Formatter.php index 44776a2ac..d2396ea27 100644 --- a/src/Formatter/Formatter.php +++ b/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; diff --git a/src/Forum/ValidateCustomLess.php b/src/Forum/ValidateCustomLess.php index 4bfdbc60e..dc6e529d8 100644 --- a/src/Forum/ValidateCustomLess.php +++ b/src/Forum/ValidateCustomLess.php @@ -22,6 +22,9 @@ use League\Flysystem\Adapter\NullAdapter; use League\Flysystem\Filesystem; use Less_Exception_Parser; +/** + * @internal + */ class ValidateCustomLess { /** diff --git a/src/Foundation/Application.php b/src/Foundation/Application.php index bc2ba6ccd..10f92aa8d 100644 --- a/src/Foundation/Application.php +++ b/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); diff --git a/src/Frontend/AddLocaleAssets.php b/src/Frontend/AddLocaleAssets.php index 8de62bb0c..8dc089db4 100644 --- a/src/Frontend/AddLocaleAssets.php +++ b/src/Frontend/AddLocaleAssets.php @@ -12,6 +12,9 @@ namespace Flarum\Frontend; use Flarum\Frontend\Compiler\Source\SourceCollector; use Flarum\Locale\LocaleManager; +/** + * @internal + */ class AddLocaleAssets { /** diff --git a/src/Frontend/AddTranslations.php b/src/Frontend/AddTranslations.php index 5df1a91c6..139724e1d 100644 --- a/src/Frontend/AddTranslations.php +++ b/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 { /** diff --git a/src/Frontend/Assets.php b/src/Frontend/Assets.php index 68768a443..8b793697e 100644 --- a/src/Frontend/Assets.php +++ b/src/Frontend/Assets.php @@ -17,6 +17,8 @@ use Illuminate\Contracts\Filesystem\Filesystem; /** * A factory class for creating frontend asset compilers. + * + * @internal */ class Assets { diff --git a/src/Frontend/Compiler/JsCompiler.php b/src/Frontend/Compiler/JsCompiler.php index 53604d520..a092f6af0 100644 --- a/src/Frontend/Compiler/JsCompiler.php +++ b/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 diff --git a/src/Frontend/Compiler/LessCompiler.php b/src/Frontend/Compiler/LessCompiler.php index a245f224a..615c23f22 100644 --- a/src/Frontend/Compiler/LessCompiler.php +++ b/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 { /** diff --git a/src/Frontend/Compiler/RevisionCompiler.php b/src/Frontend/Compiler/RevisionCompiler.php index f77d5eec5..9db42c21c 100644 --- a/src/Frontend/Compiler/RevisionCompiler.php +++ b/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'; diff --git a/src/Frontend/Compiler/Source/FileSource.php b/src/Frontend/Compiler/Source/FileSource.php index 7cd974497..f85c5926e 100644 --- a/src/Frontend/Compiler/Source/FileSource.php +++ b/src/Frontend/Compiler/Source/FileSource.php @@ -11,6 +11,9 @@ namespace Flarum\Frontend\Compiler\Source; use InvalidArgumentException; +/** + * @internal + */ class FileSource implements SourceInterface { /** diff --git a/src/Frontend/Compiler/Source/SourceCollector.php b/src/Frontend/Compiler/Source/SourceCollector.php index eb6cf0d34..ec537b26b 100644 --- a/src/Frontend/Compiler/Source/SourceCollector.php +++ b/src/Frontend/Compiler/Source/SourceCollector.php @@ -9,6 +9,9 @@ namespace Flarum\Frontend\Compiler\Source; +/** + * @internal + */ class SourceCollector { /** diff --git a/src/Frontend/Compiler/Source/StringSource.php b/src/Frontend/Compiler/Source/StringSource.php index b480e875c..cd6cc1988 100644 --- a/src/Frontend/Compiler/Source/StringSource.php +++ b/src/Frontend/Compiler/Source/StringSource.php @@ -9,6 +9,9 @@ namespace Flarum\Frontend\Compiler\Source; +/** + * @internal + */ class StringSource implements SourceInterface { /** diff --git a/src/Frontend/RecompileFrontendAssets.php b/src/Frontend/RecompileFrontendAssets.php index 73b0497e2..8a0b9a90d 100644 --- a/src/Frontend/RecompileFrontendAssets.php +++ b/src/Frontend/RecompileFrontendAssets.php @@ -12,6 +12,9 @@ namespace Flarum\Frontend; use Flarum\Locale\LocaleManager; use Flarum\Settings\Event\Saved; +/** + * @internal + */ class RecompileFrontendAssets { /** diff --git a/src/Http/RouteCollection.php b/src/Http/RouteCollection.php index 57f7c9449..78c6998e2 100644 --- a/src/Http/RouteCollection.php +++ b/src/Http/RouteCollection.php @@ -13,6 +13,9 @@ use FastRoute\DataGenerator; use FastRoute\RouteParser; use Illuminate\Support\Arr; +/** + * @internal + */ class RouteCollection { /** diff --git a/src/Http/RouteCollectionUrlGenerator.php b/src/Http/RouteCollectionUrlGenerator.php index 611c5ce8c..dffa13982 100644 --- a/src/Http/RouteCollectionUrlGenerator.php +++ b/src/Http/RouteCollectionUrlGenerator.php @@ -9,6 +9,9 @@ namespace Flarum\Http; +/** + * @internal + */ class RouteCollectionUrlGenerator { /** diff --git a/src/Http/RouteHandlerFactory.php b/src/Http/RouteHandlerFactory.php index af8b3f441..ac49b7ca6 100644 --- a/src/Http/RouteHandlerFactory.php +++ b/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 { /** diff --git a/src/Install/Steps/WriteSettings.php b/src/Install/Steps/WriteSettings.php index 8ca993cb3..910bbcffa 100644 --- a/src/Install/Steps/WriteSettings.php +++ b/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', ]; } diff --git a/src/Notification/MailableInterface.php b/src/Notification/MailableInterface.php index ac2706ace..2804e0704 100644 --- a/src/Notification/MailableInterface.php +++ b/src/Notification/MailableInterface.php @@ -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); } diff --git a/src/Notification/NotificationSyncer.php b/src/Notification/NotificationSyncer.php index 22072d941..18d845a8d 100644 --- a/src/Notification/NotificationSyncer.php +++ b/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 { diff --git a/src/Post/Post.php b/src/Post/Post.php index 4b294a55f..f9deff3d2 100644 --- a/src/Post/Post.php +++ b/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) { diff --git a/src/User/Access/Gate.php b/src/User/Access/Gate.php index 98e93fa22..5970b3043 100644 --- a/src/User/Access/Gate.php +++ b/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 = [ diff --git a/src/User/User.php b/src/User/User.php index 6420a5749..5648e3b48 100644 --- a/src/User/User.php +++ b/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) {