Add API to register custom image handlers

ndossche · ndossche · commit 39a80715d627 · 2025-07-19T14:27:49.000+02:00
This is modelled similarly to the password registry API.
We have an array to which new handlers can be added, and when a built-in
handler cannot handle the image, we try the handlers in the array.
The standard module is in control of registering a new constant for the
image file type so that no clashes can occur. It also updates the image
file type count constant. As such, the registration may only happen
during module startup.
diff --git a/ext/standard/basic_functions.c b/ext/standard/basic_functions.c
@@ -303,6 +303,7 @@ PHP_MINIT_FUNCTION(basic) /* {{{ */
 	BASIC_MINIT_SUBMODULE(standard_filters)
 	BASIC_MINIT_SUBMODULE(user_filters)
 	BASIC_MINIT_SUBMODULE(password)
+	BASIC_MINIT_SUBMODULE(image)
 
 #ifdef ZTS
 	BASIC_MINIT_SUBMODULE(localeconv)
@@ -376,6 +377,7 @@ PHP_MSHUTDOWN_FUNCTION(basic) /* {{{ */
 #endif
 	BASIC_MSHUTDOWN_SUBMODULE(crypt)
 	BASIC_MSHUTDOWN_SUBMODULE(password)
+	BASIC_MSHUTDOWN_SUBMODULE(image)
 
 	return SUCCESS;
 }
diff --git a/ext/standard/basic_functions.stub.php b/ext/standard/basic_functions.stub.php
@@ -653,7 +653,7 @@
 const IMAGETYPE_UNKNOWN = UNKNOWN;
 /**
  * @var int
- * @cvalue IMAGE_FILETYPE_COUNT
+ * @cvalue IMAGE_FILETYPE_FIXED_COUNT
  */
 const IMAGETYPE_COUNT = UNKNOWN;
 
@@ -3027,13 +3027,11 @@ function request_parse_body(?array $options = null): array {}
 /* image.c */
 
 /**
- * @compile-time-eval
  * @refcount 1
  */
 function image_type_to_mime_type(int $image_type): string {}
 
 /**
- * @compile-time-eval
  * @refcount 1
  */
 function image_type_to_extension(int $image_type, bool $include_dot = true): string|false {}
diff --git a/ext/standard/basic_functions_arginfo.h b/ext/standard/basic_functions_arginfo.h
diff --git a/ext/standard/image.c b/ext/standard/image.c
@@ -52,6 +52,9 @@ PHPAPI const char php_sig_ico[4] = {(char)0x00, (char)0x00, (char)0x01, (char)0x
 PHPAPI const char php_sig_riff[4] = {'R', 'I', 'F', 'F'};
 PHPAPI const char php_sig_webp[4] = {'W', 'E', 'B', 'P'};
 
+static zend_array php_image_handlers;
+static int php_image_handler_next_id = IMAGE_FILETYPE_FIXED_COUNT;
+
 /* REMEMBER TO ADD MIME-TYPE TO FUNCTION php_image_type_to_mime_type */
 /* PCX must check first 64bytes and byte 0=0x0a and byte2 < 0x06 */
 
@@ -1210,7 +1213,7 @@ bool php_is_image_avif(php_stream* stream) {
 
 /* {{{ php_image_type_to_mime_type
  * Convert internal image_type to mime type */
-PHPAPI char * php_image_type_to_mime_type(int image_type)
+PHPAPI const char * php_image_type_to_mime_type(int image_type)
 {
 	switch( image_type) {
 		case IMAGE_FILETYPE_GIF:
@@ -1245,7 +1248,13 @@ PHPAPI char * php_image_type_to_mime_type(int image_type)
 			return "image/webp";
 		case IMAGE_FILETYPE_AVIF:
 			return "image/avif";
-		default:
+		default: {
+			const struct php_image_handler *handler = zend_hash_index_find_ptr(&php_image_handlers, (zend_ulong) image_type);
+			if (handler) {
+				return handler->mime_type;
+			}
+			ZEND_FALLTHROUGH;
+		}
 		case IMAGE_FILETYPE_UNKNOWN:
 			return "application/octet-stream"; /* suppose binary format */
 	}
@@ -1261,7 +1270,7 @@ PHP_FUNCTION(image_type_to_mime_type)
 		Z_PARAM_LONG(p_image_type)
 	ZEND_PARSE_PARAMETERS_END();
 
-	ZVAL_STRING(return_value, (char*)php_image_type_to_mime_type(p_image_type));
+	ZVAL_STRING(return_value, php_image_type_to_mime_type(p_image_type));
 }
 /* }}} */
 
@@ -1330,6 +1339,13 @@ PHP_FUNCTION(image_type_to_extension)
 		case IMAGE_FILETYPE_AVIF:
 			imgext = ".avif";
 			break;
+		default: {
+			const struct php_image_handler *handler = zend_hash_index_find_ptr(&php_image_handlers, (zend_ulong) image_type);
+			if (handler) {
+				imgext = handler->extension;
+			}
+			break;
+		}
 	}
 
 	if (imgext) {
@@ -1432,6 +1448,15 @@ PHPAPI int php_getimagetype(php_stream *stream, const char *input, char *filetyp
 		return IMAGE_FILETYPE_XBM;
 	}
 
+	zend_ulong h;
+	zval *zv;
+	ZEND_HASH_FOREACH_NUM_KEY_VAL(&php_image_handlers, h, zv) {
+		const struct php_image_handler *handler = Z_PTR_P(zv);
+		if (handler->identify(stream) == SUCCESS) {
+			return (int) h;
+		}
+	} ZEND_HASH_FOREACH_END();
+
 	return IMAGE_FILETYPE_UNKNOWN;
 }
 /* }}} */
@@ -1440,6 +1465,7 @@ static void php_getimagesize_from_stream(php_stream *stream, char *input, zval *
 {
 	int itype = 0;
 	struct php_gfxinfo *result = NULL;
+	const char *mime_type = NULL;
 
 	if (!stream) {
 		RETURN_FALSE;
@@ -1464,6 +1490,7 @@ static void php_getimagesize_from_stream(php_stream *stream, char *input, zval *
 			result = php_handle_swf(stream);
 			break;
 		case IMAGE_FILETYPE_SWC:
+			/* TODO: with the new php_image_register_handler() APIs, this restriction could be solved */
 #if defined(HAVE_ZLIB) && !defined(COMPILE_DL_ZLIB)
 			result = php_handle_swc(stream);
 #else
@@ -1506,27 +1533,44 @@ static void php_getimagesize_from_stream(php_stream *stream, char *input, zval *
 		case IMAGE_FILETYPE_AVIF:
 			result = php_handle_avif(stream);
 			break;
-		default:
+		default: {
+			struct php_image_handler* handler = zend_hash_index_find_ptr(&php_image_handlers, (zend_ulong) itype);
+			if (handler) {
+				result = handler->get_info(stream);
+				mime_type = handler->mime_type;
+				break;
+			}
+			ZEND_FALLTHROUGH;
+		}
 		case IMAGE_FILETYPE_UNKNOWN:
 			break;
 	}
 
 	if (result) {
-		char temp[MAX_LENGTH_OF_LONG * 2 + sizeof("width=\"\" height=\"\"")];
 		array_init(return_value);
-		add_index_long(return_value, 0, result->width);
-		add_index_long(return_value, 1, result->height);
+		if (result->width_str) {
+			add_index_str(return_value, 0, result->width_str);
+			add_index_str(return_value, 1, result->height_str);
+		} else {
+			add_index_long(return_value, 0, result->width);
+			add_index_long(return_value, 1, result->height);
+		}
 		add_index_long(return_value, 2, itype);
-		snprintf(temp, sizeof(temp), "width=\"%d\" height=\"%d\"", result->width, result->height);
-		add_index_string(return_value, 3, temp);
+		if (result->width_str) {
+			add_index_str(return_value, 3, zend_strpprintf_unchecked(0, "width=\"%S\" height=\"%S\"", result->width_str, result->height_str));
+		} else {
+			char temp[MAX_LENGTH_OF_LONG * 2 + sizeof("width=\"\" height=\"\"")];
+			snprintf(temp, sizeof(temp), "width=\"%d\" height=\"%d\"", result->width, result->height);
+			add_index_string(return_value, 3, temp);
+		}
 
 		if (result->bits != 0) {
 			add_assoc_long(return_value, "bits", result->bits);
 		}
 		if (result->channels != 0) {
 			add_assoc_long(return_value, "channels", result->channels);
 		}
-		add_assoc_string(return_value, "mime", (char*)php_image_type_to_mime_type(itype));
+		add_assoc_string(return_value, "mime", mime_type ? mime_type : php_image_type_to_mime_type(itype));
 		efree(result);
 	} else {
 		RETURN_FALSE;
@@ -1589,3 +1633,36 @@ PHP_FUNCTION(getimagesizefromstring)
 	php_getimagesize_from_any(INTERNAL_FUNCTION_PARAM_PASSTHRU, FROM_DATA);
 }
 /* }}} */
+
+PHP_MINIT_FUNCTION(image)
+{
+	zend_hash_init(&php_image_handlers, 4, NULL, NULL, true);
+	return SUCCESS;
+}
+
+PHP_MSHUTDOWN_FUNCTION(image)
+{
+#ifdef ZTS
+	if (!tsrm_is_main_thread()) {
+		return SUCCESS;
+	}
+#endif
+	zend_hash_destroy(&php_image_handlers);
+	return SUCCESS;
+}
+
+extern zend_module_entry basic_functions_module;
+
+int php_image_register_handler(const struct php_image_handler *handler)
+{
+	zend_hash_index_add_ptr(&php_image_handlers, (zend_ulong) php_image_handler_next_id, (void *) handler);
+	zend_register_long_constant(handler->const_name, strlen(handler->const_name), php_image_handler_next_id, CONST_PERSISTENT, basic_functions_module.module_number);
+	Z_LVAL_P(zend_get_constant_str(ZEND_STRL("IMAGETYPE_COUNT")))++;
+	return php_image_handler_next_id++;
+}
+
+zend_result php_image_unregister_handler(int image_type)
+{
+	ZEND_ASSERT(image_type >= IMAGE_FILETYPE_FIXED_COUNT);
+	return zend_hash_index_del(&php_image_handlers, (zend_ulong) image_type);
+}
diff --git a/ext/standard/php_image.h b/ext/standard/php_image.h
@@ -18,6 +18,9 @@
 #ifndef PHP_IMAGE_H
 #define PHP_IMAGE_H
 
+PHP_MINIT_FUNCTION(image);
+PHP_MSHUTDOWN_FUNCTION(image);
+
 /* {{{ enum image_filetype
    This enum is used to have ext/standard/image.c and ext/exif/exif.c use
    the same constants for file types.
@@ -45,13 +48,13 @@ typedef enum
   IMAGE_FILETYPE_WEBP,
   IMAGE_FILETYPE_AVIF,
 /* WHEN EXTENDING: PLEASE ALSO REGISTER IN basic_function.stub.php */
-  IMAGE_FILETYPE_COUNT
+  IMAGE_FILETYPE_FIXED_COUNT
 } image_filetype;
 /* }}} */
 
 PHPAPI int php_getimagetype(php_stream *stream, const char *input, char *filetype);
 
-PHPAPI char * php_image_type_to_mime_type(int image_type);
+PHPAPI const char * php_image_type_to_mime_type(int image_type);
 
 PHPAPI bool php_is_image_avif(php_stream *stream);
 
@@ -65,4 +68,22 @@ struct php_gfxinfo {
 	unsigned int channels;
 };
 
+typedef zend_result (*php_image_identify)(php_stream *stream);
+typedef struct php_gfxinfo *(*php_image_get_info)(php_stream *stream);
+
+struct php_image_handler {
+	const char *mime_type;
+	const char *extension;
+	const char *const_name;
+	php_image_identify identify;
+	php_image_get_info get_info;
+};
+
+#define PHP_IMAGE_CONST_NAME(suffix) ("IMAGETYPE_" suffix)
+
+/* This should only be called on module init */
+PHPAPI int php_image_register_handler(const struct php_image_handler *handler);
+/* This should only be called on module shutdown */
+PHPAPI zend_result php_image_unregister_handler(int image_type);
+
 #endif /* PHP_IMAGE_H */
diff --git a/ext/standard/tests/image/image_type_to_mime_type_variation3.phpt b/ext/standard/tests/image/image_type_to_mime_type_variation3.phpt
