Nodarx/server
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

lots of improvements

Browse Source
This commit is contained in:
root
2026-02-10 17:47:48 -05:00
parent 6d0c5584bd
commit b87b5d9052
65 changed files with 3445 additions and 1577 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
shared/lib/Mail/Collection/CollectionBaseAbstract.php Normal file
View File

@@ -0,0 +1,31 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodeBaseAbstract;
/**
* Abstract Mail Collection Base Class
*
* Provides common implementation for mail collections
*
* @since 2025.05.01
*/
abstract class CollectionBase extends NodeBaseAbstract implements CollectionBaseInterface {
protected CollectionPropertiesBaseAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): CollectionPropertiesBaseInterface {
return $this->properties;
}
}

30
shared/lib/Mail/Collection/CollectionBaseInterface.php Normal file
View File

@@ -0,0 +1,30 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodeBaseInterface;
/**
* Mail Collection Base Interface
*
* Interface represents a mailbox/folder in a mail service
*
* @since 2025.05.01
*/
interface CollectionBaseInterface extends NodeBaseInterface {
/**
* Gets the collection properties
*
* @since 2025.05.01
*/
public function getProperties(): CollectionPropertiesBaseInterface|CollectionPropertiesMutableInterface;
}

49
shared/lib/Mail/Collection/CollectionMutableAbstract.php Normal file
View File

@@ -0,0 +1,49 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodeMutableAbstract;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Abstract Mail Collection Mutable Class
*
* Provides common implementation for mutable mail collections
*
* @since 2025.05.01
*/
abstract class CollectionMutableAbstract extends NodeMutableAbstract implements CollectionMutableInterface {
protected CollectionPropertiesMutableAbstract $properties;
/**
* @inheritDoc
*/
public function getProperties(): CollectionPropertiesMutableInterface {
return $this->properties;
}
/**
* @inheritDoc
*/
public function setProperties(NodePropertiesMutableInterface $value): static {
if (!$value instanceof CollectionPropertiesMutableInterface) {
throw new \InvalidArgumentException('Properties must implement CollectionPropertiesMutableInterface');
}
// Copy all property values
$this->properties->setLabel($value->getLabel());
$this->properties->setRole($value->getRole());
$this->properties->setRank($value->getRank());
$this->properties->setSubscription($value->getSubscription());
return $this;
}
}

32
shared/lib/Mail/Collection/CollectionMutableInterface.php Normal file
View File

@@ -0,0 +1,32 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodeMutableInterface;
/**
* Mail Collection Mutable Interface
*
* Interface for altering mailbox/folder properties in a mail service
*
* @since 2025.05.01
*
* @method static setProperties(CollectionPropertiesMutableInterface $value)
*/
interface CollectionMutableInterface extends CollectionBaseInterface, NodeMutableInterface {
/**
* Gets the collection properties (mutable)
*
* @since 2025.05.01
*/
public function getProperties(): CollectionPropertiesMutableInterface;
}

68
shared/lib/Mail/Collection/CollectionPropertiesBaseAbstract.php Normal file
View File

@@ -0,0 +1,68 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
/**
* Abstract Mail Collection Properties Base Class
*
* Provides common implementation for mail collection properties
*
* @since 2025.05.01
*/
abstract class CollectionPropertiesBaseAbstract extends NodePropertiesBaseAbstract implements CollectionPropertiesBaseInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function total(): int {
return $this->data['total'] ?? 0;
}
/**
* @inheritDoc
*/
public function unread(): int {
return $this->data['unread'] ?? 0;
}
/**
* @inheritDoc
*/
public function getLabel(): string {
return $this->data['label'] ?? '';
}
/**
* @inheritDoc
*/
public function getRole(): CollectionRoles {
return isset($this->data['role'])
? ($this->data['role'] instanceof CollectionRoles ? $this->data['role'] : CollectionRoles::from($this->data['role']))
: CollectionRoles::Custom;
}
/**
* @inheritDoc
*/
public function getRank(): int {
return $this->data['rank'] ?? 0;
}
/**
* @inheritDoc
*/
public function getSubscription(): bool {
return $this->data['subscribed'] ?? false;
}
}

35
shared/lib/Mail/Collection/CollectionPropertiesBaseInterface.php Normal file
View File

@@ -0,0 +1,35 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
interface CollectionPropertiesBaseInterface extends NodePropertiesBaseInterface {
public const JSON_TYPE = 'mail.collection';
public const JSON_PROPERTY_TOTAL = 'total';
public const JSON_PROPERTY_UNREAD = 'unread';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_ROLE = 'role';
public const JSON_PROPERTY_RANK = 'rank';
public const JSON_PROPERTY_SUBSCRIPTION = 'subscription';
public function total(): int;
public function unread(): int;
public function getLabel(): string;
public function getRole(): CollectionRoles;
public function getRank(): int;
public function getSubscription(): bool;
}

65
shared/lib/Mail/Collection/CollectionPropertiesMutableAbstract.php Normal file
View File

@@ -0,0 +1,65 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesMutableAbstract;
/**
* Abstract Mail Collection Properties Mutable Class
*/
abstract class CollectionPropertiesMutableAbstract extends CollectionPropertiesBaseAbstract implements CollectionPropertiesMutableInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function jsonDeserialize(array|string $data): static {
if (is_string($data)) {
$data = json_decode($data, true);
}
$this->data = $data;
return $this;
}
/**
* @inheritDoc
*/
public function setLabel(string $value): static {
$this->data['label'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setRole(CollectionRoles $value): static {
$this->data['role'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setRank(int $value): static {
$this->data['rank'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSubscription(bool $value): static {
$this->data['subscription'] = $value;
return $this;
}
}

26
shared/lib/Mail/Collection/CollectionPropertiesMutableInterface.php Normal file
View File

@@ -0,0 +1,26 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
interface CollectionPropertiesMutableInterface extends CollectionPropertiesBaseInterface, NodePropertiesMutableInterface {
public const JSON_TYPE = CollectionPropertiesBaseInterface::JSON_TYPE;
public function setLabel(string $value);
public function setRole(CollectionRoles $value): static;
public function setRank(int $value): static;
public function setSubscription(bool $value): static;
}

117
shared/lib/Mail/Collection/ICollectionBase.php
View File

@@ -1,117 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
use DateTimeImmutable;
use JsonSerializable;
/**
* Mail Collection Base Interface
*
* Represents a mailbox/folder in a mail service.
* For future use with full mail providers (IMAP, JMAP, etc.)
*
* @since 2025.05.01
*/
interface ICollectionBase extends JsonSerializable {
public const JSON_TYPE = 'mail.collection';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_PROVIDER = 'provider';
public const JSON_PROPERTY_SERVICE = 'service';
public const JSON_PROPERTY_IN = 'in';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_ROLE = 'role';
public const JSON_PROPERTY_TOTAL = 'total';
public const JSON_PROPERTY_UNREAD = 'unread';
/**
* Gets the parent collection identifier (null for root)
*
* @since 2025.05.01
*
* @return string|int|null
*/
public function in(): string|int|null;
/**
* Gets the collection identifier
*
* @since 2025.05.01
*
* @return string|int
*/
public function id(): string|int;
/**
* Gets the collection label/name
*
* @since 2025.05.01
*
* @return string
*/
public function getLabel(): string;
/**
* Gets the collection role
*
* @since 2025.05.01
*
* @return CollectionRoles
*/
public function getRole(): CollectionRoles;
/**
* Gets the total message count
*
* @since 2025.05.01
*
* @return int|null
*/
public function getTotal(): ?int;
/**
* Gets the unread message count
*
* @since 2025.05.01
*
* @return int|null
*/
public function getUnread(): ?int;
/**
* Gets the collection signature/sync token
*
* @since 2025.05.01
*
* @return string|null
*/
public function getSignature(): ?string;
/**
* Gets the creation date
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function created(): ?DateTimeImmutable;
/**
* Gets the modification date
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function modified(): ?DateTimeImmutable;
}

98
shared/lib/Mail/Collection/ICollectionMutable.php
View File

@@ -1,98 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Collection;
/**
* Mail Collection Mutable Interface
*
* Interface for creating and modifying mail collections with fluent setters.
*
* @since 2025.05.01
*/
interface ICollectionMutable extends ICollectionBase {
/**
* Sets the parent collection identifier
*
* @since 2025.05.01
*
* @param string|int|null $in Parent collection ID or null for root
*
* @return self
*/
public function setIn(string|int|null $in): self;
/**
* Sets the collection identifier
*
* @since 2025.05.01
*
* @param string|int $id
*
* @return self
*/
public function setId(string|int $id): self;
/**
* Sets the collection label/name
*
* @since 2025.05.01
*
* @param string $label
*
* @return self
*/
public function setLabel(string $label): self;
/**
* Sets the collection role
*
* @since 2025.05.01
*
* @param CollectionRoles $role
*
* @return self
*/
public function setRole(CollectionRoles $role): self;
/**
* Sets the total message count
*
* @since 2025.05.01
*
* @param int|null $total
*
* @return self
*/
public function setTotal(?int $total): self;
/**
* Sets the unread message count
*
* @since 2025.05.01
*
* @param int|null $unread
*
* @return self
*/
public function setUnread(?int $unread): self;
/**
* Sets the collection signature/sync token
*
* @since 2025.05.01
*
* @param string|null $signature
*
* @return self
*/
public function setSignature(?string $signature): self;
}

32
shared/lib/Mail/Entity/EntityBaseAbstract.php Normal file
View File

@@ -0,0 +1,32 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesBaseInterface;
use KTXF\Resource\Provider\Node\NodeBaseAbstract;
/**
* Abstract Mail Entity Base Class
*
* Provides common implementation for mail entities
*
* @since 2025.05.01
*/
abstract class EntityBaseAbstract extends NodeBaseAbstract implements EntityBaseInterface {
protected MessagePropertiesBaseInterface $properties;
/**
* @inheritDoc
*/
public function getProperties(): MessagePropertiesBaseInterface {
return $this->properties;
}
}

27
shared/lib/Mail/Entity/EntityBaseInterface.php Normal file
View File

@@ -0,0 +1,27 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesBaseInterface;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Resource\Provider\Node\NodeBaseInterface;
interface EntityBaseInterface extends NodeBaseInterface {
public const JSON_TYPE = 'mail.entity';
/**
* Gets the entity properties
*
* @since 2025.05.01
*/
public function getProperties(): MessagePropertiesBaseInterface|MessagePropertiesMutableInterface;
}

48
shared/lib/Mail/Entity/EntityMutableAbstract.php Normal file
View File

@@ -0,0 +1,48 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Resource\Provider\Node\NodeMutableAbstract;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Abstract Mail Entity Mutable Class
*
* Provides common implementation for mutable mail entities
*
* @since 2025.05.01
*/
abstract class EntityMutableAbstract extends NodeMutableAbstract implements EntityMutableInterface {
public const JSON_TYPE = EntityMutableInterface::JSON_TYPE;
protected MessagePropertiesMutableInterface $properties;
/**
* @inheritDoc
*/
public function getProperties(): MessagePropertiesMutableInterface {
return $this->properties;
}
/**
* @inheritDoc
*/
public function setProperties(NodePropertiesMutableInterface $value): static {
if (!$value instanceof MessagePropertiesMutableInterface) {
throw new \InvalidArgumentException('Properties must implement MessagePropertiesMutableInterface');
}
$this->properties = $value;
return $this;
}
}

29
shared/lib/Mail/Entity/EntityMutableInterface.php Normal file
View File

@@ -0,0 +1,29 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Resource\Provider\Node\NodeMutableInterface;
/**
* @method static setProperties(MessagePropertiesMutableInterface $value)
*/
interface EntityMutableInterface extends EntityBaseInterface, NodeMutableInterface {
public const JSON_TYPE = EntityBaseInterface::JSON_TYPE;
/**
* Gets the entity properties (mutable)
*
* @since 2025.05.01
*/
public function getProperties(): MessagePropertiesMutableInterface;
}

176
shared/lib/Mail/Entity/IMessageBase.php
View File

@@ -1,176 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use DateTimeImmutable;
use JsonSerializable;
/**
* Mail Message Base Interface
*
* Read-only interface for mail message entities.
*
* @since 2025.05.01
*/
interface IMessageBase extends JsonSerializable {
public const JSON_TYPE = 'mail.message';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_SUBJECT = 'subject';
public const JSON_PROPERTY_FROM = 'from';
public const JSON_PROPERTY_REPLY_TO = 'replyTo';
public const JSON_PROPERTY_TO = 'to';
public const JSON_PROPERTY_CC = 'cc';
public const JSON_PROPERTY_BCC = 'bcc';
public const JSON_PROPERTY_DATE = 'date';
public const JSON_PROPERTY_BODY_TEXT = 'bodyText';
public const JSON_PROPERTY_BODY_HTML = 'bodyHtml';
public const JSON_PROPERTY_ATTACHMENTS = 'attachments';
public const JSON_PROPERTY_HEADERS = 'headers';
/**
* Gets the message identifier
*
* @since 2025.05.01
*
* @return string|null Message ID or null for unsent messages
*/
public function getId(): ?string;
/**
* Gets the message subject
*
* @since 2025.05.01
*
* @return string
*/
public function getSubject(): string;
/**
* Gets the sender address
*
* @since 2025.05.01
*
* @return IAddress|null
*/
public function getFrom(): ?IAddress;
/**
* Gets the reply-to address
*
* @since 2025.05.01
*
* @return IAddress|null
*/
public function getReplyTo(): ?IAddress;
/**
* Gets the primary recipients (To)
*
* @since 2025.05.01
*
* @return array<int, IAddress>
*/
public function getTo(): array;
/**
* Gets the carbon copy recipients (CC)
*
* @since 2025.05.01
*
* @return array<int, IAddress>
*/
public function getCc(): array;
/**
* Gets the blind carbon copy recipients (BCC)
*
* @since 2025.05.01
*
* @return array<int, IAddress>
*/
public function getBcc(): array;
/**
* Gets the message date
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function getDate(): ?DateTimeImmutable;
/**
* Gets the plain text body
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBodyText(): ?string;
/**
* Gets the HTML body
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBodyHtml(): ?string;
/**
* Gets the attachments
*
* @since 2025.05.01
*
* @return array<int, IAttachment>
*/
public function getAttachments(): array;
/**
* Gets custom headers
*
* @since 2025.05.01
*
* @return array<string, string> Header name => value
*/
public function getHeaders(): array;
/**
* Gets a specific header value
*
* @since 2025.05.01
*
* @param string $name Header name
*
* @return string|null Header value or null if not set
*/
public function getHeader(string $name): ?string;
/**
* Checks if the message has any recipients
*
* @since 2025.05.01
*
* @return bool True if To, CC, or BCC has at least one recipient
*/
public function hasRecipients(): bool;
/**
* Checks if the message has any body content
*
* @since 2025.05.01
*
* @return bool True if text or HTML body is set
*/
public function hasBody(): bool;
}

211
shared/lib/Mail/Entity/IMessageMutable.php
View File

@@ -1,211 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use DateTimeImmutable;
/**
* Mail Message Mutable Interface
*
* Interface for composing and modifying mail messages with fluent setters.
*
* @since 2025.05.01
*/
interface IMessageMutable extends IMessageBase {
/**
* Sets the message identifier
*
* @since 2025.05.01
*
* @param string|null $id
*
* @return self
*/
public function setId(?string $id): self;
/**
* Sets the message subject
*
* @since 2025.05.01
*
* @param string $subject
*
* @return self
*/
public function setSubject(string $subject): self;
/**
* Sets the sender address
*
* @since 2025.05.01
*
* @param IAddress|null $from
*
* @return self
*/
public function setFrom(?IAddress $from): self;
/**
* Sets the reply-to address
*
* @since 2025.05.01
*
* @param IAddress|null $replyTo
*
* @return self
*/
public function setReplyTo(?IAddress $replyTo): self;
/**
* Sets the primary recipients (To)
*
* @since 2025.05.01
*
* @param array<int, IAddress> $to
*
* @return self
*/
public function setTo(array $to): self;
/**
* Adds a primary recipient (To)
*
* @since 2025.05.01
*
* @param IAddress $address
*
* @return self
*/
public function addTo(IAddress $address): self;
/**
* Sets the carbon copy recipients (CC)
*
* @since 2025.05.01
*
* @param array<int, IAddress> $cc
*
* @return self
*/
public function setCc(array $cc): self;
/**
* Adds a carbon copy recipient (CC)
*
* @since 2025.05.01
*
* @param IAddress $address
*
* @return self
*/
public function addCc(IAddress $address): self;
/**
* Sets the blind carbon copy recipients (BCC)
*
* @since 2025.05.01
*
* @param array<int, IAddress> $bcc
*
* @return self
*/
public function setBcc(array $bcc): self;
/**
* Adds a blind carbon copy recipient (BCC)
*
* @since 2025.05.01
*
* @param IAddress $address
*
* @return self
*/
public function addBcc(IAddress $address): self;
/**
* Sets the message date
*
* @since 2025.05.01
*
* @param DateTimeImmutable|null $date
*
* @return self
*/
public function setDate(?DateTimeImmutable $date): self;
/**
* Sets the plain text body
*
* @since 2025.05.01
*
* @param string|null $text
*
* @return self
*/
public function setBodyText(?string $text): self;
/**
* Sets the HTML body
*
* @since 2025.05.01
*
* @param string|null $html
*
* @return self
*/
public function setBodyHtml(?string $html): self;
/**
* Sets the attachments
*
* @since 2025.05.01
*
* @param array<int, IAttachment> $attachments
*
* @return self
*/
public function setAttachments(array $attachments): self;
/**
* Adds an attachment
*
* @since 2025.05.01
*
* @param IAttachment $attachment
*
* @return self
*/
public function addAttachment(IAttachment $attachment): self;
/**
* Sets custom headers
*
* @since 2025.05.01
*
* @param array<string, string> $headers Header name => value
*
* @return self
*/
public function setHeaders(array $headers): self;
/**
* Sets a specific header value
*
* @since 2025.05.01
*
* @param string $name Header name
* @param string $value Header value
*
* @return self
*/
public function setHeader(string $name, string $value): self;
}

383
shared/lib/Mail/Entity/Message.php
View File

@@ -1,383 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
use DateTimeImmutable;
/**
* Mail Message Implementation
*
* Concrete implementation of IMessageMutable for composing mail messages.
*
* @since 2025.05.01
*/
class Message implements IMessageMutable {
private ?string $id = null;
private string $subject = '';
private ?IAddress $from = null;
private ?IAddress $replyTo = null;
/** @var array<int, IAddress> */
private array $to = [];
/** @var array<int, IAddress> */
private array $cc = [];
/** @var array<int, IAddress> */
private array $bcc = [];
private ?DateTimeImmutable $date = null;
private ?string $bodyText = null;
private ?string $bodyHtml = null;
/** @var array<int, IAttachment> */
private array $attachments = [];
/** @var array<string, string> */
private array $headers = [];
/**
* Creates a message from array data
*
* @since 2025.05.01
*
* @param array $data
*
* @return self
*/
public static function fromArray(array $data): self {
$message = new self();
if (isset($data[self::JSON_PROPERTY_ID])) {
$message->setId($data[self::JSON_PROPERTY_ID]);
}
if (isset($data[self::JSON_PROPERTY_SUBJECT])) {
$message->setSubject($data[self::JSON_PROPERTY_SUBJECT]);
}
if (isset($data[self::JSON_PROPERTY_FROM])) {
$message->setFrom(Address::fromArray($data[self::JSON_PROPERTY_FROM]));
}
if (isset($data[self::JSON_PROPERTY_REPLY_TO])) {
$message->setReplyTo(Address::fromArray($data[self::JSON_PROPERTY_REPLY_TO]));
}
if (isset($data[self::JSON_PROPERTY_TO])) {
$message->setTo(array_map(fn($a) => Address::fromArray($a), $data[self::JSON_PROPERTY_TO]));
}
if (isset($data[self::JSON_PROPERTY_CC])) {
$message->setCc(array_map(fn($a) => Address::fromArray($a), $data[self::JSON_PROPERTY_CC]));
}
if (isset($data[self::JSON_PROPERTY_BCC])) {
$message->setBcc(array_map(fn($a) => Address::fromArray($a), $data[self::JSON_PROPERTY_BCC]));
}
if (isset($data[self::JSON_PROPERTY_DATE])) {
$message->setDate(new DateTimeImmutable($data[self::JSON_PROPERTY_DATE]));
}
if (isset($data[self::JSON_PROPERTY_BODY_TEXT])) {
$message->setBodyText($data[self::JSON_PROPERTY_BODY_TEXT]);
}
if (isset($data[self::JSON_PROPERTY_BODY_HTML])) {
$message->setBodyHtml($data[self::JSON_PROPERTY_BODY_HTML]);
}
if (isset($data[self::JSON_PROPERTY_ATTACHMENTS])) {
$message->setAttachments(array_map(fn($a) => Attachment::fromArray($a), $data[self::JSON_PROPERTY_ATTACHMENTS]));
}
if (isset($data[self::JSON_PROPERTY_HEADERS])) {
$message->setHeaders($data[self::JSON_PROPERTY_HEADERS]);
}
return $message;
}
/**
* @inheritDoc
*/
public function getId(): ?string {
return $this->id;
}
/**
* @inheritDoc
*/
public function setId(?string $id): self {
$this->id = $id;
return $this;
}
/**
* @inheritDoc
*/
public function getSubject(): string {
return $this->subject;
}
/**
* @inheritDoc
*/
public function setSubject(string $subject): self {
$this->subject = $subject;
return $this;
}
/**
* @inheritDoc
*/
public function getFrom(): ?IAddress {
return $this->from;
}
/**
* @inheritDoc
*/
public function setFrom(?IAddress $from): self {
$this->from = $from;
return $this;
}
/**
* @inheritDoc
*/
public function getReplyTo(): ?IAddress {
return $this->replyTo;
}
/**
* @inheritDoc
*/
public function setReplyTo(?IAddress $replyTo): self {
$this->replyTo = $replyTo;
return $this;
}
/**
* @inheritDoc
*/
public function getTo(): array {
return $this->to;
}
/**
* @inheritDoc
*/
public function setTo(array $to): self {
$this->to = $to;
return $this;
}
/**
* @inheritDoc
*/
public function addTo(IAddress $address): self {
$this->to[] = $address;
return $this;
}
/**
* @inheritDoc
*/
public function getCc(): array {
return $this->cc;
}
/**
* @inheritDoc
*/
public function setCc(array $cc): self {
$this->cc = $cc;
return $this;
}
/**
* @inheritDoc
*/
public function addCc(IAddress $address): self {
$this->cc[] = $address;
return $this;
}
/**
* @inheritDoc
*/
public function getBcc(): array {
return $this->bcc;
}
/**
* @inheritDoc
*/
public function setBcc(array $bcc): self {
$this->bcc = $bcc;
return $this;
}
/**
* @inheritDoc
*/
public function addBcc(IAddress $address): self {
$this->bcc[] = $address;
return $this;
}
/**
* @inheritDoc
*/
public function getDate(): ?DateTimeImmutable {
return $this->date;
}
/**
* @inheritDoc
*/
public function setDate(?DateTimeImmutable $date): self {
$this->date = $date;
return $this;
}
/**
* @inheritDoc
*/
public function getBodyText(): ?string {
return $this->bodyText;
}
/**
* @inheritDoc
*/
public function setBodyText(?string $text): self {
$this->bodyText = $text;
return $this;
}
/**
* @inheritDoc
*/
public function getBodyHtml(): ?string {
return $this->bodyHtml;
}
/**
* @inheritDoc
*/
public function setBodyHtml(?string $html): self {
$this->bodyHtml = $html;
return $this;
}
/**
* @inheritDoc
*/
public function getAttachments(): array {
return $this->attachments;
}
/**
* @inheritDoc
*/
public function setAttachments(array $attachments): self {
$this->attachments = $attachments;
return $this;
}
/**
* @inheritDoc
*/
public function addAttachment(IAttachment $attachment): self {
$this->attachments[] = $attachment;
return $this;
}
/**
* @inheritDoc
*/
public function getHeaders(): array {
return $this->headers;
}
/**
* @inheritDoc
*/
public function getHeader(string $name): ?string {
return $this->headers[$name] ?? null;
}
/**
* @inheritDoc
*/
public function setHeaders(array $headers): self {
$this->headers = $headers;
return $this;
}
/**
* @inheritDoc
*/
public function setHeader(string $name, string $value): self {
$this->headers[$name] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function hasRecipients(): bool {
return !empty($this->to) || !empty($this->cc) || !empty($this->bcc);
}
/**
* @inheritDoc
*/
public function hasBody(): bool {
return ($this->bodyText !== null && $this->bodyText !== '')
|| ($this->bodyHtml !== null && $this->bodyHtml !== '');
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
$data = [
self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
];
if ($this->id !== null) {
$data[self::JSON_PROPERTY_ID] = $this->id;
}
$data[self::JSON_PROPERTY_SUBJECT] = $this->subject;
if ($this->from !== null) {
$data[self::JSON_PROPERTY_FROM] = $this->from;
}
if ($this->replyTo !== null) {
$data[self::JSON_PROPERTY_REPLY_TO] = $this->replyTo;
}
if (!empty($this->to)) {
$data[self::JSON_PROPERTY_TO] = $this->to;
}
if (!empty($this->cc)) {
$data[self::JSON_PROPERTY_CC] = $this->cc;
}
if (!empty($this->bcc)) {
$data[self::JSON_PROPERTY_BCC] = $this->bcc;
}
if ($this->date !== null) {
$data[self::JSON_PROPERTY_DATE] = $this->date->format('c');
}
if ($this->bodyText !== null) {
$data[self::JSON_PROPERTY_BODY_TEXT] = $this->bodyText;
}
if ($this->bodyHtml !== null) {
$data[self::JSON_PROPERTY_BODY_HTML] = $this->bodyHtml;
}
if (!empty($this->attachments)) {
$data[self::JSON_PROPERTY_ATTACHMENTS] = $this->attachments;
}
if (!empty($this->headers)) {
$data[self::JSON_PROPERTY_HEADERS] = $this->headers;
}
return $data;
}
}

54
shared/lib/Mail/Entity/Address.php → shared/lib/Mail/Object/Address.php
View File

@@ -7,16 +7,14 @@ declare(strict_types=1);
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
namespace KTXF\Mail\Object;
/**
* Mail Address Implementation
*
* Concrete implementation of IAddress for email addresses.
* Address Implementation
*
* @since 2025.05.01
*/
class Address implements IAddress {
class Address implements AddressInterface {
/**
* @param string $address Email address
@@ -27,6 +25,16 @@ class Address implements IAddress {
private ?string $name = null,
) {}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
self::JSON_PROPERTY_ADDRESS => $this->address,
self::JSON_PROPERTY_LABEL => $this->name,
], fn($v) => $v !== null && $v !== '');
}
/**
* Creates an Address from a formatted string
*
@@ -65,7 +73,7 @@ class Address implements IAddress {
public static function fromArray(array $data): self {
return new self(
$data[self::JSON_PROPERTY_ADDRESS] ?? $data['address'] ?? '',
$data[self::JSON_PROPERTY_NAME] ?? $data['name'] ?? null,
$data[self::JSON_PROPERTY_LABEL] ?? $data['name'] ?? null,
);
}
@@ -77,15 +85,9 @@ class Address implements IAddress {
}
/**
* Sets the email address
*
* @since 2025.05.01
*
* @param string $address
*
* @return self
* @inheritDoc
*/
public function setAddress(string $address): self {
public function setAddress(string $address): static {
$this->address = $address;
return $this;
}
@@ -93,21 +95,15 @@ class Address implements IAddress {
/**
* @inheritDoc
*/
public function getName(): ?string {
public function getLabel(): ?string {
return $this->name;
}
/**
* Sets the display name
*
* @since 2025.05.01
*
* @param string|null $name
*
* @return self
* @inheritDoc
*/
public function setName(?string $name): self {
$this->name = $name;
public function setLabel(?string $label): static {
$this->name = $label;
return $this;
}
@@ -121,16 +117,6 @@ class Address implements IAddress {
return $this->address;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
self::JSON_PROPERTY_ADDRESS => $this->address,
self::JSON_PROPERTY_NAME => $this->name,
], fn($v) => $v !== null && $v !== '');
}
/**
* String representation
*/

30
shared/lib/Mail/Entity/IAddress.php → shared/lib/Mail/Object/AddressInterface.php
View File

@@ -7,39 +7,49 @@ declare(strict_types=1);
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
namespace KTXF\Mail\Object;
use JsonSerializable;
use KTXF\Json\JsonSerializable;
/**
* Mail Address Interface
* Address Interface
*
* Represents an email address with optional display name.
*
* @since 2025.05.01
*/
interface IAddress extends JsonSerializable {
interface AddressInterface extends JsonSerializable {
public const JSON_PROPERTY_ADDRESS = 'address';
public const JSON_PROPERTY_NAME = 'name';
public const JSON_PROPERTY_LABEL = 'label';
/**
* Gets the email address
*
* @since 2025.05.01
*
* @return string Email address (e.g., "user@example.com")
*/
public function getAddress(): string;
/**
* Sets the email address
*
* @since 2025.05.01
*/
public function setAddress(string $value): static;
/**
* Gets the display name
*
* @since 2025.05.01
*
* @return string|null Display name (e.g., "John Doe") or null
*/
public function getName(): ?string;
public function getLabel(): ?string;
/**
* Sets the display name
*
* @since 2025.05.01
*/
public function setLabel(?string $value): static;
/**
* Gets the formatted address string

39
shared/lib/Mail/Entity/Attachment.php → shared/lib/Mail/Object/Attachment.php
View File

@@ -7,16 +7,14 @@ declare(strict_types=1);
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
namespace KTXF\Mail\Object;
/**
* Mail Attachment Implementation
*
* Concrete implementation of IAttachment for mail attachments.
* Attachment Implementation
*
* @since 2025.05.01
*/
class Attachment implements IAttachment {
class Attachment implements AttachmentInterface {
/**
* @param string $name File name
@@ -41,6 +39,22 @@ class Attachment implements IAttachment {
}
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
self::JSON_PROPERTY_ID => $this->id,
self::JSON_PROPERTY_NAME => $this->name,
self::JSON_PROPERTY_MIME_TYPE => $this->mimeType,
self::JSON_PROPERTY_SIZE => $this->size,
self::JSON_PROPERTY_CONTENT_ID => $this->contentId,
self::JSON_PROPERTY_INLINE => $this->inline ?: null,
'contentBase64' => $this->getContentBase64(),
], fn($v) => $v !== null);
}
/**
* Creates an attachment from a file path
*
@@ -177,19 +191,4 @@ class Attachment implements IAttachment {
return base64_encode($this->content);
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
self::JSON_PROPERTY_ID => $this->id,
self::JSON_PROPERTY_NAME => $this->name,
self::JSON_PROPERTY_MIME_TYPE => $this->mimeType,
self::JSON_PROPERTY_SIZE => $this->size,
self::JSON_PROPERTY_CONTENT_ID => $this->contentId,
self::JSON_PROPERTY_INLINE => $this->inline ?: null,
'contentBase64' => $this->getContentBase64(),
], fn($v) => $v !== null);
}
}

8
shared/lib/Mail/Entity/IAttachment.php → shared/lib/Mail/Object/AttachmentInterface.php
View File

@@ -7,18 +7,18 @@ declare(strict_types=1);
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Entity;
namespace KTXF\Mail\Object;
use JsonSerializable;
use KTXF\Json\JsonSerializable;
/**
* Mail Attachment Interface
* Attachment Interface
*
* Represents a file attachment on a mail message.
*
* @since 2025.05.01
*/
interface IAttachment extends JsonSerializable {
interface AttachmentInterface extends JsonSerializable {
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_NAME = 'name';

122
shared/lib/Mail/Object/MessagePartBaseAbstract.php Normal file
View File

@@ -0,0 +1,122 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
/**
* Abstract Message Part Base Class
*
* Provides common implementation for message parts (read-only)
*
* @since 2025.05.01
*/
abstract class MessagePartBaseAbstract implements MessagePartInterface {
/**
* Internal data storage
*/
protected array $data = [];
/**
* Sub-parts storage
* @var array<int,MessagePartInterface>
*/
protected array $parts = [];
/**
* Constructor
*
* @param array &$data Reference to data array
*/
public function __construct(array &$data = null) {
if ($data === null) {
$data = [];
}
$this->data = &$data;
}
/**
* @inheritDoc
*/
public function getBlobId(): ?string {
return $this->data['blobId'] ?? null;
}
/**
* @inheritDoc
*/
public function getId(): ?string {
return $this->data['partId'] ?? null;
}
/**
* @inheritDoc
*/
public function getType(): ?string {
return $this->data['type'] ?? null;
}
/**
* @inheritDoc
*/
public function getDisposition(): ?string {
return $this->data['disposition'] ?? null;
}
/**
* @inheritDoc
*/
public function getName(): ?string {
return $this->data['name'] ?? null;
}
/**
* @inheritDoc
*/
public function getCharset(): ?string {
return $this->data['charset'] ?? null;
}
/**
* @inheritDoc
*/
public function getLanguage(): ?string {
return $this->data['language'] ?? null;
}
/**
* @inheritDoc
*/
public function getLocation(): ?string {
return $this->data['location'] ?? null;
}
/**
* @inheritDoc
*/
public function getParts(): array {
return $this->parts;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
$result = $this->data;
if (!empty($this->parts)) {
$result['subParts'] = [];
foreach ($this->parts as $part) {
$result['subParts'][] = $part->jsonSerialize();
}
}
return $result;
}
}

104
shared/lib/Mail/Object/MessagePartInterface.php Normal file
View File

@@ -0,0 +1,104 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use KTXF\Json\JsonSerializable;
/**
* Message Part Interface
*
* Represents a MIME part of a message (body, attachment, etc.)
*
* @since 2025.05.01
*/
interface MessagePartInterface extends JsonSerializable {
/**
* Gets the blob identifier
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBlobId(): ?string;
/**
* Gets the part identifier
*
* @since 2025.05.01
*
* @return string|null
*/
public function getId(): ?string;
/**
* Gets the MIME type
*
* @since 2025.05.01
*
* @return string|null
*/
public function getType(): ?string;
/**
* Gets the content disposition (inline, attachment)
*
* @since 2025.05.01
*
* @return string|null
*/
public function getDisposition(): ?string;
/**
* Gets the part name
*
* @since 2025.05.01
*
* @return string|null
*/
public function getName(): ?string;
/**
* Gets the character set
*
* @since 2025.05.01
*
* @return string|null
*/
public function getCharset(): ?string;
/**
* Gets the language
*
* @since 2025.05.01
*
* @return string|null
*/
public function getLanguage(): ?string;
/**
* Gets the location
*
* @since 2025.05.01
*
* @return string|null
*/
public function getLocation(): ?string;
/**
* Gets the sub-parts
*
* @since 2025.05.01
*
* @return array<int,MessagePartInterface>
*/
public function getParts(): array;
}

146
shared/lib/Mail/Object/MessagePartMutableAbstract.php Normal file
View File

@@ -0,0 +1,146 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
/**
* Abstract Message Part Mutable Class
*
* Provides common implementation for mutable message parts
*
* @since 2025.05.01
*/
abstract class MessagePartMutableAbstract extends MessagePartBaseAbstract {
/**
* Sets the blob identifier
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setBlobId(string $value): static {
$this->data['blobId'] = $value;
return $this;
}
/**
* Sets the part identifier
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setId(string $value): static {
$this->data['partId'] = $value;
return $this;
}
/**
* Sets the MIME type
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setType(string $value): static {
$this->data['type'] = $value;
return $this;
}
/**
* Sets the content disposition
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setDisposition(string $value): static {
$this->data['disposition'] = $value;
return $this;
}
/**
* Sets the part name
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setName(string $value): static {
$this->data['name'] = $value;
return $this;
}
/**
* Sets the character set
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setCharset(string $value): static {
$this->data['charset'] = $value;
return $this;
}
/**
* Sets the language
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setLanguage(string $value): static {
$this->data['language'] = $value;
return $this;
}
/**
* Sets the location
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setLocation(string $value): static {
$this->data['location'] = $value;
return $this;
}
/**
* Sets the sub-parts
*
* @since 2025.05.01
*
* @param MessagePartInterface ...$value
*
* @return static
*/
public function setParts(MessagePartInterface ...$value): static {
$this->parts = $value;
return $this;
}
}

400
shared/lib/Mail/Object/MessagePropertiesBaseAbstract.php Normal file
View File

@@ -0,0 +1,400 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
/**
* Abstract Message Properties Base Class
*
* Provides common implementation for message properties (read-only)
*
* @since 2025.05.01
*/
abstract class MessagePropertiesBaseAbstract extends NodePropertiesBaseAbstract implements MessagePropertiesBaseInterface {
public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function version(): int {
return $this->data['version'] ?? 1;
}
/**
* @inheritDoc
*/
public function getHeaders(): array {
return $this->data['headers'] ?? [];
}
/**
* @inheritDoc
*/
public function getHeader(string $name): string|array|null {
return $this->data['headers'][$name] ?? null;
}
/**
* @inheritDoc
*/
public function getUrid(): ?string {
return $this->data['urid'] ?? null;
}
/**
* @inheritDoc
*/
public function getCreated(): ?DateTimeImmutable {
return $this->data['created'] ?? null;
}
/**
* @inheritDoc
*/
public function getModified(): ?DateTimeImmutable {
return $this->data['modified'] ?? null;
}
/**
* @inheritDoc
*/
public function getDate(): ?DateTimeImmutable {
return $this->data['date'] ?? null;
}
/**
* @inheritDoc
*/
public function getReceived(): ?DateTimeImmutable {
return $this->data['received'] ?? null;
}
/**
* @inheritDoc
*/
public function getSize(): ?int {
return $this->data['size'] ?? null;
}
/**
* @inheritDoc
*/
public function getSender(): ?AddressInterface {
return $this->data['sender'] ?? null;
}
/**
* @inheritDoc
*/
public function getFrom(): ?AddressInterface {
return $this->data['from'] ?? null;
}
/**
* @inheritDoc
*/
public function getReplyTo(): array {
return $this->data['replyTo'] ?? [];
}
/**
* @inheritDoc
*/
public function getTo(): array {
return $this->data['to'] ?? [];
}
/**
* @inheritDoc
*/
public function getCc(): array {
return $this->data['cc'] ?? [];
}
/**
* @inheritDoc
*/
public function getBcc(): array {
return $this->data['bcc'] ?? [];
}
/**
* @inheritDoc
*/
public function getInReplyTo(): ?string {
return $this->data['inReplyTo'] ?? null;
}
/**
* @inheritDoc
*/
public function getReferences(): array {
return $this->data['references'] ?? [];
}
/**
* @inheritDoc
*/
public function getSubject(): string {
return $this->data['subject'] ?? '';
}
/**
* @inheritDoc
*/
public function getSnippet(): ?string {
return $this->data['snippet'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyText(): ?string {
return $this->data['bodyText'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyTextCharset(): ?string {
return $this->data['bodyTextCharset'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyTextSize(): ?int {
return $this->data['bodyTextSize'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyHtml(): ?string {
return $this->data['bodyHtml'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyHtmlCharset(): ?string {
return $this->data['bodyHtmlCharset'] ?? null;
}
/**
* @inheritDoc
*/
public function getBodyHtmlSize(): ?int {
return $this->data['bodyHtmlSize'] ?? null;
}
/**
* @inheritDoc
*/
public function getAttachments(): array {
return $this->data['attachments'] ?? [];
}
/**
* @inheritDoc
*/
public function getFlags(): array {
return $this->data['flags'] ?? [
'read' => false,
'starred' => false,
'important' => false,
'answered' => false,
'forwarded' => false,
'draft' => false,
'deleted' => false,
'flagged' => false,
];
}
/**
* @inheritDoc
*/
public function getFlag(string $name): bool {
return $this->data['flags'][$name] ?? false;
}
/**
* Gets message labels
*
* @since 2025.05.01
*
* @return array<int, string>
*/
public function getLabels(): array {
return $this->data['labels'] ?? [];
}
/**
* Gets message tags
*
* @since 2025.05.01
*
* @return array<int, string>
*/
public function getTags(): array {
return $this->data['tags'] ?? [];
}
/**
* Gets message priority
*
* @since 2025.05.01
*
* @return string
*/
public function getPriority(): string {
return $this->data['priority'] ?? 'normal';
}
/**
* Gets message sensitivity
*
* @since 2025.05.01
*
* @return string
*/
public function getSensitivity(): string {
return $this->data['sensitivity'] ?? 'normal';
}
/**
* Gets encryption information
*
* @since 2025.05.01
*
* @return array{method: string|null, signed: bool, encrypted: bool}
*/
public function getEncryption(): array {
return $this->data['encryption'] ?? [
'method' => null,
'signed' => false,
'encrypted' => false,
];
}
/**
* Checks if delivery receipt is requested
*
* @since 2025.05.01
*
* @return bool
*/
public function isDeliveryReceipt(): bool {
return $this->data['deliveryReceipt'] ?? false;
}
/**
* Checks if read receipt is requested
*
* @since 2025.05.01
*
* @return bool
*/
public function isReadReceipt(): bool {
return $this->data['readReceipt'] ?? false;
}
/**
* @inheritDoc
*/
public function hasRecipients(): bool {
return !empty($this->data['to']) || !empty($this->data['cc']) || !empty($this->data['bcc']);
}
/**
* @inheritDoc
*/
public function hasBody(): bool {
return ($this->data['bodyText'] !== null && $this->data['bodyText'] !== '')
|| ($this->data['bodyHtml'] !== null && $this->data['bodyHtml'] !== '');
}
/**
* @inheritDoc
*/
public function getBody(): ?MessagePartInterface {
return $this->data['body'] ?? null;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
$data = [
self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
self::JSON_PROPERTY_VERSION => $this->data['version'] ?? 1,
];
if (!empty($this->data['headers'])) {
$data[self::JSON_PROPERTY_HEADERS] = $this->data['headers'];
}
if (isset($this->data['urid']) && $this->data['urid'] !== null) {
$data[self::JSON_PROPERTY_URID] = $this->data['urid'];
}
if (isset($this->data['date']) && $this->data['date'] !== null) {
$data[self::JSON_PROPERTY_DATE] = $this->data['date'] instanceof DateTimeImmutable
? $this->data['date']->format('c')
: $this->data['date'];
}
if (isset($this->data['received']) && $this->data['received'] !== null) {
$data[self::JSON_PROPERTY_RECEIVED] = $this->data['received'] instanceof DateTimeImmutable
? $this->data['received']->format('c')
: $this->data['received'];
}
if (isset($this->data['size']) && $this->data['size'] !== null) {
$data[self::JSON_PROPERTY_SIZE] = $this->data['size'];
}
if (isset($this->data['sender']) && $this->data['sender'] !== null) {
$data[self::JSON_PROPERTY_SENDER] = $this->data['sender'];
}
if (isset($this->data['from']) && $this->data['from'] !== null) {
$data[self::JSON_PROPERTY_FROM] = $this->data['from'];
}
if (!empty($this->data['replyTo'])) {
$data[self::JSON_PROPERTY_REPLY_TO] = $this->data['replyTo'];
}
if (!empty($this->data['to'])) {
$data[self::JSON_PROPERTY_TO] = $this->data['to'];
}
if (!empty($this->data['cc'])) {
$data[self::JSON_PROPERTY_CC] = $this->data['cc'];
}
if (!empty($this->data['bcc'])) {
$data[self::JSON_PROPERTY_BCC] = $this->data['bcc'];
}
if (isset($this->data['inReplyTo']) && $this->data['inReplyTo'] !== null) {
$data[self::JSON_PROPERTY_IN_REPLY_TO] = $this->data['inReplyTo'];
}
if (!empty($this->data['references'])) {
$data[self::JSON_PROPERTY_REFERENCES] = $this->data['references'];
}
if (isset($this->data['snippet']) && $this->data['snippet'] !== null) {
$data[self::JSON_PROPERTY_SNIPPET] = $this->data['snippet'];
}
if (!empty($this->data['attachments'])) {
$data[self::JSON_PROPERTY_ATTACHMENTS] = $this->data['attachments'];
}
$data[self::JSON_PROPERTY_SUBJECT] = $this->data['subject'] ?? null;
$data[self::JSON_PROPERTY_BODY] = $this->data['body'] ?? null;
return $data;
}
}

252
shared/lib/Mail/Object/MessagePropertiesBaseInterface.php Normal file
View File

@@ -0,0 +1,252 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
/**
* Message Properties Base Interface
*
* @since 2025.05.01
*/
interface MessagePropertiesBaseInterface extends NodePropertiesBaseInterface {
public const JSON_TYPE = 'mail.message';
public const JSON_PROPERTY_HEADERS = 'headers';
public const JSON_PROPERTY_URID = 'urid';
public const JSON_PROPERTY_DATE = 'date';
public const JSON_PROPERTY_RECEIVED = 'received';
public const JSON_PROPERTY_SIZE = 'size';
public const JSON_PROPERTY_SENDER = 'sender';
public const JSON_PROPERTY_FROM = 'from';
public const JSON_PROPERTY_REPLY_TO = 'replyTo';
public const JSON_PROPERTY_TO = 'to';
public const JSON_PROPERTY_CC = 'cc';
public const JSON_PROPERTY_BCC = 'bcc';
public const JSON_PROPERTY_IN_REPLY_TO = 'inReplyTo';
public const JSON_PROPERTY_REFERENCES = 'references';
public const JSON_PROPERTY_SUBJECT = 'subject';
public const JSON_PROPERTY_SNIPPET = 'snippet';
public const JSON_PROPERTY_BODY = 'body';
public const JSON_PROPERTY_ATTACHMENTS = 'attachments';
public const JSON_PROPERTY_TAGS = 'tags';
/**
* Gets custom headers
*
* @since 2025.05.01
*
* @return array<string,string> Header name => value
*/
public function getHeaders(): array;
/**
* Gets a specific header value
*
* @since 2025.05.01
*
* @param string $name Header name
*
* @return string|array<int,string>|null Header value(s) or null if not set
*/
public function getHeader(string $name): string|array|null;
/**
* Gets the universal resource identifier (URN)
*
* @since 2025.05.01
*
* @return string|null
*/
public function getUrid(): ?string;
/**
* Gets the message date
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function getDate(): ?DateTimeImmutable;
/**
* Gets the received date
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function getReceived(): ?DateTimeImmutable;
/**
* Gets the message size in bytes
*
* @since 2025.05.01
*
* @return int|null
*/
public function getSize(): ?int;
/**
* Gets the sender address (actual sender, may differ from From)
*
* @since 2025.05.01
*
* @return AddressInterface|null
*/
public function getSender(): ?AddressInterface;
/**
* Gets the sender address
*
* @since 2025.05.01
*
* @return AddressInterface|null
*/
public function getFrom(): ?AddressInterface;
/**
* Gets the reply-to addresses
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getReplyTo(): array;
/**
* Gets the primary recipients (To)
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getTo(): array;
/**
* Gets the carbon copy recipients (CC)
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getCc(): array;
/**
* Gets the blind carbon copy recipients (BCC)
*
* @since 2025.05.01
*
* @return array<int,AddressInterface>
*/
public function getBcc(): array;
/**
* Gets the message ID this is replying to
*
* @since 2025.05.01
*
* @return string|null
*/
public function getInReplyTo(): ?string;
/**
* Gets the references (message IDs in thread)
*
* @since 2025.05.01
*
* @return array<int,string>
*/
public function getReferences(): array;
/**
* Gets the message subject
*
* @since 2025.05.01
*
* @return string
*/
public function getSubject(): string;
/**
* Gets the message snippet/preview
*
* @since 2025.05.01
*
* @return string|null
*/
public function getSnippet(): ?string;
/**
* Checks if the message has any body content
*
* @since 2025.05.01
*
* @return bool True if text or HTML body is set
*/
public function hasBody(): bool;
/**
* Gets the message body structure
*
* @since 2025.05.01
*
* @return MessagePartInterface|null The body structure or null if no body
*/
public function getBody(): ?MessagePartInterface;
/**
* Gets the plain text body content
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBodyText(): ?string;
/**
* Gets the HTML body content
*
* @since 2025.05.01
*
* @return string|null
*/
public function getBodyHtml(): ?string;
/**
* Gets the attachments
*
* @since 2025.05.01
*
* @return array<int,AttachmentInterface>
*/
public function getAttachments(): array;
/**
* Gets message flags
*
* @since 2025.05.01
*
* @return array{read:bool,starred:bool,important:bool,answered:bool,forwarded:bool,draft:bool,deleted:bool,flagged:bool}
*/
public function getFlags(): array;
/**
* Gets a specific flag value
*
* @since 2025.05.01
*
* @param string $name Flag name (read, starred, important, answered, forwarded, draft, deleted, flagged)
*
* @return bool
*/
public function getFlag(string $name): bool;
}

455
shared/lib/Mail/Object/MessagePropertiesMutableAbstract.php Normal file
View File

@@ -0,0 +1,455 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
/**
* Abstract Message Properties Mutable Class
*
* Provides common implementation for mutable message properties
*
* @since 2025.05.01
*/
abstract class MessagePropertiesMutableAbstract extends MessagePropertiesBaseAbstract implements MessagePropertiesMutableInterface {
public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
/**
* @inheritDoc
*/
public function setHeaders(array $value): static {
$this->data['headers'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setHeader(string $name, string|array $value): static {
$this->data['headers'][$name] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setUrid(?string $value): static {
$this->data['urid'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setCreated(DateTimeImmutable $value): static {
$this->data['created'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setModified(DateTimeImmutable $value): static {
$this->data['modified'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setDate(DateTimeImmutable $value): static {
$this->data['date'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setReceived(?DateTimeImmutable $value): static {
$this->data['received'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSize(?int $value): static {
$this->data['size'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSender(?AddressInterface $value): static {
$this->data['sender'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setFrom(AddressInterface $value): static {
$this->data['from'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setReplyTo(AddressInterface ...$value): static {
$this->data['replyTo'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setTo(AddressInterface ...$value): static {
$this->data['to'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setCc(AddressInterface ...$value): static {
$this->data['cc'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setBcc(AddressInterface ...$value): static {
$this->data['bcc'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setInReplyTo(?string $value): static {
$this->data['inReplyTo'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setReferences(string ...$value): static {
$this->data['references'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSubject(string $value): static {
$this->data['subject'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setSnippet(?string $value): static {
$this->data['snippet'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setBodyText(?string $value): static {
$this->data['bodyText'] = $value;
return $this;
}
/**
* Sets the plain text body charset
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setBodyTextCharset(string $value): static {
$this->data['bodyTextCharset'] = $value;
return $this;
}
/**
* Sets the plain text body size
*
* @since 2025.05.01
*
* @param int $value
*
* @return static
*/
public function setBodyTextSize(int $value): static {
$this->data['bodyTextSize'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setBodyHtml(?string $value): static {
$this->data['bodyHtml'] = $value;
return $this;
}
/**
* Sets the HTML body charset
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setBodyHtmlCharset(string $value): static {
$this->data['bodyHtmlCharset'] = $value;
return $this;
}
/**
* Sets the HTML body size
*
* @since 2025.05.01
*
* @param int $value
*
* @return static
*/
public function setBodyHtmlSize(int $value): static {
$this->data['bodyHtmlSize'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function setAttachments(AttachmentInterface ...$value): static {
$this->data['attachments'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function addAttachment(AttachmentInterface $value): static {
$this->data['attachments'][] = $value;
return $this;
}
/**
* Sets message flags
*
* @since 2025.05.01
*
* @param array $value
*
* @return static
*/
public function setFlags(array $value): static {
if (!isset($this->data['flags'])) {
$this->data['flags'] = [
'read' => false,
'starred' => false,
'important' => false,
'answered' => false,
'forwarded' => false,
'draft' => false,
'deleted' => false,
'flagged' => false,
];
}
$this->data['flags'] = array_merge($this->data['flags'], $value);
return $this;
}
/**
* @inheritDoc
*/
public function setFlag(string $name, bool $value): static {
if (!isset($this->data['flags'])) {
$this->data['flags'] = [
'read' => false,
'starred' => false,
'important' => false,
'answered' => false,
'forwarded' => false,
'draft' => false,
'deleted' => false,
'flagged' => false,
];
}
if (array_key_exists($name, $this->data['flags'])) {
$this->data['flags'][$name] = $value;
}
return $this;
}
/**
* Sets message labels
*
* @since 2025.05.01
*
* @param string ...$value
*
* @return static
*/
public function setLabels(string ...$value): static {
$this->data['labels'] = $value;
return $this;
}
/**
* Adds a message label
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function addLabel(string $value): static {
$this->data['labels'][] = $value;
return $this;
}
/**
* Sets message tags
*
* @since 2025.05.01
*
* @param string ...$value
*
* @return static
*/
public function setTags(string ...$value): static {
$this->data['tags'] = $value;
return $this;
}
/**
* Adds a message tag
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function addTag(string $value): static {
$this->data['tags'][] = $value;
return $this;
}
/**
* Sets message priority
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setPriority(string $value): static {
$this->data['priority'] = $value;
return $this;
}
/**
* Sets message sensitivity
*
* @since 2025.05.01
*
* @param string $value
*
* @return static
*/
public function setSensitivity(string $value): static {
$this->data['sensitivity'] = $value;
return $this;
}
/**
* Sets encryption information
*
* @since 2025.05.01
*
* @param array $value
*
* @return static
*/
public function setEncryption(array $value): static {
if (!isset($this->data['encryption'])) {
$this->data['encryption'] = [
'method' => null,
'signed' => false,
'encrypted' => false,
];
}
$this->data['encryption'] = array_merge($this->data['encryption'], $value);
return $this;
}
/**
* Sets delivery receipt flag
*
* @since 2025.05.01
*
* @param bool $value
*
* @return static
*/
public function setDeliveryReceipt(bool $value): static {
$this->data['deliveryReceipt'] = $value;
return $this;
}
/**
* Sets read receipt flag
*
* @since 2025.05.01
*
* @param bool $value
*
* @return static
*/
public function setReadReceipt(bool $value): static {
$this->data['readReceipt'] = $value;
return $this;
}
/**
* @inheritDoc
*/
public function jsonDeserialize(array|string $data): static {
if (is_string($data)) {
$data = json_decode($data, true);
}
// Merge deserialized data into internal storage
foreach ($data as $key => $value) {
if (!in_array($key, ['collection', 'identifier', 'signature', 'created', 'modified'])) {
$this->data[$key] = $value;
}
}
return $this;
}
}

255
shared/lib/Mail/Object/MessagePropertiesMutableInterface.php Normal file
View File

@@ -0,0 +1,255 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Object;
use DateTimeImmutable;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
/**
* Message Properties Mutable Interface
*
* @since 2025.05.01
*/
interface MessagePropertiesMutableInterface extends MessagePropertiesBaseInterface, NodePropertiesMutableInterface {
public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
/**
* Sets custom headers
*
* @since 2025.05.01
*
* @param array<string,string|array<int,string>> $value Header name => value
*
* @return self
*/
public function setHeaders(array $value): static;
/**
* Sets a specific header value
*
* @since 2025.05.01
*
* @param string $name Header name
* @param string|array<int,string> $value Header value(s)
*
* @return self
*/
public function setHeader(string $name, string|array $value): static;
/**
* Sets the universal resource identifier (URN)
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setUrid(?string $value): static;
/**
* Sets the message date
*
* @since 2025.05.01
*
* @param DateTimeImmutable $value
*
* @return self
*/
public function setDate(DateTimeImmutable $value): static;
/**
* Sets the received date
*
* @since 2025.05.01
*
* @param DateTimeImmutable|null $value
*
* @return self
*/
public function setReceived(?DateTimeImmutable $value): static;
/**
* Sets the message size in bytes
*
* @since 2025.05.01
*
* @param int|null $value
*
* @return self
*/
public function setSize(?int $value): static;
/**
* Sets the sender address (actual sender, may differ from From)
*
* @since 2025.05.01
*
* @param AddressInterface|null $value
*
* @return self
*/
public function setSender(?AddressInterface $value): static;
/**
* Sets the sender address
*
* @since 2025.05.01
*
* @param AddressInterface $value
*
* @return self
*/
public function setFrom(AddressInterface $value): static;
/**
* Sets the reply-to addresses
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setReplyTo(AddressInterface ...$value): static;
/**
* Sets the primary recipients (To)
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setTo(AddressInterface ...$value): static;
/**
* Sets the carbon copy recipients (CC)
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setCc(AddressInterface ...$value): static;
/**
* Sets the blind carbon copy recipients (BCC)
*
* @since 2025.05.01
*
* @param AddressInterface ...$value
*
* @return self
*/
public function setBcc(AddressInterface ...$value): static;
/**
* Sets the message ID this is replying to
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setInReplyTo(?string $value): static;
/**
* Sets the references (message IDs in thread)
*
* @since 2025.05.01
*
* @param string ...$value
*
* @return self
*/
public function setReferences(string ...$value): static;
/**
* Sets the message subject
*
* @since 2025.05.01
*
* @param string $value
*
* @return self
*/
public function setSubject(string $value): static;
/**
* Sets the message snippet/preview
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setSnippet(?string $value): static;
/**
* Sets the plain text body content
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setBodyText(?string $value): static;
/**
* Sets the HTML body content
*
* @since 2025.05.01
*
* @param string|null $value
*
* @return self
*/
public function setBodyHtml(?string $value): static;
/**
* Sets the attachments
*
* @since 2025.05.01
*
* @param AttachmentInterface ...$value
*
* @return self
*/
public function setAttachments(AttachmentInterface ...$value): static;
/**
* Adds an attachment
*
* @since 2025.05.01
*
* @param AttachmentInterface $value
*
* @return self
*/
public function addAttachment(AttachmentInterface $value): static;
/**
* Sets message tags
*
* @since 2025.05.01
*
* @param array{read: bool, starred: bool, important: bool, answered: bool, forwarded: bool, draft: bool, deleted: bool, flagged: bool} $value
*
* @return self
*/
public function setFlag(string $label, bool $value): static;
}

6
shared/lib/Mail/Provider/ProviderBaseInterface.php
View File

@@ -31,11 +31,11 @@ interface ProviderBaseInterface extends ResourceProviderBaseInterface{
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for context
* @param string $userId User identifier
* @param string $address Email address to find service for
*
* @return IServiceBase|null Service handling the address, or null
* @return ServiceBaseInterface|null Service handling the address, or null
*/
public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?ServiceBaseInterface;
public function serviceFindByAddress(string $tenantId, string $userId, string $address): ?ServiceBaseInterface;
}

43
shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php
View File

@@ -9,6 +9,8 @@ declare(strict_types=1);
namespace KTXF\Mail\Provider;
use KTXF\Resource\Provider\ResourceServiceLocationInterface;
/**
* Mail Provider Autodiscovery Interface
*
@@ -27,39 +29,24 @@ namespace KTXF\Mail\Provider;
interface ProviderServiceDiscoverInterface extends ProviderBaseInterface {
/**
* Discover service configuration
*
* Attempts to discover service configuration using provider-specific methods.
* Each provider may use different discovery mechanisms:
* - IMAP/SMTP: config database, DNS SRV, well-known URIs, common patterns
* - JMAP: Well-known JMAP session discovery
* - Provider-specific: Known configurations for popular providers
*
* @since 2025.05.01
*
* @param string $identity Identity to discover configuration for
* @param array $options Provider-specific options (e.g., preferred protocols, timeout)
* @param string $tenantId Tenant identifier
* @param string $userId User identifier
* @param string $identity Identity to discover configuration for (e.g., email address)
* @param string|null $location Optional hostname to test directly (bypasses DNS lookup)
* @param string|null $secret Optional password/token to validate discovered service
*
* @return array Discovery results in the format:
* [
* 'domain' => 'example.com',
* 'provider' => 'gmail|outlook|generic|etc', // Optional detected provider
* 'results' => [
* [
* 'protocol' => 'imap|smtp|jmap|etc',
* 'host' => 'imap.example.com',
* 'port' => 993,
* 'security' => 'ssl|tls|starttls|none',
* 'authentication' => ['plain', 'login', 'oauth2'], // Supported auth methods
* 'confidence' => 'high|medium|low',
* 'source' => 'mozilla|srv|wellknown|common|verified', // Discovery method used
* ],
* // ... more protocol results
* ]
* ]
*
* Returns empty results array if no configuration could be discovered.
* @return ResourceServiceLocationInterface|null Discovered location or null if not found
*/
public function serviceDiscover(string $identity, array $options = []): array;
public function serviceDiscover(
string $tenantId,
string $userId,
string $identity,
?string $location = null,
?string $secret = null
): ResourceServiceLocationInterface|null;
}

183
shared/lib/Mail/Selector/ServiceSelector.php
View File

@@ -1,183 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Selector;
use JsonSerializable;
use KTXF\Mail\Service\ServiceScope;
/**
* Mail Service Selector
*
* Filter criteria for selecting mail services from providers.
*
* @since 2025.05.01
*/
class ServiceSelector implements JsonSerializable {
private ?ServiceScope $scope = null;
private ?string $owner = null;
private ?string $address = null;
private ?array $capabilities = null;
private ?bool $enabled = null;
/**
* Filter by service scope
*
* @since 2025.05.01
*
* @param ServiceScope|null $scope
*
* @return self
*/
public function setScope(?ServiceScope $scope): self {
$this->scope = $scope;
return $this;
}
/**
* Gets the scope filter
*
* @since 2025.05.01
*
* @return ServiceScope|null
*/
public function getScope(): ?ServiceScope {
return $this->scope;
}
/**
* Filter by owner user ID
*
* @since 2025.05.01
*
* @param string|null $owner
*
* @return self
*/
public function setOwner(?string $owner): self {
$this->owner = $owner;
return $this;
}
/**
* Gets the owner filter
*
* @since 2025.05.01
*
* @return string|null
*/
public function getOwner(): ?string {
return $this->owner;
}
/**
* Filter by email address (matches primary or secondary)
*
* @since 2025.05.01
*
* @param string|null $address
*
* @return self
*/
public function setAddress(?string $address): self {
$this->address = $address;
return $this;
}
/**
* Gets the address filter
*
* @since 2025.05.01
*
* @return string|null
*/
public function getAddress(): ?string {
return $this->address;
}
/**
* Filter by required capabilities
*
* @since 2025.05.01
*
* @param array<string>|null $capabilities
*
* @return self
*/
public function setCapabilities(?array $capabilities): self {
$this->capabilities = $capabilities;
return $this;
}
/**
* Gets the capabilities filter
*
* @since 2025.05.01
*
* @return array<string>|null
*/
public function getCapabilities(): ?array {
return $this->capabilities;
}
/**
* Filter by enabled status
*
* @since 2025.05.01
*
* @param bool|null $enabled
*
* @return self
*/
public function setEnabled(?bool $enabled): self {
$this->enabled = $enabled;
return $this;
}
/**
* Gets the enabled filter
*
* @since 2025.05.01
*
* @return bool|null
*/
public function getEnabled(): ?bool {
return $this->enabled;
}
/**
* Checks if any filter criteria are set
*
* @since 2025.05.01
*
* @return bool
*/
public function hasFilters(): bool {
return $this->scope !== null
|| $this->owner !== null
|| $this->address !== null
|| $this->capabilities !== null
|| $this->enabled !== null;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
'scope' => $this->scope?->value,
'owner' => $this->owner,
'address' => $this->address,
'capabilities' => $this->capabilities,
'enabled' => $this->enabled,
], fn($v) => $v !== null);
}
}

81
shared/lib/Mail/Service/ServiceBaseInterface.php
View File

@@ -9,9 +9,9 @@ declare(strict_types=1);
namespace KTXF\Mail\Service;
use KTXF\Mail\Collection\ICollectionBase;
use KTXF\Mail\Entity\IAddress;
use KTXF\Mail\Entity\IMessageBase;
use KTXF\Mail\Collection\CollectionBaseInterface;
use KTXF\Mail\Object\AddressInterface;
use KTXF\Resource\Delta\Delta;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Provider\ResourceServiceBaseInterface;
use KTXF\Resource\Range\IRange;
@@ -34,7 +34,13 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';
// Message capabilities
// Collection Filter
public const CAPABILITY_COLLECTION_FILTER_LABEL = 'label';
public const CAPABILITY_COLLECTION_FILTER_ROLE = 'role';
// Collection Sort
public const CAPABILITY_COLLECTION_SORT_LABEL = 'label';
public const CAPABILITY_COLLECTION_SORT_RANK = 'rank';
// Entity capabilities
public const CAPABILITY_ENTITY_LIST = 'EntityList';
public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
@@ -43,19 +49,24 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';
// Filter capabilities
public const CAPABILITY_FILTER_ID = 'id';
public const CAPABILITY_FILTER_SUBJECT = 'subject';
public const CAPABILITY_FILTER_FROM = 'from';
public const CAPABILITY_FILTER_TO = 'to';
public const CAPABILITY_FILTER_DATE = 'date';
public const CAPABILITY_FILTER_FLAG = 'flag';
public const CAPABILITY_FILTER_SIZE = 'size';
public const CAPABILITY_FILTER_BODY = 'body';
public const CAPABILITY_ENTITY_FILTER_ALL = '*';
public const CAPABILITY_ENTITY_FILTER_FROM = 'from';
public const CAPABILITY_ENTITY_FILTER_TO = 'to';
public const CAPABILITY_ENTITY_FILTER_CC = 'cc';
public const CAPABILITY_ENTITY_FILTER_BCC = 'bcc';
public const CAPABILITY_ENTITY_FILTER_SUBJECT = 'subject';
public const CAPABILITY_ENTITY_FILTER_BODY = 'body';
public const CAPABILITY_ENTITY_FILTER_DATE_BEFORE = 'before';
public const CAPABILITY_ENTITY_FILTER_DATE_AFTER = 'after';
public const CAPABILITY_ENTITY_FILTER_SIZE_MIN = 'min';
public const CAPABILITY_ENTITY_FILTER_SIZE_MAX = 'max';
// Sort capabilities
public const CAPABILITY_SORT_DATE = 'date';
public const CAPABILITY_SORT_SUBJECT = 'subject';
public const CAPABILITY_SORT_FROM = 'from';
public const CAPABILITY_SORT_SIZE = 'size';
public const CAPABILITY_ENTITY_SORT_FROM = 'from';
public const CAPABILITY_ENTITY_SORT_TO = 'to';
public const CAPABILITY_ENTITY_SORT_SUBJECT = 'subject';
public const CAPABILITY_ENTITY_SORT_DATE_RECEIVED = 'received';
public const CAPABILITY_ENTITY_SORT_DATE_SENT = 'sent';
public const CAPABILITY_ENTITY_SORT_SIZE = 'size';
public const JSON_TYPE = 'mail.service';
public const JSON_PROPERTY_PRIMARY_ADDRESS = 'primaryAddress';
@@ -66,16 +77,16 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @since 2025.05.01
*
* @return IAddress
* @return AddressInterface
*/
public function getPrimaryAddress(): IAddress;
public function getPrimaryAddress(): AddressInterface;
/**
* Gets the secondary mailing addresses (aliases) for this service
*
* @since 2025.05.01
*
* @return array<int, IAddress>
* @return array<int,AddressInterface>
*/
public function getSecondaryAddresses(): array;
@@ -88,7 +99,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @return bool True if address matches primary or any secondary address
*/
public function handlesAddress(string $address): bool;
public function hasAddress(string $address): bool;
/**
* Lists all collections in this service
@@ -98,9 +109,9 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
* @param IFilter|null $filter Optional filter criteria
* @param ISort|null $sort Optional sort order
*
* @return array<string|int,ICollectionBase> Collections indexed by ID
* @return array<string|int,CollectionBaseInterface> Collections indexed by ID
*/
public function collectionList(?IFilter $filter = null, ?ISort $sort = null): array;
public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array;
/**
* Creates a filter builder for collections
@@ -129,7 +140,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @return array<string|int,bool> Map of ID => exists
*/
public function collectionExtant(string|int ...$identifiers): array;
public function collectionExtant(string|int $location, string|int ...$identifiers): array;
/**
* Fetches a single collection
@@ -138,9 +149,9 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @param string|int $identifier Collection ID
*
* @return ICollectionBase|null Collection or null if not found
* @return CollectionBaseInterface|null Collection or null if not found
*/
public function collectionFetch(string|int $identifier): ?ICollectionBase;
public function collectionFetch(string|int $identifier): ?CollectionBaseInterface;
/**
* Lists messages in a collection
@@ -153,9 +164,9 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
* @param IRange|null $range Optional pagination
* @param array|null $properties Optional message properties to fetch
*
* @return array<string|int,IMessageBase> Messages indexed by ID
* @return array<string|int,EntityBaseInterface> Messages indexed by ID
*/
public function messageList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
/**
* Creates a filter builder for messages
@@ -164,7 +175,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @return IFilter
*/
public function messageListFilter(): IFilter;
public function entityListFilter(): IFilter;
/**
* Creates a sort builder for messages
@@ -173,7 +184,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @return ISort
*/
public function messageListSort(): ISort;
public function entityListSort(): ISort;
/**
* Creates a range builder for messages
@@ -184,7 +195,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @return IRange
*/
public function messageListRange(RangeType $type): IRange;
public function entityListRange(RangeType $type): IRange;
/**
* Gets incremental changes since last sync
@@ -197,7 +208,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array]
*/
public function messageDelta(string|int $collection, string $signature, string $detail = 'ids'): array;
public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta;
/**
* Checks if messages exist
@@ -209,18 +220,18 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
*
* @return array<string|int,bool> Map of ID => exists
*/
public function messageExtant(string|int $collection, string|int ...$identifiers): array;
public function entityExtant(string|int $collection, string|int ...$identifiers): array;
/**
* Fetches one or more messages
* Fetches one or more entities
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param string|int ...$identifiers Message IDs to fetch
*
* @return array<string|int,IMessageBase> Messages indexed by ID
* @return array<string|int,EntityBaseInterface> Messages indexed by ID
*/
public function messageFetch(string|int $collection, string|int ...$identifiers): array;
public function entityFetch(string|int $collection, string|int ...$identifiers): array;
}

29
shared/lib/Mail/Service/ServiceCollectionMutableInterface.php
View File

@@ -9,8 +9,8 @@ declare(strict_types=1);
namespace KTXF\Mail\Service;
use KTXF\Mail\Collection\ICollectionBase;
use KTXF\Mail\Collection\ICollectionMutable;
use KTXF\Mail\Collection\CollectionBaseInterface;
use KTXF\Mail\Collection\CollectionMutableInterface;
/**
* Mail Service Collection Mutable Interface
@@ -32,9 +32,9 @@ interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
*
* @since 2025.05.01
*
* @return ICollectionMutable Fresh collection object
* @return CollectionMutableInterface Fresh collection object
*/
public function collectionFresh(): ICollectionMutable;
public function collectionFresh(): CollectionMutableInterface;
/**
* Creates a new collection
@@ -42,12 +42,12 @@ interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
* @since 2025.05.01
*
* @param string|int|null $location Parent collection ID (null for root)
* @param ICollectionMutable $collection Collection to create
* @param CollectionMutableInterface $collection Collection to create
* @param array $options Protocol-specific options
*
* @return ICollectionBase Created collection with assigned ID
* @return CollectionBaseInterface Created collection with assigned ID
*/
public function collectionCreate(string|int|null $location, ICollectionMutable $collection, array $options = []): ICollectionBase;
public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface;
/**
* Modifies an existing collection
@@ -55,11 +55,11 @@ interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
* @param ICollectionMutable $collection Updated collection data
* @param CollectionMutableInterface $collection Updated collection data
*
* @return ICollectionBase Modified collection
* @return CollectionBaseInterface Modified collection
*/
public function collectionModify(string|int $identifier, ICollectionMutable $collection): ICollectionBase;
public function collectionModify(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface;
/**
* Destroys a collection
@@ -67,11 +67,12 @@ interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
* @since 2025.05.01
*
* @param string|int $identifier Collection ID
* @param bool $recursive Destroy child collections too
* @param bool $force Force destruction even if not empty
* @param bool $recursive Recursively destroy contents
*
* @return bool True if destroyed
*/
public function collectionDestroy(string|int $identifier, bool $recursive = false): bool;
public function collectionDestroy(string|int $identifier, bool $force = false, bool $recursive = false): bool;
/**
* Moves a collection to a new parent
@@ -81,8 +82,8 @@ interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
* @param string|int $identifier Collection ID
* @param string|int|null $targetLocation New parent ID (null for root)
*
* @return ICollectionBase Moved collection
* @return CollectionBaseInterface Moved collection
*/
public function collectionMove(string|int $identifier, string|int|null $targetLocation): ICollectionBase;
public function collectionMove(string|int $identifier, string|int|null $targetLocation): CollectionBaseInterface;
}

26
shared/lib/Mail/Service/ServiceConfigurableInterface.php Normal file
View File

@@ -0,0 +1,26 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use KTXF\Resource\Provider\ResourceServiceConfigureInterface;
/**
* Mail Service Mutable Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
*
* @since 2025.05.01
*/
interface ServiceConfigurableInterface extends ServiceMutableInterface, ResourceServiceConfigureInterface {
public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE;
}

103
shared/lib/Mail/Service/ServiceEntityMutableInterface.php Normal file
View File

@@ -0,0 +1,103 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use KTXF\Mail\Entity\EntityBaseInterface;
use KTXF\Mail\Entity\EntityMutableInterface;
/**
* Mail Service Entity Mutable Interface
*
* Optional interface for services that support entity CRUD operations.
* Provides entity creation, modification, deletion, copying, moving, and flag management.
*
* @since 2025.05.01
*/
interface ServiceEntityMutableInterface extends ServiceBaseInterface {
public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
public const CAPABILITY_ENTITY_DESTROY = 'EntityDestroy';
public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
/**
* Creates a fresh entity instance for composition
*
* @since 2025.05.01
*
* @return EntityMutableInterface Fresh entity object
*/
public function entityFresh(): EntityMutableInterface;
/**
* Creates/imports an entity into a collection
*
* @since 2025.05.01
*
* @param string|int $collection collection identifier
* @param EntityMutableInterface $entity Entity data
* @param array $options additional options
*
* @return EntityBaseInterface Created entity
*/
public function entityCreate(string|int $collection, EntityMutableInterface $entity, array $options = []): EntityBaseInterface;
/**
* Modifies an existing entity
*
* @since 2025.05.01
*
* @param string|int $collection Collection identifier
* @param string|int $identifier Entity identifier
* @param EntityMutableInterface $entity Entity data
*
* @return EntityBaseInterface Modified entity
*/
public function entityModify(string|int $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface;
/**
* Destroys one or more entities
*
* @since 2025.05.01
*
* @param string|int $collection Collection identifier
* @param string|int ...$identifiers Entity identifiers to destroy
*
* @return array<string|int,bool> List of destroyed entity identifiers
*/
public function entityDestroy(string|int $collection, string|int ...$identifiers): array;
/**
* Copies entities to another collection
*
* @since 2025.05.01
*
* @param string|int $sourceCollection Source collection identifier
* @param string|int $targetCollection Target collection identifier
* @param string|int ...$identifiers Entity identifiers to copy
*
* @return array<string|int,string|int> Map of source identifier => new identifier
*/
public function entityCopy(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
/**
* Moves entities to another collection
*
* @since 2025.05.01
*
* @param string|int $sourceCollection Source collection identifier
* @param string|int $targetCollection Target collection identifier
* @param string|int ...$identifiers Entity identifiers to move
*
* @return array<string|int,bool> List of moved entity identifiers
*/
public function entityMove(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
}

48
shared/lib/Mail/Service/ServiceEntityTransmitInterface.php Normal file
View File

@@ -0,0 +1,48 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use KTXF\Mail\Entity\EntityMutableInterface;
use KTXF\Mail\Exception\SendException;
/**
* Mail Service Transmit Interface
*
* Interface for mail services capable of transmitting outbound entities.
*
* @since 2025.05.01
*/
interface ServiceEntityTransmitInterface extends ServiceBaseInterface {
public const CAPABILITY_ENTITY_TRANSMIT = 'EntityTransmit';
/**
* Creates a fresh entity instance for composition
*
* @since 2025.05.01
*
* @return EntityMutableInterface Fresh entity object
*/
public function entityFresh(): EntityMutableInterface;
/**
* Transmits an outbound entity
*
* @since 2025.05.01
*
* @param EntityMutableInterface $entity Entity to transmit
*
* @return string Entity identifier assigned by the transport
*
* @throws SendException On delivery failure
*/
public function entitySend(EntityMutableInterface $entity): string;
}

119
shared/lib/Mail/Service/ServiceMessageMutableInterface.php
View File

@@ -1,119 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use KTXF\Mail\Entity\IMessageBase;
use KTXF\Mail\Entity\IMessageMutable;
/**
* Mail Service Message Mutable Interface
*
* Optional interface for services that support message CRUD operations.
* Provides message creation, modification, deletion, copying, moving, and flag management.
*
* @since 2025.05.01
*/
interface ServiceMessageMutableInterface extends ServiceBaseInterface {
public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
public const CAPABILITY_ENTITY_DESTROY = 'EntityDestroy';
public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
public const CAPABILITY_ENTITY_FLAG = 'EntityFlag';
/**
* Creates a fresh message instance for composition
*
* @since 2025.05.01
*
* @return IMessageMutable Fresh message object
*/
public function messageFresh(): IMessageMutable;
/**
* Creates/imports a message into a collection
*
* @since 2025.05.01
*
* @param string|int $collection Target collection ID
* @param IMessageMutable $message Message to create
* @param array $options Protocol-specific options (e.g., flags, keywords)
*
* @return IMessageBase Created message with assigned ID
*/
public function messageCreate(string|int $collection, IMessageMutable $message, array $options = []): IMessageBase;
/**
* Modifies an existing message
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param string|int $identifier Message ID
* @param IMessageMutable $message Updated message data
*
* @return IMessageBase Modified message
*/
public function messageModify(string|int $collection, string|int $identifier, IMessageMutable $message): IMessageBase;
/**
* Destroys one or more messages
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param string|int ...$identifiers Message IDs to destroy
*
* @return array<string|int,bool> Map of ID => destroyed
*/
public function messageDestroy(string|int $collection, string|int ...$identifiers): array;
/**
* Copies messages to another collection
*
* @since 2025.05.01
*
* @param string|int $sourceCollection Source collection ID
* @param string|int $targetCollection Target collection ID
* @param string|int ...$identifiers Message IDs to copy
*
* @return array<string|int,string|int> Map of source ID => new ID
*/
public function messageCopy(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
/**
* Moves messages to another collection
*
* @since 2025.05.01
*
* @param string|int $sourceCollection Source collection ID
* @param string|int $targetCollection Target collection ID
* @param string|int ...$identifiers Message IDs to move
*
* @return array<string|int,bool> Map of ID => moved
*/
public function messageMove(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;
/**
* Sets flags on messages
*
* @since 2025.05.01
*
* @param string|int $collection Collection ID
* @param array $flags Flags to set (e.g., ['\Seen', '\Flagged'])
* @param bool $value True to add flags, false to remove
* @param string|int ...$identifiers Message IDs
*
* @return array<string|int,bool> Map of ID => success
*/
public function messageFlag(string|int $collection, array $flags, bool $value, string|int ...$identifiers): array;
}

49
shared/lib/Mail/Service/ServiceMessageSendInterface.php
View File

@@ -1,49 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use KTXF\Mail\Entity\IMessageMutable;
use KTXF\Mail\Exception\SendException;
/**
* Mail Service Send Interface
*
* Interface for mail services capable of sending outbound messages.
* This is the minimum capability for an outbound-only mail service.
*
* @since 2025.05.01
*/
interface ServiceMessageSendInterface extends ServiceBaseInterface {
public const CAPABILITY_SEND = 'Send';
/**
* Creates a new fresh message object
*
* @since 2025.05.01
*
* @return IMessageMutable Fresh message object for composing
*/
public function messageFresh(): IMessageMutable;
/**
* Sends an outbound message
*
* @since 2025.05.01
*
* @param IMessageMutable $message Message to send
*
* @return string Message ID assigned by the transport
*
* @throws SendException On delivery failure
*/
public function messageSend(IMessageMutable $message): string;
}

14
shared/lib/Mail/Service/ServiceMutableInterface.php
View File

@@ -9,7 +9,7 @@ declare(strict_types=1);
namespace KTXF\Mail\Service;
use KTXF\Mail\Entity\IAddress;
use KTXF\Mail\Object\AddressInterface;
/**
* Mail Service Mutable Interface
@@ -26,21 +26,21 @@ interface ServiceMutableInterface extends ServiceBaseInterface {
*
* @since 2025.05.01
*
* @param IAddress $value Primary email address
* @param AddressInterface $value Primary email address
*
* @return self
* @return static
*/
public function setPrimaryAddress(IAddress $value): self;
public function setPrimaryAddress(AddressInterface $value): static;
/**
* Sets the secondary mailing addresses (aliases) for this service
*
* @since 2025.05.01
*
* @param array<int, IAddress> $value Array of secondary addresses
* @param array<int,AddressInterface> $value Array of secondary addresses
*
* @return self
* @return static
*/
public function setSecondaryAddresses(array $value): self;
public function setSecondaryAddresses(array $value): static;
}