feat: add possibility to define return field for built-in recipients

phpstan-baseline.neon

@@ -1660,11 +1660,6 @@ parameters:
 			count: 1
 			path: src/Repository/Recipient/BaseRecipient.php
 
-		-
-			message: "#^Parameter \\#1 \\$args of function get_users expects array\\{blog_id\\?\\: int, role\\?\\: array\\<string\\>\\|string, role__in\\?\\: array\\<string\\>, role__not_in\\?\\: array\\<string\\>, meta_key\\?\\: array\\<string\\>\\|string, meta_value\\?\\: array\\<string\\>\\|string, meta_compare\\?\\: string, meta_compare_key\\?\\: string, \\.\\.\\.\\}, array\\{include\\: non\\-empty\\-array\\<int, string\\>, fields\\: array\\{'user_email'\\}\\} given\\.$#"
-			count: 1
-			path: src/Repository/Recipient/UserID.php
-
 		-
 			message: "#^Parameter \\#3 \\$subject of function str_replace expects array\\|string, mixed given\\.$#"
 			count: 1

readme.txt

@@ -365,6 +365,7 @@ Removed deprecated hooks:
 * [Added] Notification converter concept, with array and JSON default converters.
 * [Added] Custom wp_notifications table (with corresponding helper tables).
 * [Added] User nickname merge tag.
+* [Added] Possibility to define return field for built-in recipients (ID or user_email)
 * [Changed] Notification is now saved to the custom table instead of wp_posts.
 * [Changed] Global functions has been deprecated and got equivalents in respective classes.
 * [Changed] Removed v6 & v7 deprecated functions.

src/Repository/Recipient/BaseRecipient.php

@@ -24,6 +24,18 @@ abstract class BaseRecipient implements Interfaces\Receivable
 	use Traits\HasSlug;
 	use Casegnostic;
 
+	/**
+	 * List of available return fields.
+	 */
+	protected const AVAILABLE_RETURN_FIELDS = ['ID', 'user_email'];
+
+	/**
+	 * Return field key name.
+	 *
+	 * @var string
+	 */
+	protected $returnField = 'user_email';
+
 	/**
 	 * Recipient input default value
 	 *
@@ -47,6 +59,16 @@ public function __construct($params = [])
 			$this->setName($params['name']);
 		}
 
+		if (is_string($params['return_field'] ?? null)) {
+			$returnField = $params['return_field'];
+
+			if (!in_array($returnField, self::AVAILABLE_RETURN_FIELDS, true)) {
+				trigger_error(sprintf('Recipient return field "%s" is not supported.', $returnField), E_USER_ERROR);
+			}
+
+			$this->returnField = $returnField;
+		}
+
 		if (!isset($params['default_value'])) {
 			trigger_error('Recipient requires default_value', E_USER_ERROR);
 		}

src/Repository/Recipient/Role.php

@@ -22,15 +22,19 @@ class Role extends BaseRecipient
 	 * Recipient constructor
 	 *
 	 * @since 5.0.0
+	 * @param array<mixed> $params recipient configuration params.
 	 */
-	public function __construct()
+	public function __construct($params = [])
 	{
 		parent::__construct(
-			[
-				'slug' => 'role',
-				'name' => __('Role', 'notification'),
-				'default_value' => 'administrator',
-			]
+			array_merge(
+				$params,
+				[
+					'slug' => 'role',
+					'name' => __('Role', 'notification'),
+					'default_value' => 'administrator',
+				]
+			)
 		);
 	}
 
@@ -46,13 +50,13 @@ public function parseValue($value = '')
 			$value = $this->getDefaultValue();
 		}
 
-		$emails = [];
+		$values = [];
 
 		foreach (UserQueries::withRole($value) as $user) {
-			$emails[] = $user['user_email'];
+			$values[] = $user[$this->returnField];
 		}
 
-		return $emails;
+		return $values;
 	}
 
 	/**

src/Repository/Recipient/User.php

@@ -22,15 +22,19 @@ class User extends BaseRecipient
 	 * Recipient constructor
 	 *
 	 * @since 5.0.0
+	 * @param array<mixed> $params recipient configuration params.
 	 */
-	public function __construct()
+	public function __construct($params = [])
 	{
 		parent::__construct(
-			[
-				'slug' => 'user',
-				'name' => __('User', 'notification'),
-				'default_value' => get_current_user_id(),
-			]
+			array_merge(
+				$params,
+				[
+					'slug' => 'user',
+					'name' => __('User', 'notification'),
+					'default_value' => get_current_user_id(),
+				]
+			)
 		);
 	}
 
@@ -49,8 +53,7 @@ public function parseValue($value = '')
 		$user = get_userdata((int)$value);
 
 		if ($user) {
-			// phpcs:ignore Squiz.NamingConventions.ValidVariableName.MemberNotCamelCaps
-			return [$user->user_email];
+			return [$user->{$this->returnField}];
 		}
 
 		return [];

src/Repository/Recipient/UserID.php

@@ -21,15 +21,19 @@ class UserID extends BaseRecipient
 	 * Recipient constructor
 	 *
 	 * @since 5.0.0
+	 * @param array<mixed> $params recipient configuration params.
 	 */
-	public function __construct()
+	public function __construct($params = [])
 	{
 		parent::__construct(
-			[
-				'slug' => 'user_id',
-				'name' => __('User ID', 'notification'),
-				'default_value' => '',
-			]
+			array_merge(
+				$params,
+				[
+					'slug' => 'user_id',
+					'name' => __('User ID', 'notification'),
+					'default_value' => '',
+				]
+			)
 		);
 	}
 
@@ -45,15 +49,19 @@ public function parseValue($value = '')
 			return [];
 		}
 
-		$userIds = array_map('trim', explode(',', $value));
+		$userIds = array_map(
+			static fn($userId) => intval(trim($userId)),
+			explode(',', $value)
+		);
+
 		$users = get_users(
 			[
 				'include' => $userIds,
-				'fields' => ['user_email'],
+				'fields' => [$this->returnField],
 			]
 		);
 
-		return wp_list_pluck($users, 'user_email');
+		return wp_list_pluck($users, $this->returnField);
 	}
 
 	/**