Nodarx/provider_imap
1
0
Fork 0
generated from Nodarx/template
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

refactor: use new mail interface desing

Browse Source 
Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
This commit is contained in:
Sebastian Krupinski
2026-05-14 22:44:28 -04:00
parent b37da945f5
commit ca646eec3c
9 changed files with 311 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
lib/Providers/CollectionResource.php
View File

@@ -91,12 +91,4 @@ class CollectionResource extends CollectionMutableAbstract
return $this->properties;
}
// ── JSON ─────────────────────────────────────────────────────────────────
public function jsonSerialize(): array
{
$data = $this->data;
$data['properties'] = $this->getProperties()->jsonSerialize();
return $data;
}
}

22
lib/Providers/EntityResource.php
View File

@@ -9,7 +9,6 @@ declare(strict_types=1);
namespace KTXM\ProviderImap\Providers;
use DateTimeInterface;
use KTXM\ProviderImap\Client\Message;
use KTXF\Mail\Entity\EntityMutableAbstract;
@@ -43,27 +42,6 @@ class EntityResource extends EntityMutableAbstract {
return $this;
}
/**
* Convert mail entity object to store array
*/
public function toStore(): array {
return array_merge(
$this->data,
['properties' => $this->getProperties()->toStore()]
);
}
/**
* Hydrate mail entity object from store array
*/
public function fromStore(array $data): static {
$properties = $data['properties'] ?? [];
unset($data['properties']);
$this->data = $data;
$this->getProperties()->fromStore($properties);
return $this;
}
/**
* @inheritDoc
*/

146
lib/Providers/MessageProperties.php
View File

@@ -25,71 +25,74 @@ class MessageProperties extends MessagePropertiesMutableAbstract {
*/
public function fromImap(Message $message): static
{
$this->data['size'] = $message->size();
$this->data['flags'] = [];
foreach ($message->flags() as $flag) {
$flag = ltrim($flag, '\\');
$normalized = match (strtolower($flag)) {
'seen' => 'read',
'flagged' => 'flagged',
'answered' => 'answered',
'draft' => 'draft',
'deleted' => 'deleted',
default => strtolower($flag),
};
$this->data['flags'][$normalized] = true;
}
$this->data[static::PROPERTY_SIZE] = $message->size();
if ($message->messageId() !== null) {
$this->data['urid'] = $message->messageId();
$this->data[static::PROPERTY_URID] = $message->messageId();
}
if ($message->subject() !== null) {
$this->data['subject'] = $message->subject();
if ($message->inReplyTo() !== null) {
$this->data[static::PROPERTY_IN_REPLY_TO] = $message->inReplyTo();
}
//if ($message->references() !== []) {
// $this->data[static::PROPERTY_REFERENCES] = $message->references();
//}
$receivedAt = $message->receivedAt() ?? $message->internalDate();
if ($receivedAt !== null) {
$date = new DateTimeImmutable($receivedAt);
$this->data[static::PROPERTY_RECEIVED] = $date->format(DateTimeInterface::ATOM);
}
if ($message->sentAt() !== null) {
$date = new DateTimeImmutable($message->sentAt());
$this->data['date'] = $date->format(DateTimeInterface::ATOM);
}
if ($message->inReplyTo() !== null) {
$this->data['inReplyTo'] = $message->inReplyTo();
}
if ($message->from() !== []) {
$this->data['from'] = $message->from()[0]->toArray();
$this->data[static::PROPERTY_SENT] = $date->format(DateTimeInterface::ATOM);
}
if ($message->sender() !== []) {
$this->data['sender'] = $message->sender()[0]->toArray();
$this->data[static::PROPERTY_SENDER] = $message->sender()[0]->toArray();
}
foreach (['to', 'cc', 'bcc', 'replyTo'] as $field) {
if ($message->from() !== []) {
$this->data[static::PROPERTY_FROM] = $message->from()[0]->toArray();
}
$addressProperties = [
'to' => static::PROPERTY_TO,
'cc' => static::PROPERTY_CC,
'bcc' => static::PROPERTY_BCC,
'replyTo' => static::PROPERTY_REPLY_TO,
];
foreach ($addressProperties as $field => $property) {
$addresses = $message->{$field}();
if ($addresses === []) {
continue;
}
$this->data[$field] = array_map(
$this->data[$property] = array_map(
static fn ($address): array => $address->toArray(),
$addresses,
);
}
if ($message->subject() !== null) {
$this->data[static::PROPERTY_SUBJECT] = $message->subject();
}
if ($message->bodyStructure() !== null) {
$this->data['body'] = $message->bodyStructure()->toArray();
$this->data[static::PROPERTY_BODY] = $message->bodyStructure()->toArray();
$attachments = [];
self::collectAttachments($message->bodyStructure(), $attachments);
$this->collectAttachments($message->bodyStructure(), $attachments);
if ($attachments !== []) {
$this->data['attachments'] = $attachments;
$this->data[static::PROPERTY_ATTACHMENTS] = $attachments;
}
}
if ($message->bodyStructure() !== null) {
$this->data['body'] = $message->bodyStructure()->toArray();
$this->data[static::PROPERTY_BODY] = $message->bodyStructure()->toArray();
// Recursively add content from bodyValues to matching parts
if (is_array($message->bodySections())) {
$addContentToParts = function(&$structure, $bodyValues) use (&$addContentToParts) {
@@ -105,77 +108,36 @@ class MessageProperties extends MessagePropertiesMutableAbstract {
}
};
$addContentToParts($this->data['body'], $message->bodySections());
$addContentToParts($this->data[static::PROPERTY_BODY], $message->bodySections());
}
}
$this->data[static::PROPERTY_FLAGS] = [];
foreach ($message->flags() as $flag) {
$flag = ltrim($flag, '\\');
$normalized = match (strtolower($flag)) {
'seen' => 'read',
'flagged' => 'flagged',
'answered' => 'answered',
'draft' => 'draft',
'deleted' => 'deleted',
default => strtolower($flag),
};
$this->data[static::PROPERTY_FLAGS][$normalized] = true;
}
return $this;
}
public function toImap(): array
{
$message = [];
if (isset($this->data['flags'])) {
$message['flags'] = $this->data['flags'];
}
return $message;
}
/**
* Hydrate from store array
*/
public function fromStore(array $data): static {
$this->data = $data;
return $this;
}
/**
* Serialize to store array
*/
public function toStore(): array {
return $this->data;
}
/**
* Convert a string to UTF-8 from the given charset.
*
* Tries mb_convert_encoding first; falls back to iconv when mbstring does
* not recognise the charset name (e.g. "windows-1250").
*/
public static function toUtf8(string $content, string $charset): string
{
if ($charset === '' || in_array(strtolower($charset), ['utf-8', 'utf8'], true)) {
// Content claims to be UTF-8 but may still have invalid sequences; scrub to be safe.
return mb_convert_encoding($content, 'UTF-8', 'UTF-8');
}
// Try mbstring first
try {
$converted = mb_convert_encoding($content, 'UTF-8', $charset);
if ($converted !== false) {
return $converted;
}
} catch (\ValueError) {
// charset not recognised by mbstring — fall through to iconv
}
// iconv fallback (handles Windows-125x, ISO-8859-*, etc.)
$converted = @iconv($charset, 'UTF-8//TRANSLIT//IGNORE', $content);
$content = ($converted !== false) ? $converted : $content;
// Final scrub: strip any residual invalid UTF-8 bytes so json_encode never fails.
return mb_convert_encoding($content, 'UTF-8', 'UTF-8');
}
/**
* Recursively collect attachment parts from body structure
*/
private static function collectAttachments(ClientMessagePart $part, array &$attachments): void
private function collectAttachments(ClientMessagePart $part, array &$attachments): void
{
$children = $part->parts();
if ($children !== []) {
foreach ($children as $childPart) {
self::collectAttachments($childPart, $attachments);
$this->collectAttachments($childPart, $attachments);
}
return;
}

5
lib/Providers/Provider.php
View File

@@ -14,6 +14,7 @@ use KTXF\Mail\Provider\ProviderServiceDiscoverInterface;
use KTXF\Mail\Provider\ProviderServiceMutateInterface;
use KTXF\Mail\Provider\ProviderServiceTestInterface;
use KTXF\Mail\Service\ServiceBaseInterface;
use KTXF\Mail\Service\ServiceMutableInterface;
use KTXF\Resource\Provider\ResourceServiceLocationInterface;
use KTXF\Resource\Provider\ResourceServiceMutateInterface;
use KTXM\ProviderImap\Service\Discovery;
@@ -23,7 +24,7 @@ use KTXM\ProviderImap\Stores\ServiceStore;
/**
* IMAP Mail Provider
*/
class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscoverInterface, ProviderServiceTestInterface
class Provider implements ProviderBaseInterface, ProviderServiceMutateInterface, ProviderServiceDiscoverInterface, ProviderServiceTestInterface
{
public const JSON_TYPE = ProviderBaseInterface::JSON_TYPE;
@@ -180,7 +181,7 @@ class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscove
return $discovery->discover($identity, $location, $secret, $verifySSL);
}
public function serviceTest(ServiceBaseInterface $service, array $options = []): array
public function serviceTest(ServiceBaseInterface|ServiceMutableInterface $service, array $options = []): array
{
$startTime = microtime(true);

98
lib/Providers/Service.php
View File

@@ -12,8 +12,7 @@ namespace KTXM\ProviderImap\Providers;
use Generator;
use KTXF\Mail\Collection\CollectionBaseInterface;
use KTXF\Mail\Collection\CollectionMutableInterface;
use KTXF\Mail\Entity\EntityBaseInterface;
use KTXF\Mail\Entity\EntityMutableInterface;
use KTXF\Mail\Collection\CollectionPropertiesBaseInterface;
use KTXF\Mail\Object\Address;
use KTXF\Mail\Object\AddressInterface;
use KTXF\Mail\Service\ServiceBaseInterface;
@@ -41,6 +40,7 @@ use KTXM\ProviderImap\Service\Remote\RemoteService;
use KTXM\ProviderImap\Providers\CollectionResource;
use KTXF\Mail\Collection\CollectionRoles;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Mail\Service\ServiceEntityMutableInterface;
use KTXM\ProviderImap\Providers\EntityResource;
/**
@@ -48,8 +48,6 @@ use KTXM\ProviderImap\Providers\EntityResource;
*/
class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceConfigurableInterface, ServiceCollectionMutableInterface, ServiceEntityMutableInterface
{
public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE;
private const PROVIDER_IDENTIFIER = 'imap';
private ?string $serviceTenantId = null;
@@ -92,6 +90,11 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
self::CAPABILITY_ENTITY_LIST_RANGE => ['tally' => ['absolute', 'relative']],
self::CAPABILITY_ENTITY_EXTANT => true,
self::CAPABILITY_ENTITY_FETCH => true,
self::CAPABILITY_ENTITY_CREATE => false,
self::CAPABILITY_ENTITY_MODIFY => false,
self::CAPABILITY_ENTITY_DELETE => true,
self::CAPABILITY_ENTITY_MOVE => true,
self::CAPABILITY_ENTITY_COPY => false,
];
private RemoteMailService $mailService;
@@ -359,7 +362,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
$this->initialize();
$list = [];
foreach ($this->mailService->collectionList($location, $filter, $sort) as $mailbox) {
$resource = $this->collectionFresh();
$resource->fromImap($mailbox);
@@ -383,12 +386,16 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
{
$this->initialize();
$mailboxes = $this->collectionList(null);
$extant = [];
foreach ($identifiers as $id) {
$extant[(string) $id] = isset($mailboxes[(string) $id]);
$list = [];
foreach ($identifiers as $identifier) {
$key = (string) $identifier;
$result = $this->mailService->collectionFetch($key);
$list[$key] = $result !== false;
}
return $extant;
return $list;
}
public function collectionFetch(string|int $identifier): ?CollectionBaseInterface
@@ -411,17 +418,23 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
return new CollectionResource($this->provider(), $this->identifier());
}
public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface
public function collectionCreate(CollectionIdentifier|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface
{
$this->initialize();
if (!$properties->getLabel()) {
throw new \InvalidArgumentException('Collection label is required property');
}
$label = $properties->getLabel();
// Resolve the full name: if a parent location is given, prepend it
$label = $collection->getProperties()->getLabel() ?? '';
if ($location !== null && $location !== '') {
if ($target !== null) {
$path = $target->collection();
// Determine the hierarchy delimiter from an existing mailbox, default to '/'
$mailboxes = iterator_to_array($this->mailService->collectionList(null, null, null, ''));
$delimiter = $mailboxes ? reset($mailboxes)->delimiter() ?? '/' : '/';
$label = rtrim((string) $location, $delimiter) . $delimiter . ltrim($label, $delimiter);
$rootMailbox = $mailboxes === [] ? null : reset($mailboxes);
$delimiter = $rootMailbox === false ? '/' : ($rootMailbox?->delimiter() ?? '/');
$label = rtrim((string) $path, $delimiter) . $delimiter . ltrim($label, $delimiter);
}
$mailbox = $this->mailService->collectionCreate($label);
@@ -432,20 +445,26 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
return $collection;
}
public function collectionUpdate(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface
public function collectionUpdate(CollectionIdentifier $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface
{
$this->initialize();
if (!$properties->getLabel()) {
throw new \InvalidArgumentException('Collection label is a required property');
}
$label = $properties->getLabel();
// In IMAP, "update" = rename to the new label
$newName = $collection->getProperties()->getLabel() ?? (string) $identifier;
$mailbox = $this->mailService->collectionRename((string) $identifier, $newName);
$oldPath = (string) $target->collection();
$newName = $properties->getLabel();
$mailbox = $this->mailService->collectionRename($oldPath, $newName);
$collection = $this->collectionFresh();
$collection->fromImap($mailbox);
return $collection;
}
public function collectionDelete(string|int $identifier, bool $force = false): CollectionBaseInterface | true
public function collectionDelete(CollectionIdentifier $target, bool $force = false): CollectionBaseInterface | true
{
$this->initialize();
@@ -458,7 +477,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
// Move to target collection (e.g. Trash) instead of deleting
if ($deleteMode === 'soft' && $deleteTarget !== null) {
return $this->collectionMove((string) $identifier, (string) $deleteTarget);
return $this->collectionMove($target, new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget));
}
if ($deleteMode === 'soft' && $deleteTarget === null) {
@@ -474,24 +493,24 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
}
// we need to determine if the folder being deleted is already in the trash
if (str_starts_with((string) $identifier, (string) $deleteTarget)) {
if (str_starts_with((string) $target->collection(), (string) $deleteTarget)) {
// if so, we should hard delete instead of moving to avoid duplicates in the trash
$deleteMode = 'hard';
}
$result = match ($deleteMode) {
'soft' => $this->collectionMove((string) $identifier, (string) $deleteTarget),
'hard' => $this->mailService->collectionDestroy((string) $identifier)
'soft' => $this->collectionMove($target, new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget)),
'hard' => $this->mailService->collectionDestroy((string) $target->collection()),
};
return $result;
}
public function collectionMove(string|int $identifier, string|int|null $target): CollectionBaseInterface
public function collectionMove(CollectionIdentifier $target, CollectionIdentifier $source): CollectionBaseInterface
{
$this->initialize();
$sourceMailbox = $this->mailService->collectionFetch((string) $identifier);
$targetMailbox = $this->mailService->collectionFetch((string) $target);
$sourceMailbox = $this->mailService->collectionFetch((string) $source->collection());
$targetMailbox = $this->mailService->collectionFetch((string) $target->collection());
if ($sourceMailbox === null) {
throw new \RuntimeException('Source collection not found for move operation');
}
@@ -514,7 +533,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array
{
return itterator_to_array($this->entityList((string) $collection, $filter, $sort, $range), true);
return iterator_to_array($this->entityList((string) $collection, $filter, $sort, $range), true);
}
public function entityListStream(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): Generator
@@ -579,12 +598,12 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
public function entityCreate(CollectionIdentifier $target, MessagePropertiesMutableInterface $properties, array $options = []): EntityResource
{
return $this->entityFresh();
throw new \RuntimeException('Entity creation is not supported in this service');
}
public function entityModify(EntityIdentifier $target, MessagePropertiesMutableInterface $properties): EntityResource
{
return $this->entityFresh();
throw new \RuntimeException('Entity modification is not supported in this service');
}
public function entityDelete(EntityIdentifier ...$targets): array
@@ -613,7 +632,12 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
throw new \RuntimeException('No Trash collection configured or found for deletion');
}
$deleteTargetNative = reset($mailboxes)->name();
$rootMailbox = reset($mailboxes);
if ($rootMailbox === false) {
throw new \RuntimeException('No Trash collection configured or found for deletion');
}
$deleteTargetNative = $rootMailbox->name();
$deleteTargetIdentifier = new CollectionIdentifier($this->provider(), (string) $this->identifier(), $deleteTargetNative);
} else {
$deleteTargetNative = $deleteTarget;
@@ -636,7 +660,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
foreach ($uids as $uid) {
$mutatedUid = $mutations[$uid] ?? null;
$results[(string)$sourceEntities[$uid]] = [
$list[(string)$sourceEntities[$uid]] = [
'disposition' => $deleteMode === 'soft' ? 'moved' : 'deleted',
'destination' => $deleteMode === 'soft' ? $deleteTargetIdentifier : null,
'mutation' => $mutatedUid !== null ? new EntityIdentifier($this->provider(), $this->identifier(), $deleteTargetIdentifier->collection(), $mutatedUid) : null,
@@ -644,7 +668,12 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
}
}
return $results;
return $list;
}
public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array
{
throw new \RuntimeException('Entity patching is not supported in this service');
}
public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array
@@ -736,6 +765,11 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
return $list;
}
public function entityCopy(CollectionIdentifier $target, EntityIdentifier ...$sources): array
{
throw new \RuntimeException('Entity copying is not supported in this service');
}
private function groupEntitiesByCollection(EntityIdentifier ...$identifiers): array
{
$list = [];