*/ private const VALID_PRIORITIES = array( self::LOW, self::NORMAL, self::HIGH, self::URGENT, ); /** * Mapping from priority token to internal ordering weight. * * @var array */ private const WEIGHTS = array( self::LOW => self::WEIGHT_LOW, self::NORMAL => self::WEIGHT_NORMAL, self::HIGH => self::WEIGHT_HIGH, self::URGENT => self::WEIGHT_URGENT, ); /** * Canonical priority token. */ private string $value; /** * Cached numeric ordering weight for {@see self::$value}. */ private int $weight; /** * Private constructor — instances are obtained via the static * named constructors {@see self::low()} / {@see self::normal()} * / {@see self::high()} / {@see self::urgent()} or via * {@see self::fromString()} for deserialization paths. * * @param string $value Pre-validated priority token. * @param int $weight Pre-resolved ordering weight. */ private function __construct( string $value, int $weight ) { $this->value = $value; $this->weight = $weight; } /** * Construct a `low` priority instance. */ public static function low(): self { return new self( self::LOW, self::WEIGHT_LOW ); } /** * Construct a `normal` priority instance. */ public static function normal(): self { return new self( self::NORMAL, self::WEIGHT_NORMAL ); } /** * Construct a `high` priority instance. */ public static function high(): self { return new self( self::HIGH, self::WEIGHT_HIGH ); } /** * Construct an `urgent` priority instance. */ public static function urgent(): self { return new self( self::URGENT, self::WEIGHT_URGENT ); } /** * Construct a priority instance from a raw string token, * validating against the closed §13.2 set. * * The token is trimmed first so a carelessly-decoded payload * (trailing newline, padded space) is normalized to the same * canonical form a freshly-constructed priority would carry. * * @param string $value Raw priority token as supplied by the caller. * * @throws InvalidArgumentException When `$value` is not a * member of the §13.2 closed * set. */ public static function fromString( string $value ): self { $trimmed = trim( $value ); if ( ! array_key_exists( $trimmed, self::WEIGHTS ) ) { $message = sprintf( 'SyncPriority must be one of [%s]; got "%s".', implode( ', ', self::VALID_PRIORITIES ), $value ); // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Developer-facing message, never rendered to HTML. throw new InvalidArgumentException( $message ); } return new self( $trimmed, self::WEIGHTS[ $trimmed ] ); } /** * Closed set of accepted priority tokens, in ascending weight * order. * * @return list */ public static function validPriorities(): array { return self::VALID_PRIORITIES; } /** * Canonical priority token. */ public function value(): string { return $this->value; } /** * Numeric ordering weight associated with this priority. * * Higher numbers mean "should run sooner". The concrete values * (low=10, normal=50, high=80, urgent=100) are an internal * ordering convention; consumers SHOULD prefer * {@see self::isHigherThan()} / {@see self::isAtLeast()} over * comparing the raw integers. */ public function weight(): int { return $this->weight; } /** * Value-object equality: two priorities are equal iff their * tokens match exactly. * * @param SyncPriority $other Other priority to compare against. */ public function equals( SyncPriority $other ): bool { return $this->value === $other->value; } /** * Whether this priority outranks `$other` (strictly higher * weight). * * @param SyncPriority $other Other priority to compare against. */ public function isHigherThan( SyncPriority $other ): bool { return $this->weight > $other->weight; } /** * Whether this priority is at least as high as `$other` (equal * or higher weight). * * @param SyncPriority $other Other priority to compare against. */ public function isAtLeast( SyncPriority $other ): bool { return $this->weight >= $other->weight; } }