Import by foreign key

resources/translations/messages.en.xlf

@@ -730,6 +730,10 @@ Thank you.</target>
         <source>Campaign not found or not in submitted status</source>
         <target>__Campaign not found or not in submitted status</target>
       </trans-unit>
+      <trans-unit id="TBYUW2m" resname="Conflict: email and foreign key refer to different subscribers.">
+        <source>Conflict: email and foreign key refer to different subscribers.</source>
+        <target>__Conflict: email and foreign key refer to different subscribers.</target>
+      </trans-unit>
     </body>
   </file>
 </xliff>

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,45 @@
 
 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 = $this->normalizeData($row);
+
+        $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,
         );
     }
+
+    private function normalizeData(array $row): array
+    {
+        $normalizedRow = [];
+        foreach ($row as $key => $value) {
+            $normalizedRow[strtolower((string)$key)] = is_string($value) ? trim($value) : $value;
+        }
+
+        return $normalizedRow;
+    }
 }

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,14 @@ private function processRow(
             return null;
         }
 
-        $subscriber = $this->subscriberRepository->findOneByEmail($dto->email);
+        [$subscriber, $conflictError] = $this->resolveSubscriber($dto);
+
+        if ($conflictError !== null) {
+            $stats['skipped']++;
+            $stats['errors'][] = $conflictError;
+            return null;
+        }
+
         if ($this->handleSkipCase($subscriber, $options, $stats)) {
             return null;
         }
@@ -197,20 +204,7 @@ private function processRow(
 
         $this->attributeManager->processAttributes($subscriber, $dto->extraAttributes);
 
-        $addedNewSubscriberToList = false;
-        $listLines = [];
-        if (!$subscriber->isBlacklisted() && count($options->listIds) > 0) {
-            foreach ($options->listIds as $listId) {
-                $created = $this->subscriptionManager->addSubscriberToAList($subscriber, $listId);
-                if ($created) {
-                    $addedNewSubscriberToList = true;
-                    $listLines[] = $this->translator->trans(
-                        'Subscribed to %list%',
-                        ['%list%' => $created->getSubscriberList()->getName()]
-                    );
-                }
-            }
-        }
+        [$listLines, $addedNewSubscriberToList] = $this->getHistoryListLines($subscriber, $options);
 
         if ($subscriber->isBlacklisted()) {
             $stats['blacklisted']++;
@@ -226,6 +220,22 @@ private function processRow(
         return $this->prepareConfirmationMessage($subscriber, $options, $dto, $addedNewSubscriberToList);
     }
 
+    private function resolveSubscriber(ImportSubscriberDto $dto): array
+    {
+        $byEmail = $this->subscriberRepository->findOneByEmail($dto->email);
+        $byFk = null;
+
+        if ($dto->foreignKey !== null) {
+            $byFk = $this->subscriberRepository->findOneByForeignKey($dto->foreignKey);
+        }
+
+        if ($byEmail && $byFk && $byEmail->getId() !== $byFk->getId()) {
+            return [null, $this->translator->trans('Conflict: email and foreign key refer to different subscribers.')];
+        }
+
+        return [$byFk ?? $byEmail, null];
+    }
+
     private function handleInvalidEmail(
         ImportSubscriberDto $dto,
         SubscriberImportOptions $options,
@@ -277,4 +287,27 @@ private function prepareConfirmationMessage(
 
         return null;
     }
+
+    private function getHistoryListLines(Subscriber $subscriber, SubscriberImportOptions $options): array
+    {
+        $addedNewSubscriberToList = false;
+        $listLines = [];
+        if (!$subscriber->isBlacklisted() && count($options->listIds) > 0) {
+            foreach ($options->listIds as $listId) {
+                $created = $this->subscriptionManager->addSubscriberToAList($subscriber, $listId);
+                if ($created) {
+                    $addedNewSubscriberToList = true;
+                    $listLines[] = $this->translator->trans(
+                        'Subscribed to %list%',
+                        ['%list%' => $created->getSubscriberList()->getName()]
+                    );
+                }
+            }
+        }
+
+        return [
+            $listLines,
+            $addedNewSubscriberToList,
+        ];
+    }
 }

src/Migrations/Version20251103SeedInitialAdmin.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpList\Core\Migrations;
+
+use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+final class Version20251103SeedInitialAdmin extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'Seed initial admin user';
+    }
+
+    public function up(Schema $schema): void
+    {
+        $platform = $this->connection->getDatabasePlatform();
+        $this->skipIf(!$platform instanceof PostgreSQLPlatform, sprintf(
+            'Unsupported platform for this migration: %s',
+            get_class($platform)
+        ));
+
+        $this->addSql(<<<'SQL'
+    INSERT INTO phplist_admin (id, created, modified, loginname, namelc, email, password, passwordchanged, disabled, superuser, privileges)
+    VALUES (1, NOW(), NOW(), 'admin', 'admin', '[email protected]', :hash, CURRENT_DATE, FALSE, TRUE, :privileges)
+    ON CONFLICT (id) DO UPDATE
+    SET 
+        modified = EXCLUDED.modified,
+        privileges = EXCLUDED.privileges
+    SQL, [
+        'hash' => hash('sha256', 'password'),
+        'privileges' => 'a:4:{s:11:"subscribers";b:1;s:9:"campaigns";b:1;s:10:"statistics";b:1;s:8:"settings";b:1;}',
+        ]);
+    }
+
+    public function down(Schema $schema): void
+    {
+        $platform = $this->connection->getDatabasePlatform();
+        $this->skipIf(!$platform instanceof PostgreSQLPlatform, sprintf(
+            'Unsupported platform for this migration: %s',
+            get_class($platform)
+        ));
+
+        $this->addSql('DELETE FROM phplist_admin WHERE id = 1');
+    }
+}