feature: notice class and factory

includes/class-notice-factory.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Notifications API:Message_Factory class
+ *
+ * @package wordpress/wp-feature-notifications
+ */
+
+namespace WP\Notifications;
+
+use DateTime;
+
+/**
+ * Class representing a notice factory.
+ */
+class Notice_Factory {
+
+	/**
+	 * Instantiates a Notice object.
+
+	 * @param array|string $args     {
+	 *     Array or string of arguments for creating a notice. Supported arguments are described below.
+	 *
+	 *     @type string               $channel_name Channel name, including namespace, the notice was emitted from.
+	 *     @type int                  $message_id   ID of the message related to the notice.
+	 *     @type int                  $user_id      ID of the user the notice belongs to.
+	 *     @type string|null          $context      Optional display context of the notice. Default `'adminbar'`
+	 *     @type string|DateTime|null $created_at   Optional datetime at which the notice was created. Default `null`
+	 *     @type string|DateTime|null $dismissed_at Optional datetime  t which the notice was dismissed. Default `null`
+	 *     @type string|DateTime|null $displayed_at Optional datetime at which the notice was first displayed. Default `null`
+	 *     @type string|DateTime|null $expires_at   Optional datetime at which the notice expires. Default `null`
+	 * }
+	 * @param bool         $validate Optionally validate the arguments.
+	 *
+	 * @return Message|false A newly created instance of Channel or false.
+	 */
+	public function make( $args ) {
+		$parsed = wp_parse_args( $args );
+
+		// Required properties
+
+		$channel_name = $parsed['channel_name'];
+		$message_id   = $parsed['message_id'];
+		$user_id      = $parsed['user_id'];
+
+		// Optional properties
+
+		$context      = array_key_exists( 'context', $parsed ) ? $parsed['context'] : 'adminbar';
+		$created_at   = array_key_exists( 'created_at', $parsed ) ? $parsed['created_at'] : null;
+		$dismissed_at = array_key_exists( 'dismissed_at', $parsed ) ? $parsed['dismissed_at'] : null;
+		$displayed_at = array_key_exists( 'displayed_at', $parsed ) ? $parsed['displayed_at'] : null;
+		$expires_at   = array_key_exists( 'expires_at', $parsed ) ? $parsed['expires_at'] : null;
+
+		// Deserialize MySQL datetime stings.
+
+		$created_at   = Helpers\Serde::maybe_deserialize_mysql_date( $created_at );
+		$dismissed_at = Helpers\Serde::maybe_deserialize_mysql_date( $dismissed_at );
+		$displayed_at = Helpers\Serde::maybe_deserialize_mysql_date( $displayed_at );
+		$expires_at   = Helpers\Serde::maybe_deserialize_mysql_date( $expires_at );
+
+		$notice = new Notice(
+			$channel_name,
+			$message_id,
+			$user_id,
+			$context,
+			$created_at,
+			$dismissed_at,
+			$displayed_at,
+			$expires_at
+		);
+
+		return $notice;
+	}
+}

includes/class-notice.php

@@ -0,0 +1,208 @@
+<?php
+/**
+ * Notifications API:Notice class
+ *
+ * @package wordpress/wp-feature-notifications
+ */
+
+namespace WP\Notifications;
+
+use DateTime;
+use JsonSerializable;
+
+/**
+ * Class representing a notification.
+ */
+class Notice implements JsonSerializable {
+
+	/**
+	 * Channel name, including namespace, the notice belongs to.
+	 *
+	 * @var string
+	 */
+	protected string $channel_name;
+
+	/**
+	 * Display context of the notice.
+	 *
+	 * @var string|null
+	 */
+	protected $context;
+
+	/**
+	 * Datetime at which the notice was created.
+	 *
+	 * @var DateTime|null
+	 */
+	protected $created_at;
+
+	/**
+	 * Datetime at which the notice was dismissed.
+	 *
+	 * @var DateTime|null
+	 */
+	protected $dismissed_at;
+
+	/**
+	 * Datetime at which the notice was first displayed to the user.
+	 *
+	 * Intended to facility polling for new notices from the client.
+	 *
+	 * @var DateTime|null
+	 */
+	protected $displayed_at;
+
+	/**
+	 * Datetime at which the notice expires.
+	 *
+	 * Intended to allow notice emitters to specify when a notice can be automatically
+	 * disposed of in UTC time.
+	 *
+	 * @var DateTime|null
+	 */
+	protected $expires_at;
+
+	/**
+	 * Database ID of the message related to the notice.
+	 *
+	 * @var int
+	 */
+	protected int $message_id;
+
+	/**
+	 * Database ID of the user the notice belongs to.
+	 *
+	 * @var int
+	 */
+	protected int $user_id;
+
+	/**
+	 * Constructor.
+	 *
+	 * Instantiates a Notice object.
+	 *
+	 * @param string        $channel_name Channel name, including namespace, the notice was emitted from.
+	 * @param int           $message_id   ID of the message related to the notice.
+	 * @param int           $user_id      ID of the user the notice belongs to.
+	 * @param string|null   $context      Optional display context of the notice. Default `'adminbar'`
+	 * @param DateTime|null $created_at   Optional datetime at which the notice was created.
+	 * @param DateTime|null $dismissed_at Optional datetime  t which the notice was dismissed.
+	 * @param DateTime|null $displayed_at Optional datetime at which the notice was first displayed.
+	 * @param DateTime|null $expires_at   Optional datetime at which the notice expires.
+	 */
+	public function __construct(
+		$channel_name,
+		$message_id,
+		$user_id,
+		$context = 'admin',
+		$created_at = null,
+		$dismissed_at = null,
+		$displayed_at = null,
+		$expires_at = null
+	) {
+		// Required properties
+
+		$this->channel_name = $channel_name;
+		$this->message_id   = $message_id;
+		$this->user_id      = $user_id;
+
+		// Optional properties
+
+		$this->context      = $context;
+		$this->created_at   = $created_at;
+		$this->dismissed_at = $dismissed_at;
+		$this->displayed_at = $displayed_at;
+		$this->expires_at   = $expires_at;
+	}
+
+	/**
+	 * Specifies data which should be serialized to JSON.
+	 *
+	 * @return mixed Data which can be serialized by json_encode, which is a
+	 *               value of any type other than a resource.
+	 */
+	public function jsonSerialize(): mixed {
+		return array(
+			'channel_name' => $this->channel_name,
+			'context'      => $this->context,
+			'created_at'   => Helpers\Serde::maybe_serialize_json_date( $this->created_at ),
+			'dismissed_at' => Helpers\Serde::maybe_serialize_json_date( $this->dismissed_at ),
+			'displayed_at' => Helpers\Serde::maybe_serialize_json_date( $this->displayed_at ),
+			'expires_at'   => Helpers\Serde::maybe_serialize_json_date( $this->expires_at ),
+			'message_id'   => $this->message_id,
+			'user_id'      => $this->user_id,
+		);
+	}
+
+	/**
+	 * Get the namespaced channel name.
+	 *
+	 * @return string The namespaced channel name of the notice.
+	 */
+	public function get_channel_name(): string {
+		return $this->channel_name;
+	}
+
+	/**
+	 * Get the display context.
+	 *
+	 * @return string|null The display context of the notice.
+	 */
+	public function get_context() {
+		return $this->context;
+	}
+
+	/**
+	 * Get the created at datetime.
+	 *
+	 * @return DateTime|null The datetime at which the notice was created.
+	 */
+	public function get_created_at() {
+		return $this->created_at;
+	}
+
+	/**
+	 * Get the dismissed at datetime.
+	 *
+	 * @return DateTime|null The datetime at which the notice was dismissed.
+	 */
+	public function get_dismissed_at() {
+		return $this->dismissed_at;
+	}
+
+	/**
+	 * Get the displayed at datetime.
+	 *
+	 * @return DateTime|null The datetime at which the notice was first displayed.
+	 */
+	public function get_displayed_at() {
+		return $this->displayed_at;
+	}
+
+	/**
+	 * Get the expires at datetime.
+	 *
+	 * @return DateTime|null The datetime at which the notice expires.
+	 */
+	public function get_expires_at() {
+		return $this->expires_at;
+	}
+
+	/**
+	 * Get the message ID.
+	 *
+	 * @return DateTime|null The database ID of the message related to the notice.
+	 */
+	public function get_message_id() {
+		return $this->message_id;
+	}
+
+	/**
+	 * Get the user ID.
+	 *
+	 * @return DateTime|null The database ID of the user the notice belongs to.
+	 */
+	public function get_user_id() {
+		return $this->user_id;
+	}
+}