includes/utils/UIDGenerator.php
<?php
/**
* This file deals with UID generation.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @file
*/
use MediaWiki\MediaWikiServices;
use Wikimedia\UUID\GlobalIdGenerator;
/**
* Class for getting statistically unique IDs
*
* @since 1.21
* @deprecated Since 1.35; use GlobalIdGenerator instead
*/
class UIDGenerator {
/** @var int B/C constant (deprecated since 1.35) */
public const QUICK_RAND = 0; // b/c
/** @var int B/C constant (deprecated since 1.35) */
public const QUICK_VOLATILE = GlobalIdGenerator::QUICK_VOLATILE;
/**
* Get a statistically unique 88-bit unsigned integer ID string.
* The bits of the UID are prefixed with the time (down to the millisecond).
*
* These IDs are suitable as values for the shard key of distributed data.
* If a column uses these as values, it should be declared UNIQUE to handle collisions.
* New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast.
* They can also be stored "DECIMAL(27) UNSIGNED" or BINARY(11) in MySQL.
*
* UID generation is serialized on each server (as the node ID is for the whole machine).
*
* @param int $base Specifies a base other than 10
* @return string Number
* @throws RuntimeException
*/
public static function newTimestampedUID88( $base = 10 ) {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newTimestampedUID88( $base );
}
/**
* Get a statistically unique 128-bit unsigned integer ID string.
* The bits of the UID are prefixed with the time (down to the millisecond).
*
* These IDs are suitable as globally unique IDs, without any enforced uniqueness.
* New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast.
* They can also be stored as "DECIMAL(39) UNSIGNED" or BINARY(16) in MySQL.
*
* UID generation is serialized on each server (as the node ID is for the whole machine).
*
* @param int $base Specifies a base other than 10
* @return string Number
* @throws RuntimeException
*/
public static function newTimestampedUID128( $base = 10 ) {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newTimestampedUID128( $base );
}
/**
* Return an RFC4122 compliant v1 UUID
*
* @return string
* @throws RuntimeException
* @since 1.27
*/
public static function newUUIDv1() {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newUUIDv1();
}
/**
* Return an RFC4122 compliant v1 UUID
*
* @return string 32 hex characters with no hyphens
* @throws RuntimeException
* @since 1.27
*/
public static function newRawUUIDv1() {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newRawUUIDv1();
}
/**
* Get timestamp in a specified format from UUIDv1
*
* @param string $uuid the UUID to get the timestamp from
* @param int $format the format to convert the timestamp to. Default: TS_MW
* @return string|false timestamp in requested format or false
*/
public static function getTimestampFromUUIDv1( string $uuid, int $format = TS_MW ) {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->getTimestampFromUUIDv1( $uuid, $format );
}
/**
* Return an RFC4122 compliant v4 UUID
*
* @param int $flags Bitfield (unused)
* @return string
* @throws RuntimeException
*/
public static function newUUIDv4( $flags = 0 ) {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newUUIDv4();
}
/**
* Return an RFC4122 compliant v4 UUID
*
* @param int $flags Bitfield (unused)
* @return string 32 hex characters with no hyphens
* @throws RuntimeException
*/
public static function newRawUUIDv4( $flags = 0 ) {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newRawUUIDv4();
}
/**
* Return an ID that is sequential *only* for this node and bucket
*
* These IDs are suitable for per-host sequence numbers, e.g. for some packet protocols.
* If UIDGenerator::QUICK_VOLATILE is used the counter might reset on server restart.
*
* @param string $bucket Arbitrary bucket name (should be ASCII)
* @param int $bits Bit size (<=48) of resulting numbers before wrap-around
* @param int $flags (supports UIDGenerator::QUICK_VOLATILE)
* @return float Integer value as float
* @since 1.23
*/
public static function newSequentialPerNodeID( $bucket, $bits = 48, $flags = 0 ) {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newSequentialPerNodeID( $bucket, $bits, $flags );
}
/**
* Return IDs that are sequential *only* for this node and bucket
*
* @see UIDGenerator::newSequentialPerNodeID()
* @param string $bucket Arbitrary bucket name (should be ASCII)
* @param int $bits Bit size (16 to 48) of resulting numbers before wrap-around
* @param int $count Number of IDs to return
* @param int $flags (supports UIDGenerator::QUICK_VOLATILE)
* @return array Ordered list of float integer values
* @since 1.23
*/
public static function newSequentialPerNodeIDs( $bucket, $bits, $count, $flags = 0 ) {
$gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
return $gen->newSequentialPerNodeIDs( $bucket, $bits, $count, $flags );
}
}