[RFC] [Draft] Add UUID extension by kocsismate · Pull Request #21715 · php/php-src

kocsismate · 2026-04-10T21:00:04Z

Native support for UUIDs is clearly missing from PHP, so the newly added UUID extension would fill this void. For now, only v7 is implemented, just for demonstration purposes.

I wanted to benchmark how a native implementation compares against symfony/uid and ramsey/uuid performance-wise. Here are the initial results (with the caveat that I have not verified yet the correctness of the native version, and monotonic ordering is not yet guaranteed):

PHP UUID - 50 iterations, 20 warmups, 10 requests (sec)

PHP	Min	Max	Std dev	Rel std dev %	Mean	Median
PHP - UUID	0.07254	0.07463	0.00048	0.65%	0.07329	0.07316

Symfony UUID - 50 iterations, 20 warmups, 10 requests (sec)

PHP	Min	Max	Std dev	Rel std dev %	Mean	Median
PHP - UUID	0.62739	0.63435	0.00137	0.22%	0.63016	0.62998

Ramsey UUID - 50 iterations, 20 warmups, 10 requests (sec)

PHP	Min	Max	Std dev	Rel std dev %	Mean	Median
PHP - UUID	1.04438	1.06381	0.00333	0.32%	1.04850	1.04795

LamentXU123 · 2026-04-11T08:14:30Z

ext/uuid/config.m4

+
+PHP_INSTALL_HEADERS([ext/uuid], m4_normalize([
+  php_uuid.h
+  uuidv7-h/php_uuid.h


This should be uuidv7.h right?

Suggested change

uuidv7-h/php_uuid.h

uuidv7-h/uuidv7.h

LamentXU123 · 2026-04-11T08:17:51Z

Zend/zend_time.c

+
+#else
+
+	ts->tv_sec  = zend_time_real_get();


Suggested change

ts->tv_sec = zend_time_real_get();

ts->tv_sec = zend_time_real_sec();

Is this a typo? We don't get a definition of zend_time_real_get yet(?)

The first commit comes from #21370

LamentXU123 · 2026-04-11T08:26:19Z

ext/uuid/php_uuid.c

+
+ZEND_ATTRIBUTE_NONNULL_ARGS(1) PHPAPI zend_result php_uuid_v7_parse(const zend_string *uuid_str, php_uuid_v7 uuid)
+{
+	int result = uuidv7_from_string(ZSTR_VAL(uuid_str), uuid);


since uuidv7_from_string only check if the input is a valid uuid but not a valid uuidv7. I suggest we can have a function like

static zend_always_inline bool php_uuid_v7_is_valid(const php_uuid_v7 uuid) { return (uuid[6] & 0xf0) == 0x70 && (uuid[8] & 0xc0) == 0x80; }

To specifically check if the input is uuidv7

LamentXU123 · 2026-04-11T08:31:21Z

ext/uuid/php_uuid.c

+		case UUIDV7_STATUS_CLOCK_ROLLBACK:
+			ZEND_FALLTHROUGH;
+		case UUIDV7_STATUS_ERR_TIMESTAMP:
+			ZEND_FALLTHROUGH;


Would this be clearer?

Suggested change

ZEND_FALLTHROUGH;

zend_throw_error(NULL, "The generated UUID v7 timestamp is out of range");

RETURN_THROWS();

I haven't had time to research/think about error handling yet, but it's definitely a good idea.

LamentXU123 · 2026-04-11T08:32:08Z

ext/uuid/php_uuid.c

+		case UUIDV7_STATUS_ERR_TIMESTAMP:
+			ZEND_FALLTHROUGH;
+		case UUIDV7_STATUS_ERR_TIMESTAMP_OVERFLOW:
+			break;


Suggested change

break;

zend_throw_error(NULL, "The generated UUID v7 timestamp overflowed");

RETURN_THROWS();

LamentXU123 · 2026-04-11T08:34:10Z

ext/uuid/php_uuid.c

+	uuid_object->is_initialized = false;
+}
+
+PHP_METHOD(Uuid_UuidV7, generate)


This uses a monotonic clock when no DateTimeImmutable is passed. UUID v7 is supposed to encode Unix wall-clock time, so on platforms where zend_hrtime() is available this will produce timestamps based on uptime rather than the Unix epoch. So I'd suggest to implement a php_uuid_current_unix_time_ms() here, it could also be used in other time-based uuids like uuidv1

LamentXU123 · 2026-04-11T08:46:05Z

ext/uuid/php_uuid.c

+	}
+
+	uint8_t random_bytes[10];
+	for (int i = 0; i < 10; i++) {


The default Random\Engine is MT19937 which is PRNG. In the RFC of uuidv7 the random bytes should be generated in CSPRNG, and therefore I suggest using Random\CryptoSafeEngine instead here.

therefore I suggest using Random\CryptoSafeEngine instead here.

Not necessary to restrict this to CryptSafeEngines, but the default should indeed be Random\Engine\Secure.

LamentXU123 · 2026-04-11T08:50:11Z

ext/uuid/php_uuid.c

+	object_init_ex(return_value, Z_CE_P(ZEND_THIS));
+	php_uuid_v7_object *uuid_object = Z_UUID_V7_OBJECT_P(return_value);
+
+	if (uuidv7_from_string(ZSTR_VAL(uuid_str), uuid_object->uuid) == FAILURE) {
+		zend_throw_exception(NULL, "The specified UUID v7 is malformed", 0);
+		RETURN_THROWS();


If I am understanding this code correctly, this could be clearer:

Suggested change

object_init_ex(return_value, Z_CE_P(ZEND_THIS));

php_uuid_v7_object *uuid_object = Z_UUID_V7_OBJECT_P(return_value);

if (uuidv7_from_string(ZSTR_VAL(uuid_str), uuid_object->uuid) == FAILURE) {

zend_throw_exception(NULL, "The specified UUID v7 is malformed", 0);

RETURN_THROWS();

if (php_uuid_v7_parse(uuid_str, uuid) == FAILURE) {

zend_throw_exception(NULL, "The specified UUID is not a valid UUID v7", 0);

RETURN_THROWS();

LamentXU123 · 2026-04-11T08:53:04Z

ext/uuid/php_uuid.c

+	if (zend_hash_num_elements(Z_ARRVAL_P(arr)) > 0) {
+		zend_throw_exception_ex(NULL, 0, "Invalid serialization data for %s object", ZSTR_VAL(uuid_object->std.ce->name));
+		RETURN_THROWS();
+	}


To make it readonly.

Suggested change

}

}

uuid_object->is_initialized = true;

LamentXU123 · 2026-04-11T08:56:11Z

ext/uuid/php_uuid.c

+	memcpy(new_uuid_object->uuid, uuid_object->uuid, sizeof(php_uuid_v7));
+	zend_objects_clone_members(&new_uuid_object->std, &uuid_object->std);
+


Mark this as is_initialized after we clone it.

Suggested change

memcpy(new_uuid_object->uuid, uuid_object->uuid, sizeof(php_uuid_v7));

zend_objects_clone_members(&new_uuid_object->std, &uuid_object->std);

memcpy(new_uuid_object->uuid, uuid_object->uuid, sizeof(php_uuid_v7));

new_uuid_object->is_initialized = true;

zend_objects_clone_members(&new_uuid_object->std, &uuid_object->std);

TimWolla · 2026-04-11T15:32:20Z

ext/uuid/php_uuid.c

+
+	uint64_t unix_time_ms;
+	if (datetime_object == NULL) {
+		unix_time_ms = zend_time_mono_fallback_nsec() / 1000000;


mono is not the correct block to use, it can only be used to measure durations within a single execution.

TimWolla · 2026-04-11T15:34:08Z

ext/uuid/php_uuid.c

+	}
+
+	uint8_t random_bytes[10];
+	for (int i = 0; i < 10; i++) {


therefore I suggest using Random\CryptoSafeEngine instead here.

Not necessary to restrict this to CryptSafeEngines, but the default should indeed be Random\Engine\Secure.

TimWolla · 2026-04-11T15:36:15Z

ext/uuid/php_uuid.c

+	uint8_t random_bytes[10];
+	for (int i = 0; i < 10; i++) {
+		random_bytes[i] = php_random_range(random_algo, 0, 127);
+	}


This whole loop looks fishy.

why we are random-ing only bytes between 0 and 127🤔 I know its ASCII but not all ASCII bytes are printable, then there is no actual meaning of rander-ing between these bytes. OR maybe I am getting things wrong.

Introduce new time retrieval Zend-API

0448f0d

kocsismate added the Status: Requires RFC label Apr 10, 2026

github-actions bot added Category: Build System Category: Engine ABI break labels Apr 10, 2026

kocsismate mentioned this pull request Apr 10, 2026

Introduce new time retrieval Zend-API #21370

Open

Add UUID extension

866da2f

kocsismate force-pushed the uuid branch from 6890c21 to 866da2f Compare April 11, 2026 04:49

github-actions bot added the Extension: standard label Apr 11, 2026

kocsismate changed the title ~~[Draft] Add UUID extension~~ [RFC] [Draft] Add UUID extension Apr 11, 2026

LamentXU123 reviewed Apr 11, 2026

View reviewed changes

TimWolla reviewed Apr 11, 2026

View reviewed changes

	ts->tv_sec = zend_time_real_get();
	ts->tv_sec = zend_time_real_sec();

	ZEND_FALLTHROUGH;
	zend_throw_error(NULL, "The generated UUID v7 timestamp is out of range");
	RETURN_THROWS();

	break;
	zend_throw_error(NULL, "The generated UUID v7 timestamp overflowed");
	RETURN_THROWS();

-	}
+	}
+	uuid_object->is_initialized = true;

		memcpy(new_uuid_object->uuid, uuid_object->uuid, sizeof(php_uuid_v7));
		zend_objects_clone_members(&new_uuid_object->std, &uuid_object->std);

Conversation

kocsismate commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PHP UUID - 50 iterations, 20 warmups, 10 requests (sec)

Symfony UUID - 50 iterations, 20 warmups, 10 requests (sec)

Ramsey UUID - 50 iterations, 20 warmups, 10 requests (sec)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LamentXU123 Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kocsismate commented Apr 10, 2026 •

edited

Loading

LamentXU123 Apr 12, 2026 •

edited

Loading