Add a Rank class

Author: thiemowmde

src/Statement/Rank.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Wikibase\DataModel\Statement;
+
+use InvalidArgumentException;
+
+/**
+ * @see https://www.mediawiki.org/wiki/Wikibase/DataModel#Ranks_of_Statements
+ * @see https://meta.wikimedia.org/wiki/Wikidata/Data_model_update#Ranks_and_order
+ *
+ * @since 4.4
+ *
+ * @licence GNU GPL v2+
+ * @author Thiemo Mättig
+ */
+class Rank {
+
+	/**
+	 * Higher values are more preferred.
+	 * TODO: Link to discussion/documentation that guarantees increasing order.
+	 */
+	const DEPRECATED = 0;
+	const NORMAL = 1;
+	const PREFERRED = 2;
+
+	/**
+	 * TODO: Add doc.
+	 */
+	const RANK_0 = self::DEPRECATED;
+	const RANK_1 = self::NORMAL;
+	const RANK_2 = self::PREFERRED;
+
+	/**
+	 * @param int $rank
+	 *
+	 * @throws InvalidArgumentException
+	 * @return bool
+	 */
+	public static function isValid( $rank ) {
+		if ( $rank === self::DEPRECATED
+			|| $rank === self::NORMAL
+			|| $rank === self::PREFERRED
+		) {
+			return true;
+		}
+
+		throw new InvalidArgumentException( 'Unknown rank' );
+	}
+
+	/**
+	 * @param int $rank1
+	 * @param int $rank2
+	 *
+	 * @return bool True if the given ranks are equal.
+	 */
+	public static function equals( $rank1, $rank2 ) {
+		return self::compare( $rank1, $rank2 ) === 0;
+	}
+
+	/**
+	 * @param int $rank1
+	 * @param int $rank2
+	 *
+	 * @return bool True if the first rank is less preferred than the second.
+	 */
+	public static function isLower( $rank1, $rank2 ) {
+		return self::compare( $rank1, $rank2 ) === -1;
+	}
+
+	/**
+	 * @param int $rank1
+	 * @param int $rank2
+	 *
+	 * @return bool True if the first rank is more preferred than the second.
+	 */
+	public static function isHigher( $rank1, $rank2 ) {
+		return self::compare( $rank1, $rank2 ) === 1;
+	}
+
+	/**
+	 * @param int $rank1
+	 * @param int $rank2
+	 *
+	 * @return int 0 if the ranks are equal, -1 if the first or +1 if the second is more preferred.
+	 */
+	public static function compare( $rank1, $rank2 ) {
+		self::isValid( $rank1 );
+		self::isValid( $rank2 );
+
+		return $rank1 - $rank2;
+	}
+
+}

src/Statement/Statement.php

@@ -29,9 +29,9 @@ class Statement implements Hashable, Comparable, PropertyIdProvider {
 	 *
 	 * @since 2.0
 	 */
-	const RANK_PREFERRED = 2;
-	const RANK_NORMAL = 1;
-	const RANK_DEPRECATED = 0;
+	const RANK_PREFERRED = Rank::PREFERRED;
+	const RANK_NORMAL = Rank::NORMAL;
+	const RANK_DEPRECATED = Rank::DEPRECATED;
 
 	/**
 	 * @var string|null