Add Update Subscrber method to MP API

[MAILPOET-6168]

doc/Readme.md

@@ -27,6 +27,7 @@ Class `\MailPoet\API\API` becomes available once MailPoet plugin is loaded by Wo
 
 - [Add List (addList)](api_methods/AddList.md)
 - [Add Subscriber (addSubscriber)](api_methods/AddSubscriber.md)
+- [Update Subscriber (updateSubscriber)](api_methods/UpdateSubscriber.md)
 - [Add Subscriber Field (addSubscriberField)](api_methods/AddSubscriberField.md)
 - [Delete List (deleteList)](api_methods/DeleteList.md)
 - [Get Lists (getLists)](api_methods/GetLists.md)

doc/api_methods/UpdateSubscriber.md

@@ -0,0 +1,31 @@
+[back to list](../Readme.md)
+
+# Update Subscriber
+
+## `array updateSubscriber($subscriberIdOrEmail, array $subscriber): array`
+
+This method allows a subscriber to be updated.
+The argument `$subscriber` is similar to [Add Subscriber](AddSubscriber.md) method, but the subscriber is updated instead of created.
+
+It returns the updated subscriber. See [Get Subscriber](GetSubscriber.md) for a subscriber data structure.
+
+## Arguments
+
+| Argument             | Type          | Description                               |
+| -------------------- | ------------- | ----------------------------------------- |
+| $subscriberIdOrEmail | string or int | An id or email of an existing subscriber. |
+| $subscriber          | array         | Subscriber data that will be updated      |
+
+## Error handling
+
+All expected errors from the API are exceptions of class `\MailPoet\API\MP\v1\APIException`.
+Code of the exception is populated to distinguish between different errors.
+
+An exception of base class `\Exception` can be thrown when something unexpected happens.
+
+Codes description:
+
+| Code | Description                                        |
+| ---- | -------------------------------------------------- |
+| 4    | Updating a subscriber that does not exist.         |
+| 13   | The subscriber couldn’t be updated in the database |

mailpoet/lib/API/MP/v1/API.php

@@ -80,6 +80,10 @@ class API {
     return $this->subscribers->addSubscriber($subscriber, $listIds, $options);
   }
 
+  public function updateSubscriber($subscriberIdOrEmail, array $subscriber): array {
+    return $this->subscribers->updateSubscriber($subscriberIdOrEmail, $subscriber);
+  }
+
   public function addList(array $list) {
     return $this->segments->addList($list);
   }

mailpoet/lib/API/MP/v1/Subscribers.php

@@ -165,6 +165,46 @@ class Subscribers {
     return $this->subscribersResponseBuilder->build($subscriberEntity);
   }
 
+  public function updateSubscriber($subscriberIdOrEmail, array $data): array {
+    $this->checkSubscriberParam($subscriberIdOrEmail);
+
+    $subscriber = $this->findSubscriber($subscriberIdOrEmail);
+
+    [$defaultFields, $customFields] = $this->extractCustomFieldsFromFromSubscriberData($data);
+
+    $this->requiredCustomFieldsValidator->validate($customFields);
+
+    // filter out all incoming data that we don't want to change, like status ...
+    $defaultFields = array_intersect_key($defaultFields, array_flip(['email', 'first_name', 'last_name', 'subscribed_ip']));
+
+    if (empty($defaultFields['subscribed_ip'])) {
+      $defaultFields['subscribed_ip'] = Helpers::getIP();
+    }
+    $defaultFields['source'] = Source::API;
+
+    try {
+      $subscriberEntity = $this->subscriberSaveController->createOrUpdate($defaultFields, $subscriber);
+    } catch (\Exception $e) {
+      throw new APIException(
+      // translators: %s is an error message.
+        sprintf(__('Failed to update subscriber: %s', 'mailpoet'), $e->getMessage()),
+        APIException::FAILED_TO_SAVE_SUBSCRIBER
+      );
+    }
+
+    try {
+      $this->subscriberSaveController->updateCustomFields($customFields, $subscriberEntity);
+    } catch (\Exception $e) {
+      throw new APIException(
+      // translators: %s is an error message
+        sprintf(__('Failed to save subscriber custom fields: %s', 'mailpoet'), $e->getMessage()),
+        APIException::FAILED_TO_SAVE_SUBSCRIBER
+      );
+    }
+    
+    return $this->subscribersResponseBuilder->build($subscriberEntity);
+  }
+
   /**
    * @throws APIException
    */

mailpoet/tests/integration/API/MP/SubscribersTest.php

@@ -14,6 +14,7 @@ use MailPoet\Config\Changelog;
 use MailPoet\CustomFields\CustomFieldsRepository;
 use MailPoet\Entities\CustomFieldEntity;
 use MailPoet\Entities\SegmentEntity;
+use MailPoet\Entities\SubscriberCustomFieldEntity;
 use MailPoet\Entities\SubscriberEntity;
 use MailPoet\Newsletter\Scheduler\WelcomeScheduler;
 use MailPoet\Segments\SegmentsRepository;
@@ -787,6 +788,28 @@ class SubscribersTest extends \MailPoetTest {
     $API->addSubscriber($subscriber, $segments, $options);
   }
 
+  public function testUpdateSubscriber() {
+    $subscriber = $this->subscriberFactory->create();
+    $customField = $this->customFieldRepository->createOrUpdate([
+      'name' => 'test custom field',
+      'type' => CustomFieldEntity::TYPE_TEXT,
+    ]);
+    $scfe = new SubscriberCustomFieldEntity($subscriber, $customField, 'value');
+    $subscriber->getSubscriberCustomFields()->add($scfe);
+    $this->entityManager->persist($scfe);
+    $this->entityManager->flush();
+
+    $result = $this->getApi()->updateSubscriber($subscriber->getId(), [
+      'email' => 'newemail@example.com',
+      'cf_' . $customField->getId() => 'new value',
+      'first_name' => 'New Name',
+    ]);
+
+    $this->assertEquals('newemail@example.com', $result['email']);
+    $this->assertEquals('New Name', $result['first_name']);
+    $this->assertEquals('new value', $result['cf_' . $customField->getId()]);
+  }
+
   public function testItGetsSubscriber() {
     $subscriber = $this->subscriberFactory->create();
     $segment = $this->getSegment();