Skip to content

feat: Enhance Attribute and Message annotations with improved generics support for better type safety. #600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat: Enhance Attribute and Message annotations with improved generics support for better type safety. #600

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 39 additions & 32 deletions src/Attribute.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,11 @@
* Class Attribute
*
* @package Webklex\PHPIMAP
*
* @implements ArrayAccess<TKey, TValue>
*
* @template TKey of array-key
* @template TValue
*/
class Attribute implements ArrayAccess {

Expand All @@ -28,14 +33,14 @@ class Attribute implements ArrayAccess {
/**
* Value holder
*
* @var array $values
* @var array<TKey, TValue> $values
*/
protected array $values = [];

/**
* Attribute constructor.
* @param string $name
* @param mixed|null $value
* @param TValue|TValue[]|null $value
*/
public function __construct(string $name, mixed $value = null) {
$this->setName($name);
Expand All @@ -57,7 +62,7 @@ public function __invoke(): array|string {
/**
* Return the serialized address
*
* @return array
* @return array<TKey, TValue>
*/
public function __serialize(){
return $this->values;
Expand All @@ -84,7 +89,7 @@ public function toString(): string {
/**
* Convert instance to array
*
* @return array
* @return array<TKey, TValue>
*/
public function toArray(): array {
return $this->__serialize();
Expand All @@ -105,7 +110,7 @@ public function toDate(): Carbon {
/**
* Determine if a value exists at a given key.
*
* @param int|string $key
* @param TKey $key
* @return bool
*/
public function has(mixed $key = 0): bool {
Expand All @@ -115,7 +120,7 @@ public function has(mixed $key = 0): bool {
/**
* Determine if a value exists at a given key.
*
* @param int|string $key
* @param TKey $key
* @return bool
*/
public function exist(mixed $key = 0): bool {
Expand All @@ -135,19 +140,20 @@ public function contains(mixed $value): bool {
/**
* Get a value by a given key.
*
* @param int|string $key
* @return mixed
* @param TKey $key
*
* @return TValue|null
*/
public function get(int|string $key = 0): mixed {
public function get(int|string $key = 0) {
return $this->values[$key] ?? null;
}

/**
* Set the value by a given key.
*
* @param mixed $key
* @param mixed $value
* @return Attribute
* @param TKey $key
* @param TValue $value
* @return $this
*/
public function set(mixed $value, mixed $key = 0): Attribute {
if (is_null($key)) {
Expand All @@ -161,8 +167,8 @@ public function set(mixed $value, mixed $key = 0): Attribute {
/**
* Unset a value by a given key.
*
* @param int|string $key
* @return Attribute
* @param TKey $key
* @return $this
*/
public function remove(int|string $key = 0): Attribute {
if (isset($this->values[$key])) {
Expand All @@ -173,10 +179,10 @@ public function remove(int|string $key = 0): Attribute {

/**
* Add one or more values to the attribute
* @param array|mixed $value
* @param TValue|TValue[]|null $value
* @param boolean $strict
*
* @return Attribute
* @return $this
*/
public function add(mixed $value, bool $strict = false): Attribute {
if (is_array($value)) {
Expand All @@ -190,10 +196,10 @@ public function add(mixed $value, bool $strict = false): Attribute {

/**
* Merge a given array of values with the current values array
* @param array $values
* @param TValue[] $values
* @param boolean $strict
*
* @return Attribute
* @return $this
*/
public function merge(array $values, bool $strict = false): Attribute {
foreach ($values as $value) {
Expand All @@ -205,9 +211,9 @@ public function merge(array $values, bool $strict = false): Attribute {

/**
* Attach a given value to the current value array
* @param $value
* @param TValue $value
* @param bool $strict
* @return Attribute
* @return $this
*/
public function attach($value, bool $strict = false): Attribute {
if ($strict === true) {
Expand All @@ -224,7 +230,7 @@ public function attach($value, bool $strict = false): Attribute {
* Set the attribute name
* @param $name
*
* @return Attribute
* @return $this
*/
public function setName($name): Attribute {
$this->name = $name;
Expand All @@ -244,7 +250,7 @@ public function getName(): string {
/**
* Get all values
*
* @return array
* @return array<TKey, TValue>
*/
public function all(): array {
reset($this->values);
Expand All @@ -254,7 +260,7 @@ public function all(): array {
/**
* Get the first value if possible
*
* @return mixed|null
* @return TValue|null
*/
public function first(): mixed {
return reset($this->values);
Expand All @@ -263,7 +269,7 @@ public function first(): mixed {
/**
* Get the last value if possible
*
* @return mixed|null
* @return TValue|null
*/
public function last(): mixed {
return end($this->values);
Expand All @@ -280,7 +286,7 @@ public function count(): int {

/**
* @see ArrayAccess::offsetExists
* @param mixed $offset
* @param TKey $offset
* @return bool
*/
public function offsetExists(mixed $offset): bool {
Expand All @@ -289,17 +295,17 @@ public function offsetExists(mixed $offset): bool {

/**
* @see ArrayAccess::offsetGet
* @param mixed $offset
* @return mixed
* @param TKey $offset
* @return TValue|null
*/
public function offsetGet(mixed $offset): mixed {
return $this->get($offset);
}

/**
* @see ArrayAccess::offsetSet
* @param mixed $offset
* @param mixed $value
* @param TKey $offset
* @param TValue $value
* @return void
*/
public function offsetSet(mixed $offset, mixed $value): void {
Expand All @@ -308,16 +314,17 @@ public function offsetSet(mixed $offset, mixed $value): void {

/**
* @see ArrayAccess::offsetUnset
* @param mixed $offset
* @param TKey $offset
* @return void
*/
public function offsetUnset(mixed $offset): void {
$this->remove($offset);
}

/**
* @param callable $callback
* @return array
* @template TReturn
* @param callable(TValue):TReturn $callback
* @return array<TKey, TReturn>
*/
public function map(callable $callback): array {
return array_map($callback, $this->values);
Expand Down
50 changes: 25 additions & 25 deletions src/Message.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,37 +51,37 @@
* @property integer $uid
* @property integer $msgn
* @property integer $size
* @property Attribute $subject
* @property Attribute $message_id
* @property Attribute $message_no
* @property Attribute $references
* @property Attribute $date
* @property Attribute $from
* @property Attribute $to
* @property Attribute $cc
* @property Attribute $bcc
* @property Attribute $reply_to
* @property Attribute $in_reply_to
* @property Attribute $sender
* @property Attribute<int, string> $subject
* @property Attribute<int, string> $message_id
* @property Attribute<int, int> $message_no
* @property Attribute<int, string> $references
* @property Attribute<int, \Carbon\Carbon> $date
* @property Attribute<int, Address> $from
* @property Attribute<int, Address> $to
* @property Attribute<int, Address> $cc
* @property Attribute<int, Address> $bcc
* @property Attribute<int, Address> $reply_to
* @property Attribute<int, string> $in_reply_to
* @property Attribute<int, Address> $sender
*
* @method integer getMsglist()
* @method integer setMsglist($msglist)
* @method integer getUid()
* @method integer getMsgn()
* @method integer getSize()
* @method Attribute getPriority()
* @method Attribute getSubject()
* @method Attribute getMessageId()
* @method Attribute getMessageNo()
* @method Attribute getReferences()
* @method Attribute getDate()
* @method Attribute getFrom()
* @method Attribute getTo()
* @method Attribute getCc()
* @method Attribute getBcc()
* @method Attribute getReplyTo()
* @method Attribute getInReplyTo()
* @method Attribute getSender()
* @method Attribute<int, string|int> getPriority()
* @method Attribute<int, string> getSubject()
* @method Attribute<int, string> getMessageId()
* @method Attribute<int, int> getMessageNo()
* @method Attribute<int, string> getReferences()
* @method Attribute<int, \Carbon\Carbon> getDate()
* @method Attribute<int, Address> getFrom()
* @method Attribute<int, Address> getTo()
* @method Attribute<int, Address> getCc()
* @method Attribute<int, Address> getBcc()
* @method Attribute<int, Address> getReplyTo()
* @method Attribute<int, string> getInReplyTo()
* @method Attribute<int, Address> getSender()
*/
class Message {
use HasEvents;
Expand Down