ApiSerializer Extender (#2438)

src/Api/Event/Serializing.php

@@ -17,6 +17,8 @@ use Flarum\Api\Serializer\AbstractSerializer;
  *
  * This event is fired when a serializer is constructing an array of resource
  * attributes for API output.
+ *
+ * @deprecated in beta 15, removed in beta 16
  */
 class Serializing
 {

src/Api/Serializer/AbstractSerializer.php

@@ -16,6 +16,7 @@ use Flarum\Event\GetApiRelationship;
 use Flarum\User\User;
 use Illuminate\Contracts\Container\Container;
 use Illuminate\Contracts\Events\Dispatcher;
+use Illuminate\Support\Arr;
 use InvalidArgumentException;
 use LogicException;
 use Psr\Http\Message\ServerRequestInterface as Request;
@@ -47,6 +48,16 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
      */
     protected static $container;
 
+    /**
+     * @var callable[]
+     */
+    protected static $mutators = [];
+
+    /**
+     * @var array
+     */
+    protected static $customRelations = [];
+
     /**
      * @return Request
      */
@@ -83,6 +94,18 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
 
         $attributes = $this->getDefaultAttributes($model);
 
+        foreach (array_reverse(array_merge([static::class], class_parents($this))) as $class) {
+            if (isset(static::$mutators[$class])) {
+                foreach (static::$mutators[$class] as $callback) {
+                    $attributes = array_merge(
+                        $attributes,
+                        $callback($this, $model, $attributes)
+                    );
+                }
+            }
+        }
+
+        // Deprecated in beta 15, removed in beta 16
         static::$dispatcher->dispatch(
             new Serializing($this, $model, $attributes)
         );
@@ -102,7 +125,7 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
      * @param DateTime|null $date
      * @return string|null
      */
-    protected function formatDate(DateTime $date = null)
+    public function formatDate(DateTime $date = null)
     {
         if ($date) {
             return $date->format(DateTime::RFC3339);
@@ -130,10 +153,20 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
      */
     protected function getCustomRelationship($model, $name)
     {
+        // Deprecated in beta 15, removed in beta 16
         $relationship = static::$dispatcher->until(
             new GetApiRelationship($this, $name, $model)
         );
 
+        foreach (array_merge([static::class], class_parents($this)) as $class) {
+            $callback = Arr::get(static::$customRelations, "$class.$name");
+
+            if (is_callable($callback)) {
+                $relationship = $callback($this, $model);
+                break;
+            }
+        }
+
         if ($relationship && ! ($relationship instanceof Relationship)) {
             throw new LogicException(
                 'GetApiRelationship handler must return an instance of '.Relationship::class
@@ -280,4 +313,27 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
     {
         static::$container = $container;
     }
+
+    /**
+     * @param string $serializerClass
+     * @param callable $mutator
+     */
+    public static function addMutator(string $serializerClass, callable $mutator)
+    {
+        if (! isset(static::$mutators[$serializerClass])) {
+            static::$mutators[$serializerClass] = [];
+        }
+
+        static::$mutators[$serializerClass][] = $mutator;
+    }
+
+    /**
+     * @param string $serializerClass
+     * @param string $relation
+     * @param callable $callback
+     */
+    public static function setRelationship(string $serializerClass, string $relation, callable $callback)
+    {
+        static::$customRelations[$serializerClass][$relation] = $callback;
+    }
 }

src/Event/GetApiRelationship.php

@@ -21,6 +21,8 @@ use Flarum\Api\Serializer\AbstractSerializer;
  * @see AbstractSerializer::hasOne()
  * @see AbstractSerializer::hasMany()
  * @see https://github.com/tobscure/json-api
+ *
+ * @deprecated in beta 15, removed in beta 16
  */
 class GetApiRelationship
 {

src/Extend/ApiSerializer.php

@@ -0,0 +1,162 @@
+<?php
+
+/*
+ * This file is part of Flarum.
+ *
+ * For detailed copyright and license information, please view the
+ * LICENSE file that was distributed with this source code.
+ */
+
+namespace Flarum\Extend;
+
+use Flarum\Api\Serializer\AbstractSerializer;
+use Flarum\Extension\Extension;
+use Flarum\Foundation\ContainerUtil;
+use Illuminate\Contracts\Container\Container;
+
+class ApiSerializer implements ExtenderInterface
+{
+    private $serializerClass;
+    private $attributes = [];
+    private $mutators = [];
+    private $relationships = [];
+
+    /**
+     * @param string $serializerClass The ::class attribute of the serializer you are modifying.
+     *                                This serializer should extend from \Flarum\Api\Serializer\AbstractSerializer.
+     */
+    public function __construct(string $serializerClass)
+    {
+        $this->serializerClass = $serializerClass;
+    }
+
+    /**
+     * @param string $name: The name of the attribute.
+     * @param callable|string $callback
+     *
+     * The callback can be a closure or an invokable class, and should accept:
+     * - $serializer: An instance of this serializer.
+     * - $model: An instance of the model being serialized.
+     * - $attributes: An array of existing attributes.
+     *
+     * The callable should return:
+     * - The value of the attribute.
+     *
+     * @return self
+     */
+    public function attribute(string $name, $callback)
+    {
+        $this->attributes[$name] = $callback;
+
+        return $this;
+    }
+
+    /**
+     * Add to or modify the attributes array of this serializer.
+     *
+     * @param callable|string $callback
+     *
+     * The callback can be a closure or an invokable class, and should accept:
+     * - $serializer: An instance of this serializer.
+     * - $model: An instance of the model being serialized.
+     * - $attributes: An array of existing attributes.
+     *
+     * The callable should return:
+     * - An array of additional attributes to merge with the existing array.
+     *   Or a modified $attributes array.
+     *
+     * @return self
+     */
+    public function mutate($callback)
+    {
+        $this->mutators[] = $callback;
+
+        return $this;
+    }
+
+    /**
+     * Establish a simple hasOne relationship from this serializer to another serializer.
+     * This represents a one-to-one relationship.
+     *
+     * @param string $name: The name of the relation. Has to be unique from other relation names.
+     *                      The relation has to exist in the model handled by this serializer.
+     * @param string $serializerClass: The ::class attribute the serializer that handles this relation.
+     *                                 This serializer should extend from \Flarum\Api\Serializer\AbstractSerializer.
+     * @return self
+     */
+    public function hasOne(string $name, string $serializerClass)
+    {
+        return $this->relationship($name, function (AbstractSerializer $serializer, $model) use ($serializerClass, $name) {
+            return $serializer->hasOne($model, $serializerClass, $name);
+        });
+    }
+
+    /**
+     * Establish a simple hasMany relationship from this serializer to another serializer.
+     * This represents a one-to-many relationship.
+     *
+     * @param string $name: The name of the relation. Has to be unique from other relation names.
+     *                      The relation has to exist in the model handled by this serializer.
+     * @param string $serializerClass: The ::class attribute the serializer that handles this relation.
+     *                                 This serializer should extend from \Flarum\Api\Serializer\AbstractSerializer.
+     * @return self
+     */
+    public function hasMany(string $name, string $serializerClass)
+    {
+        return $this->relationship($name, function (AbstractSerializer $serializer, $model) use ($serializerClass, $name) {
+            return $serializer->hasMany($model, $serializerClass, $name);
+        });
+    }
+
+    /**
+     * Add a relationship from this serializer to another serializer.
+     *
+     * @param string $name: The name of the relation. Has to be unique from other relation names.
+     *                      The relation has to exist in the model handled by this serializer.
+     * @param callable|string $callback
+     *
+     * The callable can be a closure or an invokable class, and should accept:
+     * - $serializer: An instance of this serializer.
+     * - $model: An instance of the model being serialized.
+     *
+     * The callable should return:
+     * - $relationship: An instance of \Tobscure\JsonApi\Relationship.
+     *
+     * @return self
+     */
+    public function relationship(string $name, $callback)
+    {
+        $this->relationships[$this->serializerClass][$name] = $callback;
+
+        return $this;
+    }
+
+    public function extend(Container $container, Extension $extension = null)
+    {
+        if (! empty($this->attributes)) {
+            $this->mutators[] = function ($serializer, $model, $attributes) use ($container) {
+                foreach ($this->attributes as $attributeName => $callback) {
+                    $callback = ContainerUtil::wrapCallback($callback, $container);
+
+                    $attributes[$attributeName] = $callback($serializer, $model, $attributes);
+                }
+
+                return $attributes;
+            };
+        }
+
+        foreach ($this->mutators as $mutator) {
+            $mutator = ContainerUtil::wrapCallback($mutator, $container);
+
+            AbstractSerializer::addMutator($this->serializerClass, $mutator);
+        }
+
+        foreach ($this->relationships as $serializerClass => $relationships) {
+            foreach ($relationships as $relation => $callback) {
+                $callback = ContainerUtil::wrapCallback($callback, $container);
+
+                AbstractSerializer::setRelationship($serializerClass, $relation, $callback);
+            }
+        }
+    }
+}