Massive refactor

- Use contextual namespaces within Flarum\Core
- Clean up and docblock everything
- Refactor Activity/Notification blueprint stuff
- Refactor Formatter stuff
- Refactor Search stuff
- Upgrade to JSON-API 1.0
- Removed “addedPosts” and “removedPosts” relationships from discussion
API. This was used for adding/removing event posts after renaming a
discussion etc. Instead we should make an additional request to get all
new posts

Todo:
- Fix Extenders and extensions
- Get rid of repository interfaces
- Fix other bugs I’ve inevitably introduced

src/Core/Support/DispatchesEvents.php

@@ -1,4 +1,4 @@
-<?php  namespace Flarum\Core\Support;
+<?php namespace Flarum\Core\Support;
 
 trait DispatchesEvents
 {

src/Core/Support/EventGenerator.php

@@ -8,9 +8,9 @@ trait EventGenerator
     protected $pendingEvents = [];
 
     /**
-     * Raise a new event
+     * Raise a new event.
      *
-     * @param $event
+     * @param mixed $event
      */
     public function raise($event)
     {
@@ -18,7 +18,7 @@ trait EventGenerator
     }
 
     /**
-     * Return and reset all pending events
+     * Return and reset all pending events.
      *
      * @return array
      */

src/Core/Support/Locked.php

@@ -1,34 +1,62 @@
 <?php namespace Flarum\Core\Support;
 
 use Flarum\Core\Exceptions\PermissionDeniedException;
+use Flarum\Core\Users\User;
 
+/**
+ * 'Lock' an object, allowing the permission of a user to perform an action to
+ * be tested.
+ */
 trait Locked
 {
+    /**
+     * @var callable[]
+     */
     protected static $conditions = [];
 
+    /**
+     * Get the condition callbacks for the specified action.
+     *
+     * @param string $action
+     * @return callable[]
+     */
     protected static function getConditions($action)
     {
-        $conditions = isset(static::$conditions[$action]) ? static::$conditions[$action] : [];
-        $all = isset(static::$conditions['*']) ? static::$conditions['*'] : [];
+        $conditions = array_get(static::$conditions, $action, []);
+        $all = array_get(static::$conditions, '*', []);
 
         return array_merge($conditions, $all);
     }
 
+    /**
+     * Allow the specified action if the given condition is satisfied.
+     *
+     * @param string $action
+     * @param callable $condition The condition callback. Parameters are the
+     *     object that is locked, the user performing the action,
+     *     and the name of the action. This condition will be ignored if it
+     *     returns null; otherwise, the return value will determine whether or
+     *     not the action is allowed.
+     */
     public static function allow($action, callable $condition)
     {
-        foreach ((array) $action as $action) {
-            if (! isset(static::$conditions[$action])) {
-                static::$conditions[$action] = [];
-            }
-
+        foreach ((array)$action as $action) {
             static::$conditions[$action][] = $condition;
         }
     }
 
-    public function can($user, $action)
+    /**
+     * Check whether or not a user has permission to perform an action,
+     * according to the collected conditions.
+     *
+     * @param User $actor
+     * @param string $action
+     * @return bool
+     */
+    public function can(User $actor, $action)
     {
         foreach ($this->getConditions($action) as $condition) {
-            $can = $condition($this, $user, $action);
+            $can = $condition($this, $actor, $action);
 
             if ($can !== null) {
                 return $can;
@@ -42,15 +70,13 @@ trait Locked
      * Assert that the user has a certain permission for this model, throwing
      * an exception if they don't.
      *
-     * @param \Flarum\Core\Models\User $user
-     * @param string $permission
-     * @return void
-     *
-     * @throws \Flarum\Core\Exceptions\PermissionDeniedException
+     * @param User $actor
+     * @param string $action
+     * @throws PermissionDeniedException
      */
-    public function assertCan($user, $action)
+    public function assertCan(User $actor, $action)
     {
-        if (! $this->can($user, $action)) {
+        if (! $this->can($actor, $action)) {
             throw new PermissionDeniedException;
         }
     }

src/Core/Support/VisibleScope.php

@@ -1,15 +1,37 @@
 <?php namespace Flarum\Core\Support;
 
+use Flarum\Core\Users\User;
+use Illuminate\Database\Eloquent\Builder;
+
+/**
+ * Add a query scope to an Eloquent model that filters out records that a user
+ * is not allowed to view.
+ */
 trait VisibleScope
 {
+    /**
+     * @var callable[]
+     */
     protected static $visibleScopes = [];
 
+    /**
+     * Add a callback to scope a query to only include records that are visible
+     * to a user.
+     *
+     * @param callable $scope
+     */
     public static function addVisibleScope(callable $scope)
     {
         static::$visibleScopes[] = $scope;
     }
 
-    public function scopeWhereVisibleTo($query, $user)
+    /**
+     * Scope a query to only include records that are visible to a user.
+     *
+     * @param Builder $query
+     * @param User $user
+     */
+    public function scopeWhereVisibleTo(Builder $query, User $user)
     {
         foreach (static::$visibleScopes as $scope) {
             $scope($query, $user);