Implement purposes of processing personal data (#6)

readme.md

@@ -253,6 +253,18 @@ if ($customField = $api->customFields()->exists('name')) {
 
 ## Changelog
 
+### 0.1.8
+
+* Added purposes for contacts.
+
+### 0.1.7
+
+* Fix incorrect namespace for confirmation request.
+
+### 0.1.6
+
+* Added confirmation request to import settings.
+
 ### 0.1.5
 
 * Removed deprecated API usage in Contact.php: `addContactList` and `newContactList`

src/Request/Import/Contact.php

@@ -6,6 +6,7 @@
 use SmartEmailing\v3\Models\Model;
 use SmartEmailing\v3\Request\Import\Holder\ContactLists;
 use SmartEmailing\v3\Request\Import\Holder\CustomFields;
+use SmartEmailing\v3\Request\Import\Holder\Purposes;
 
 /**
  * Contact wrapper with public properties (allows force set and easy getter). The fluent setter will help
@@ -114,6 +115,12 @@ class Contact extends Model
      * @var CustomFields
      */
     protected $customFields;
+    /**
+     * Processing purposes assigned to contact. Every purpose may be assigned multiple times for different time intervals.
+     * Exact duplicities will be silently skipped.
+     * @var Purposes
+     */
+    protected $purposes;
 
     //endregion
 
@@ -127,6 +134,7 @@ public function __construct($emailAddress)
         $this->emailAddress = $emailAddress;
         $this->customFields = new CustomFields();
         $this->contactLists = new ContactLists();
+        $this->purposes = new Purposes();
     }
 
     //region Setters
@@ -373,6 +381,14 @@ public function customFields()
         return $this->customFields;
     }
 
+    /**
+     * @return Purposes
+     */
+    public function purposes()
+    {
+        return $this->purposes;
+    }
+
     //endregion
 
     /**
@@ -402,7 +418,8 @@ public function toArray()
             'nameday' => $this->nameDay,
             'birthday' => $this->birthday,
             'contactlists' => $this->contactLists,
-            'customfields' => $this->customFields
+            'customfields' => $this->customFields,
+            'purposes' => $this->purposes
         ];
     }
 }

src/Request/Import/Holder/Purposes.php

@@ -0,0 +1,40 @@
+<?php
+namespace SmartEmailing\v3\Request\Import\Holder;
+
+use SmartEmailing\v3\Models\AbstractMapHolder;
+use SmartEmailing\v3\Request\Import\Purpose;
+
+class Purposes extends AbstractMapHolder
+{
+    /**
+     * Inserts purposes into the items. Unique items only.
+     *
+     * @param Purpose $list
+     *
+     * @return $this
+     */
+    public function add(Purpose $list)
+    {
+        $this->insertEntry($list);
+        return $this;
+    }
+
+    /**
+     * Creates Purpose entry and inserts it to the array
+     *
+     * @param int         $id
+     * @param string|null $valid_from   Date and time since processing purpose is valid in YYYY-MM-DD HH:MM:SS format.
+     *                                  If empty, current date and time will be used.
+     * @param string|null $valid_to     Date and time of processing purpose validity end in YYYY-MM-DD HH:MM:SS format.
+     *                                  If empty, it will be calculated as valid_from + default duration of particular
+     *                                  purpose.
+     *
+     * @return Purpose
+     */
+    public function create($id, $valid_from = null, $valid_to = null)
+    {
+        $field = new Purpose($id, $valid_from, $valid_to);
+        $this->add($field);
+        return $field;
+    }
+}

src/Request/Import/Purpose.php

@@ -0,0 +1,117 @@
+<?php
+namespace SmartEmailing\v3\Request\Import;
+
+use SmartEmailing\v3\Exceptions\InvalidFormatException;
+use SmartEmailing\v3\Models\Model;
+
+/**
+ * Processing purposes assigned to contact. Every purpose may be assigned multiple times for different
+ * time intervals. Exact duplicities will be silently skipped.
+ * @package SmartEmailing\v3\Request\Import
+ */
+class Purpose extends Model
+{
+    /**
+     * @var int|null
+     */
+    public $id;
+    /**
+     * Date and time since processing purpose is valid in YYYY-MM-DD HH:MM:SS format. If empty, current date
+     * and time will be used.
+     * @var string Default value: null
+     */
+    public $valid_from = null;
+
+    /**
+     * Date and time of processing purpose validity end in YYYY-MM-DD HH:MM:SS format. If empty, it will be
+     * calculated as valid_from + default duration of particular purpose.
+     * @var string Default value: null
+     */
+    public $valid_to = null;
+
+    /**
+     * Purpose constructor.
+     *
+     * @param int           $id
+     * @param string|null   $valid_from Default value: null
+     * @param string|null   $valid_to Default value: null
+     */
+    public function __construct($id, $valid_from = null, $valid_to = null)
+    {
+        $this->setId($id);
+
+        if (!is_null($valid_from)) {
+            $this->setValidFrom($valid_from);
+        }
+
+        if (!is_null($valid_to)) {
+            $this->setValidTo($valid_to);
+        }
+    }
+
+    /**
+     * @param int $id
+     *
+     * @return Purpose
+     */
+    public function setId($id)
+    {
+        $this->id = intval($id);
+        return $this;
+    }
+
+    /**
+     * Date and time since processing purpose is valid. Allowed format: YYYY-MM-DD HH:MM:SS.
+     *
+     * @param string $valid_from
+     *
+     * @return Purpose
+     */
+    public function setValidFrom($valid_from)
+    {
+        if(!preg_match('(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})', $valid_from))
+            throw new InvalidFormatException(sprintf('Invalid date and time format. Format must be YYYY-MM-DD HH:MM:SS, %s given.', $valid_from));
+
+        $this->valid_from = $valid_from;
+        return $this;
+    }
+
+    /**
+     * Date and time of processing purpose validity end. Allowed format: YYYY-MM-DD HH:MM:SS.
+     *
+     * @param string $valid_to
+     *
+     * @return Purpose
+     */
+    public function setValidTo($valid_to)
+    {
+        if(!preg_match('(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})', $valid_to))
+            throw new InvalidFormatException(sprintf('Invalid date and time format. Format must be YYYY-MM-DD HH:MM:SS, %s given.', $valid_to));
+
+        $this->valid_to = $valid_to;
+        return $this;
+    }
+
+
+    /**
+     * Converts data to array
+     * @return array
+     */
+    public function toArray()
+    {
+        return [
+            'id' => $this->id,
+            'valid_from' => $this->valid_from,
+            'valid_to' => $this->valid_to
+        ];
+    }
+
+    /**
+     * @return array
+     */
+    public function jsonSerialize()
+    {
+        // Don't remove null/empty values - not needed
+        return $this->toArray();
+    }
+}

src/Request/Import/Settings.php

@@ -68,7 +68,7 @@ class Settings extends Model
      * be written when they click through confirmation link.
      *
      * Default value: null
-     * @var Settings\ConfirmationRequest|null
+     * @var ConfirmationRequest|null
      */
     public $confirmationRequest = null;
     //endregion

tests/Request/Import/ContactTest.php

@@ -4,6 +4,7 @@
 use SmartEmailing\v3\Exceptions\InvalidFormatException;
 use SmartEmailing\v3\Request\Import\Contact;
 use SmartEmailing\v3\Request\Import\ContactList;
+use SmartEmailing\v3\Request\Import\Purpose;
 use SmartEmailing\v3\Request\Import\CustomField;
 use SmartEmailing\v3\Tests\TestCase\BaseTestCase;
 
@@ -160,6 +161,25 @@ public function testCreateListUnique()
         $this->assertEquals(ContactList::REMOVED, $list->status);
     }
 
+    public function testAddPurpose()
+    {
+        // This will be stored first
+        $this->contact->purposes()->create(1);
+        // This value will be ignores
+        $this->contact->purposes()->create(1, '1991-06-17 00:00:00', '1998-02-22 05:45:00');
+        $this->contact->purposes()->create(2, '1991-06-17 00:00:00', '1998-02-22 05:45:00');
+        $this->assertCount(2, $this->contact->purposes()->toArray(), 'There should be 2 unique fields');
+
+        /** @var Purpose $list */
+        $list = $this->contact->purposes()->get(0);
+        $this->assertEquals(1, $list->id);
+        $this->assertEquals(null, $list->valid_to);
+
+        $list = $this->contact->purposes()->get(1);
+        $this->assertEquals(2, $list->id);
+        $this->assertEquals('1998-02-22 05:45:00', $list->valid_to);
+    }
+
     public function testJson()
     {
         $this->contact->customFields()->create(1, 'test2', [1]);

tests/Request/Import/PurposeTest.php

@@ -0,0 +1,60 @@
+<?php
+namespace SmartEmailing\v3\Tests\Request\Import;
+
+use SmartEmailing\v3\Request\Import\Purpose;
+use SmartEmailing\v3\Tests\TestCase\BaseTestCase;
+
+class PurposeTest extends BaseTestCase
+{
+    /**
+     * @var Purpose
+     */
+    protected $field;
+
+    protected function setUp()
+    {
+        $this->field = new Purpose(12);
+    }
+
+    public function testConstruct()
+    {
+        $this->assertEquals(12, $this->field->id);
+    }
+
+    public function testConstructNumeric()
+    {
+        $this->assertEquals(13, (new Purpose('13'))->id);
+    }
+
+    public function testSetIdNumeric()
+    {
+        $this->assertEquals(13, $this->field->setId('13')->id);
+    }
+
+    public function testSetValidFrom()
+    {
+        $this->assertEquals('1991-06-17 00:00:00', $this->field->setValidFrom('1991-06-17 00:00:00')->valid_from);
+    }
+
+    public function testSetValidTo()
+    {
+        $this->assertEquals('1991-06-17 00:00:00', $this->field->setValidTo('1991-06-17 00:00:00')->valid_to);
+    }
+
+    public function testDateTimeFormat()
+    {
+        try {
+            $this->field->setValidFrom('1991-06-17');
+            $this->fail('The options should require format YYYY-MM-DD HH:MM:SS');
+        } catch (\Exception $exception) {
+            $this->assertContains('Invalid date and time format', $exception->getMessage());
+        }
+
+        try {
+            $this->field->setValidFrom('test');
+            $this->fail('The options should require format YYYY-MM-DD HH:MM:SS');
+        } catch (\Exception $exception) {
+            $this->assertContains('Invalid date and time format', $exception->getMessage());
+        }
+    }
+}