Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 18
0.00% covered (danger)
0.00%
0 / 9
CRAP
0.00% covered (danger)
0.00%
0 / 1
UIDGenerator
0.00% covered (danger)
0.00%
0 / 18
0.00% covered (danger)
0.00%
0 / 9
90
0.00% covered (danger)
0.00%
0 / 1
 newTimestampedUID88
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 newTimestampedUID128
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 newUUIDv1
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 newRawUUIDv1
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 getTimestampFromUUIDv1
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 newUUIDv4
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 newRawUUIDv4
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 newSequentialPerNodeID
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 newSequentialPerNodeIDs
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
1<?php
2/**
3 * This file deals with UID generation.
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
19 *
20 * @file
21 */
22use MediaWiki\MediaWikiServices;
23use Wikimedia\UUID\GlobalIdGenerator;
24
25/**
26 * Class for getting statistically unique IDs
27 *
28 * @since 1.21
29 * @deprecated Since 1.35; use GlobalIdGenerator instead
30 */
31class UIDGenerator {
32    /** @var int B/C constant (deprecated since 1.35) */
33    public const QUICK_RAND = 0; // b/c
34    /** @var int B/C constant (deprecated since 1.35) */
35    public const QUICK_VOLATILE = GlobalIdGenerator::QUICK_VOLATILE;
36
37    /**
38     * Get a statistically unique 88-bit unsigned integer ID string.
39     * The bits of the UID are prefixed with the time (down to the millisecond).
40     *
41     * These IDs are suitable as values for the shard key of distributed data.
42     * If a column uses these as values, it should be declared UNIQUE to handle collisions.
43     * New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast.
44     * They can also be stored "DECIMAL(27) UNSIGNED" or BINARY(11) in MySQL.
45     *
46     * UID generation is serialized on each server (as the node ID is for the whole machine).
47     *
48     * @param int $base Specifies a base other than 10
49     * @return string Number
50     * @throws RuntimeException
51     */
52    public static function newTimestampedUID88( $base = 10 ) {
53        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
54
55        return $gen->newTimestampedUID88( $base );
56    }
57
58    /**
59     * Get a statistically unique 128-bit unsigned integer ID string.
60     * The bits of the UID are prefixed with the time (down to the millisecond).
61     *
62     * These IDs are suitable as globally unique IDs, without any enforced uniqueness.
63     * New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast.
64     * They can also be stored as "DECIMAL(39) UNSIGNED" or BINARY(16) in MySQL.
65     *
66     * UID generation is serialized on each server (as the node ID is for the whole machine).
67     *
68     * @param int $base Specifies a base other than 10
69     * @return string Number
70     * @throws RuntimeException
71     */
72    public static function newTimestampedUID128( $base = 10 ) {
73        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
74
75        return $gen->newTimestampedUID128( $base );
76    }
77
78    /**
79     * Return an RFC4122 compliant v1 UUID
80     *
81     * @return string
82     * @throws RuntimeException
83     * @since 1.27
84     */
85    public static function newUUIDv1() {
86        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
87
88        return $gen->newUUIDv1();
89    }
90
91    /**
92     * Return an RFC4122 compliant v1 UUID
93     *
94     * @return string 32 hex characters with no hyphens
95     * @throws RuntimeException
96     * @since 1.27
97     */
98    public static function newRawUUIDv1() {
99        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
100
101        return $gen->newRawUUIDv1();
102    }
103
104    /**
105     * Get timestamp in a specified format from UUIDv1
106     *
107     * @param string $uuid the UUID to get the timestamp from
108     * @param int $format the format to convert the timestamp to. Default: TS_MW
109     * @return string|false timestamp in requested format or false
110     */
111    public static function getTimestampFromUUIDv1( string $uuid, int $format = TS_MW ) {
112        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
113
114        return $gen->getTimestampFromUUIDv1( $uuid, $format );
115    }
116
117    /**
118     * Return an RFC4122 compliant v4 UUID
119     *
120     * @param int $flags Bitfield (unused)
121     * @return string
122     * @throws RuntimeException
123     */
124    public static function newUUIDv4( $flags = 0 ) {
125        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
126
127        return $gen->newUUIDv4();
128    }
129
130    /**
131     * Return an RFC4122 compliant v4 UUID
132     *
133     * @param int $flags Bitfield (unused)
134     * @return string 32 hex characters with no hyphens
135     * @throws RuntimeException
136     */
137    public static function newRawUUIDv4( $flags = 0 ) {
138        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
139
140        return $gen->newRawUUIDv4();
141    }
142
143    /**
144     * Return an ID that is sequential *only* for this node and bucket
145     *
146     * These IDs are suitable for per-host sequence numbers, e.g. for some packet protocols.
147     * If UIDGenerator::QUICK_VOLATILE is used the counter might reset on server restart.
148     *
149     * @param string $bucket Arbitrary bucket name (should be ASCII)
150     * @param int $bits Bit size (<=48) of resulting numbers before wrap-around
151     * @param int $flags (supports UIDGenerator::QUICK_VOLATILE)
152     * @return float Integer value as float
153     * @since 1.23
154     */
155    public static function newSequentialPerNodeID( $bucket, $bits = 48, $flags = 0 ) {
156        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
157
158        return $gen->newSequentialPerNodeID( $bucket, $bits, $flags );
159    }
160
161    /**
162     * Return IDs that are sequential *only* for this node and bucket
163     *
164     * @see UIDGenerator::newSequentialPerNodeID()
165     * @param string $bucket Arbitrary bucket name (should be ASCII)
166     * @param int $bits Bit size (16 to 48) of resulting numbers before wrap-around
167     * @param int $count Number of IDs to return
168     * @param int $flags (supports UIDGenerator::QUICK_VOLATILE)
169     * @return array Ordered list of float integer values
170     * @since 1.23
171     */
172    public static function newSequentialPerNodeIDs( $bucket, $bits, $count, $flags = 0 ) {
173        $gen = MediaWikiServices::getInstance()->getGlobalIdGenerator();
174
175        return $gen->newSequentialPerNodeIDs( $bucket, $bits, $count, $flags );
176    }
177}