Rename ApiSerializer's mutate to attributes (#2578)

src/Api/Serializer/AbstractSerializer.php

@@ -43,7 +43,7 @@ abstract class AbstractSerializer extends BaseAbstractSerializer
     /**
      * @var callable[]
      */
-    protected static $mutators = [];
+    protected static $attributeMutators = [];
 
     /**
      * @var array
@@ -87,8 +87,8 @@ public function getAttributes($model, array $fields = null)
         $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) {
+            if (isset(static::$attributeMutators[$class])) {
+                foreach (static::$attributeMutators[$class] as $callback) {
                     $attributes = array_merge(
                         $attributes,
                         $callback($this, $model, $attributes)
@@ -281,15 +281,15 @@ public static function setContainer(Container $container)
 
     /**
      * @param string $serializerClass
-     * @param callable $mutator
+     * @param callable $callback
      */
-    public static function addMutator(string $serializerClass, callable $mutator)
+    public static function addAttributeMutator(string $serializerClass, callable $callback)
     {
-        if (! isset(static::$mutators[$serializerClass])) {
-            static::$mutators[$serializerClass] = [];
+        if (! isset(static::$attributeMutators[$serializerClass])) {
+            static::$attributeMutators[$serializerClass] = [];
         }
 
-        static::$mutators[$serializerClass][] = $mutator;
+        static::$attributeMutators[$serializerClass][] = $callback;
     }
 
     /**

src/Extend/ApiSerializer.php

@@ -17,8 +17,8 @@
 class ApiSerializer implements ExtenderInterface
 {
     private $serializerClass;
+    private $attribute = [];
     private $attributes = [];
-    private $mutators = [];
     private $relationships = [];
 
     /**
@@ -46,7 +46,7 @@ public function __construct(string $serializerClass)
      */
     public function attribute(string $name, $callback)
     {
-        $this->attributes[$name] = $callback;
+        $this->attribute[$name] = $callback;
 
         return $this;
     }
@@ -67,13 +67,35 @@ public function attribute(string $name, $callback)
      *
      * @return self
      */
-    public function mutate($callback)
+    public function attributes($callback)
     {
-        $this->mutators[] = $callback;
+        $this->attributes[] = $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.
+     *
+     * @deprecated in beta 16, removed in beta 17
+     * @return self
+     */
+    public function mutate($callback)
+    {
+        return $this->attributes($callback);
+    }
+
     /**
      * Establish a simple hasOne relationship from this serializer to another serializer.
      * This represents a one-to-one relationship.
@@ -133,9 +155,9 @@ public function relationship(string $name, $callback)
 
     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) {
+        if (! empty($this->attribute)) {
+            $this->attributes[] = function ($serializer, $model, $attributes) use ($container) {
+                foreach ($this->attribute as $attributeName => $callback) {
                     $callback = ContainerUtil::wrapCallback($callback, $container);
 
                     $attributes[$attributeName] = $callback($serializer, $model, $attributes);
@@ -145,10 +167,10 @@ public function extend(Container $container, Extension $extension = null)
             };
         }
 
-        foreach ($this->mutators as $mutator) {
-            $mutator = ContainerUtil::wrapCallback($mutator, $container);
+        foreach ($this->attributes as $callback) {
+            $callback = ContainerUtil::wrapCallback($callback, $container);
 
-            AbstractSerializer::addMutator($this->serializerClass, $mutator);
+            AbstractSerializer::addAttributeMutator($this->serializerClass, $callback);
         }
 
         foreach ($this->relationships as $serializerClass => $relationships) {

src/Extend/Settings.php

@@ -39,7 +39,7 @@ public function serializeToForum(string $attributeName, string $key, $callback =
     public function extend(Container $container, Extension $extension = null)
     {
         if (! empty($this->settings)) {
-            AbstractSerializer::addMutator(
+            AbstractSerializer::addAttributeMutator(
                 ForumSerializer::class,
                 function () use ($container) {
                     $settings = $container->make(SettingsRepositoryInterface::class);

tests/integration/extenders/ApiSerializerTest.php

@@ -74,7 +74,7 @@ public function custom_attributes_exist_if_added()
     {
         $this->extend(
             (new Extend\ApiSerializer(ForumSerializer::class))
-                ->mutate(function () {
+                ->attributes(function () {
                     return [
                         'customAttribute' => true
                     ];
@@ -101,7 +101,7 @@ public function custom_attributes_with_invokable_exist_if_added()
     {
         $this->extend(
             (new Extend\ApiSerializer(ForumSerializer::class))
-                ->mutate(CustomAttributesInvokableClass::class)
+                ->attributes(CustomAttributesInvokableClass::class)
         );
 
         $this->app();
@@ -124,7 +124,7 @@ public function custom_attributes_exist_if_added_to_parent_class()
     {
         $this->extend(
             (new Extend\ApiSerializer(BasicUserSerializer::class))
-                ->mutate(function () {
+                ->attributes(function () {
                     return [
                         'customAttribute' => true
                     ];
@@ -151,13 +151,13 @@ public function custom_attributes_prioritize_child_classes()
     {
         $this->extend(
             (new Extend\ApiSerializer(BasicUserSerializer::class))
-                ->mutate(function () {
+                ->attributes(function () {
                     return [
                         'customAttribute' => 'initialValue'
                     ];
                 }),
             (new Extend\ApiSerializer(UserSerializer::class))
-                ->mutate(function () {
+                ->attributes(function () {
                     return [
                         'customAttribute' => 'newValue'
                     ];
@@ -294,7 +294,7 @@ public function custom_attributes_can_be_overriden()
             (new Extend\ApiSerializer(BasicUserSerializer::class))
                 ->attribute('someCustomAttribute', function () {
                     return 'newValue';
-                })->mutate(function () {
+                })->attributes(function () {
                     return [
                         'someCustomAttribute' => 'initialValue',
                         'someOtherCustomAttribute' => 'initialValue',