Update API action architecture

- An API action handles a Flarum\Api\Request, which is a simple object
containing an array of params, the actor, and optionally an HTTP
request object
- Most API actions use SerializeAction as a base, which parses request
input according to the JSON-API spec (creates a JsonApiRequest object),
runs the child class method to get data, then serializes it and assigns
it to a JsonApiResponse (standard HTTP response with a
Tobscure\JsonApi\Document as content)
- The JSON-API request input parsing is subject to restrictions as
defined by public static properties on the action (i.e. extensible)
- Also the actor is given to the serializer instance now, instead of
being a static property

src/Api/Actions/Discussions/ShowAction.php

@@ -1,14 +1,13 @@
 <?php namespace Flarum\Api\Actions\Discussions;
 
-use Flarum\Support\Actor;
-use Flarum\Core\Repositories\DiscussionRepositoryInterface as DiscussionRepository;
-use Flarum\Core\Repositories\PostRepositoryInterface as PostRepository;
-use Flarum\Api\Actions\BaseAction;
-use Flarum\Api\Actions\ApiParams;
+use Flarum\Core\Repositories\DiscussionRepositoryInterface;
+use Flarum\Core\Repositories\PostRepositoryInterface;
+use Flarum\Api\Actions\SerializeResourceAction;
 use Flarum\Api\Actions\Posts\GetsPosts;
-use Flarum\Api\Serializers\DiscussionSerializer;
+use Flarum\Api\JsonApiRequest;
+use Flarum\Api\JsonApiResponse;
 
-class ShowAction extends BaseAction
+class ShowAction extends SerializeResourceAction
 {
     use GetsPosts;
 
@@ -26,48 +25,104 @@ class ShowAction extends BaseAction
      */
     protected $posts;
 
+    /**
+     * The name of the serializer class to output results with.
+     *
+     * @var string
+     */
+    public static $serializer = 'Flarum\Api\Serializers\DiscussionSerializer';
+
+    /**
+     * The relations that are available to be included.
+     *
+     * @var array
+     */
+    public static $includeAvailable = [
+        'startUser', 'lastUser', 'startPost', 'lastPost', 'posts',
+        'posts.user', 'posts.user.groups', 'posts.editUser', 'posts.hideUser'
+    ];
+
+    /**
+     * The relations that are included by default.
+     *
+     * @var array
+     */
+    public static $include = [
+        'startPost', 'lastPost', 'posts',
+        'posts.user', 'posts.user.groups', 'posts.editUser', 'posts.hideUser'
+    ];
+
+    /**
+     * The relations that are linked by default.
+     *
+     * @var array
+     */
+    public static $link = ['posts'];
+
+    /**
+     * The fields that are available to be sorted by.
+     *
+     * @var array
+     */
+    public static $sortAvailable = ['time'];
+
+    /**
+     * The default field to sort by.
+     *
+     * @var string
+     */
+    public static $sort = ['time' => 'asc'];
+
+    /**
+     * The maximum number of records that can be requested.
+     *
+     * @var integer
+     */
+    public static $limitMax = 50;
+
+    /**
+     * The number of records included by default.
+     *
+     * @var integer
+     */
+    public static $limit = 20;
+
     /**
      * Instantiate the action.
      *
      * @param PostRepository $posts
      */
-    public function __construct(Actor $actor, DiscussionRepository $discussions, PostRepository $posts)
+    public function __construct(DiscussionRepositoryInterface $discussions, PostRepositoryInterface $posts)
     {
-        $this->actor = $actor;
         $this->discussions = $discussions;
         $this->posts = $posts;
     }
 
     /**
-     * Show a single discussion.
+     * Get a single discussion, ready to be serialized and assigned to the
+     * JsonApi response.
      *
-     * @return Response
+     * @param \Flarum\Api\JsonApiRequest $request
+     * @param \Flarum\Api\JsonApiResponse $response
+     * @return \Flarum\Core\Models\Discussion
      */
-    protected function run(ApiParams $params)
+    protected function data(JsonApiRequest $request, JsonApiResponse $response)
     {
-        $include = $params->included(['startPost', 'lastPost', 'posts']);
+        $user = $request->actor->getUser();
 
-        $user = $this->actor->getUser();
+        $discussion = $this->discussions->findOrFail($request->get('id'), $user);
 
-        $discussion = $this->discussions->findOrFail($params->get('id'), $user);
         $discussion->posts_ids = $discussion->posts()->whereCan($user, 'view')->get(['id'])->fetch('id')->all();
 
-        if (in_array('posts', $include)) {
-            $relations = ['user', 'user.groups', 'editUser', 'hideUser'];
-            $discussion->posts = $this->getPosts($params, ['discussion_id' => $discussion->id])->load($relations);
+        if (in_array('posts', $request->include)) {
+            $length = strlen($prefix = 'posts.');
+            $relations = array_filter(array_map(function ($relationship) use ($prefix, $length) {
+                return substr($relationship, 0, $length) === $prefix ? substr($relationship, $length) : false;
+            }, $request->include));
 
-            $include = array_merge($include, array_map(function ($relation) {
-                return 'posts.'.$relation;
-            }, $relations));
+            $discussion->posts = $this->getPosts($request, ['discussion_id' => $discussion->id])->load($relations);
         }
 
-        // Set up the discussion serializer, which we will use to create the
-        // document's primary resource. As well as including the requested
-        // relations, we will specify that we want the 'posts' relation to be
-        // linked so that a list of post IDs will show up in the response.
-        $serializer = new DiscussionSerializer($include, ['posts']);
-        $document = $this->document()->setData($serializer->resource($discussion));
-
-        return $this->respondWithDocument($document);
+        return $discussion;
     }
 }