Import with a foreign key

Author: tatevikg1

src/Domain/Subscription/Model/Dto/ImportSubscriberDto.php

@@ -11,6 +11,12 @@ class ImportSubscriberDto
     #[Assert\NotBlank]
     public string $email;
 
+    /**
+     * Optional external identifier used for matching existing subscribers during import.
+     */
+    #[Assert\Length(max: 191)]
+    public ?string $foreignKey = null;
+
     #[Assert\Type('bool')]
     public bool $confirmed;
 
@@ -37,7 +43,8 @@ public function __construct(
         bool $htmlEmail,
         bool $disabled,
         ?string $extraData = null,
-        array $extraAttributes = []
+        array $extraAttributes = [],
+        ?string $foreignKey = null,
     ) {
         $this->email = $email;
         $this->confirmed = $confirmed;
@@ -47,5 +54,6 @@ public function __construct(
         $this->disabled = $disabled;
         $this->extraData = $extraData;
         $this->extraAttributes = $extraAttributes;
+        $this->foreignKey = $foreignKey;
     }
 }

src/Domain/Subscription/Repository/SubscriberRepository.php

@@ -16,6 +16,7 @@
  *
  * @author Oliver Klee <[email protected]>
  * @author Tatevik Grigoryan <[email protected]>
+ * @SuppressWarnings(PHPMD.TooManyPublicMethods)
  */
 class SubscriberRepository extends AbstractRepository implements PaginatableRepositoryInterface
 {
@@ -41,6 +42,11 @@ public function findOneByUniqueId(string $uniqueId): ?Subscriber
         return $this->findOneBy(['uniqueId' => $uniqueId]);
     }
 
+    public function findOneByForeignKey(string $foreignKey): ?Subscriber
+    {
+        return $this->findOneBy(['foreignKey' => $foreignKey]);
+    }
+
     public function findSubscribersBySubscribedList(int $listId): ?Subscriber
     {
         return $this->createQueryBuilder('s')

src/Domain/Subscription/Service/CsvRowToDtoMapper.php

@@ -8,24 +8,38 @@
 
 class CsvRowToDtoMapper
 {
+    private const FK_HEADER = 'foreignkey';
     private const KNOWN_HEADERS = [
-        'email', 'confirmed', 'blacklisted', 'html_email', 'disabled', 'extra_data',
+        'email', 'confirmed', 'blacklisted', 'html_email', 'disabled', 'extra_data', 'foreignkey',
     ];
 
     public function map(array $row): ImportSubscriberDto
     {
-        $extraAttributes = array_filter($row, function ($key) {
+        // Normalize keys to lower-case for header matching safety (CSV library keeps original headers)
+        $normalizedRow = [];
+        foreach ($row as $key => $value) {
+            $normalizedRow[strtolower((string)$key)] = is_string($value) ? trim($value) : $value;
+        }
+
+        $email = strtolower(trim((string)($normalizedRow['email'] ?? '')));
+
+        if (array_key_exists(self::FK_HEADER, $normalizedRow) && $normalizedRow[self::FK_HEADER] !== '') {
+            $foreignKey = (string)$normalizedRow[self::FK_HEADER];
+        }
+
+        $extraAttributes = array_filter($normalizedRow, function ($key) {
             return !in_array($key, self::KNOWN_HEADERS, true);
         }, ARRAY_FILTER_USE_KEY);
 
         return new ImportSubscriberDto(
-            email: trim($row['email'] ?? ''),
-            confirmed: filter_var($row['confirmed'] ?? false, FILTER_VALIDATE_BOOLEAN),
-            blacklisted: filter_var($row['blacklisted'] ?? false, FILTER_VALIDATE_BOOLEAN),
-            htmlEmail: filter_var($row['html_email'] ?? false, FILTER_VALIDATE_BOOLEAN),
-            disabled: filter_var($row['disabled'] ?? false, FILTER_VALIDATE_BOOLEAN),
-            extraData: $row['extra_data'] ?? null,
-            extraAttributes: $extraAttributes
+            email: $email,
+            confirmed: filter_var($normalizedRow['confirmed'] ?? false, FILTER_VALIDATE_BOOLEAN),
+            blacklisted: filter_var($normalizedRow['blacklisted'] ?? false, FILTER_VALIDATE_BOOLEAN),
+            htmlEmail: filter_var($normalizedRow['html_email'] ?? false, FILTER_VALIDATE_BOOLEAN),
+            disabled: filter_var($normalizedRow['disabled'] ?? false, FILTER_VALIDATE_BOOLEAN),
+            extraData: $normalizedRow['extra_data'] ?? null,
+            extraAttributes: $extraAttributes,
+            foreignKey: $foreignKey ?? null,
         );
     }
 }

src/Domain/Subscription/Service/Manager/SubscriberManager.php

@@ -114,6 +114,9 @@ public function createFromImport(ImportSubscriberDto $subscriberDto): Subscriber
         $subscriber->setHtmlEmail($subscriberDto->htmlEmail);
         $subscriber->setDisabled($subscriberDto->disabled);
         $subscriber->setExtraData($subscriberDto->extraData ?? '');
+        if ($subscriberDto->foreignKey !== null) {
+            $subscriber->setForeignKey($subscriberDto->foreignKey);
+        }
 
         $this->entityManager->persist($subscriber);
 
@@ -129,6 +132,9 @@ public function updateFromImport(Subscriber $existingSubscriber, ImportSubscribe
         $existingSubscriber->setHtmlEmail($subscriberDto->htmlEmail);
         $existingSubscriber->setDisabled($subscriberDto->disabled);
         $existingSubscriber->setExtraData($subscriberDto->extraData);
+        if ($subscriberDto->foreignKey !== null) {
+            $existingSubscriber->setForeignKey($subscriberDto->foreignKey);
+        }
 
         $uow = $this->entityManager->getUnitOfWork();
         $meta = $this->entityManager->getClassMetadata(Subscriber::class);

src/Domain/Subscription/Service/SubscriberCsvImporter.php

@@ -182,7 +182,20 @@ private function processRow(
             return null;
         }
 
-        $subscriber = $this->subscriberRepository->findOneByEmail($dto->email);
+        $subscriberByEmail = $this->subscriberRepository->findOneByEmail($dto->email);
+        $subscriberByFk = null;
+        if ($dto->foreignKey !== null) {
+            $subscriberByFk = $this->subscriberRepository->findOneByForeignKey($dto->foreignKey);
+        }
+
+        if ($subscriberByEmail && $subscriberByFk && $subscriberByEmail->getId() !== $subscriberByFk->getId()) {
+            $stats['skipped']++;
+            $stats['errors'][] = $this->translator->trans('Conflict: email and foreign key refer to different subscribers.');
+            return null;
+        }
+
+        $subscriber = $subscriberByFk ?? $subscriberByEmail;
+
         if ($this->handleSkipCase($subscriber, $options, $stats)) {
             return null;
         }