From 2f5808b65a6a43c68a5c763c88c02aa4ae44051a Mon Sep 17 00:00:00 2001
From: Brian Boy <97043252+derseitenschneider@users.noreply.github.com>
Date: Thu, 30 Jul 2026 13:33:35 +0200
Subject: [PATCH 1/2] Options, Meta APIs: Pass $unique to the
 add_{$meta_type}_meta and added_{$meta_type}_meta actions.

The $unique flag passed to add_metadata() was not exposed to the
add_{$meta_type}_meta and added_{$meta_type}_meta action hooks, so
callbacks could not tell whether the metadata being added was meant to
be unique for the object. Pass it as an additional argument, matching
the add_{$meta_type}_metadata filter which already receives it.
---
 src/wp-includes/meta.php                 |  8 +++--
 tests/phpunit/tests/meta/addMetadata.php | 43 ++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 tests/phpunit/tests/meta/addMetadata.php

diff --git a/src/wp-includes/meta.php b/src/wp-includes/meta.php
index c657c6c2e7af3..442fe0556d3b0 100644
--- a/src/wp-includes/meta.php
+++ b/src/wp-includes/meta.php
@@ -120,12 +120,14 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
 	 *  - `add_user_meta`
 	 *
 	 * @since 3.1.0
+	 * @since 7.2.0 The `$unique` parameter was added.
 	 *
 	 * @param int    $object_id   ID of the object metadata is for.
 	 * @param string $meta_key    Metadata key.
 	 * @param mixed  $_meta_value Metadata value.
+	 * @param bool   $unique      Whether the specified meta key should be unique for the object.
 	 */
-	do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );
+	do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value, $unique );
 
 	$result = $wpdb->insert(
 		$table,
@@ -159,13 +161,15 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
 	 *  - `added_user_meta`
 	 *
 	 * @since 2.9.0
+	 * @since 7.2.0 The `$unique` parameter was added.
 	 *
 	 * @param int    $mid         The meta ID after successful update.
 	 * @param int    $object_id   ID of the object metadata is for.
 	 * @param string $meta_key    Metadata key.
 	 * @param mixed  $_meta_value Metadata value.
+	 * @param bool   $unique      Whether the specified meta key should be unique for the object.
 	 */
-	do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
+	do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value, $unique );
 
 	return $mid;
 }
diff --git a/tests/phpunit/tests/meta/addMetadata.php b/tests/phpunit/tests/meta/addMetadata.php
new file mode 100644
index 0000000000000..bc9379aa700a4
--- /dev/null
+++ b/tests/phpunit/tests/meta/addMetadata.php
@@ -0,0 +1,43 @@
+<?php
+
+/**
+ * @group meta
+ * @covers ::add_metadata
+ */
+class Tests_Meta_AddMetadata extends WP_UnitTestCase {
+
+	/**
+	 * @ticket 39706
+	 *
+	 * @dataProvider data_actions_should_receive_unique
+	 *
+	 * @param bool $unique Whether the specified meta key should be unique for the object.
+	 */
+	public function test_actions_should_receive_unique( $unique ) {
+		$add_action   = new MockAction();
+		$added_action = new MockAction();
+
+		add_action( 'add_post_meta', array( $add_action, 'action' ), 10, 4 );
+		add_action( 'added_post_meta', array( $added_action, 'action' ), 10, 5 );
+
+		add_metadata( 'post', 123, 'test_key', 'value', $unique );
+
+		$add_args   = $add_action->get_args();
+		$added_args = $added_action->get_args();
+
+		$this->assertSame( $unique, $add_args[0][3], 'The add_post_meta action should receive the value of $unique.' );
+		$this->assertSame( $unique, $added_args[0][4], 'The added_post_meta action should receive the value of $unique.' );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public function data_actions_should_receive_unique() {
+		return array(
+			'unique meta'     => array( true ),
+			'non-unique meta' => array( false ),
+		);
+	}
+}

From 3e6927acab319a2d55d9b8d51f985cbeb0682282 Mon Sep 17 00:00:00 2001
From: Brian Boy <97043252+derseitenschneider@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:42:33 +0200
Subject: [PATCH 2/2] Clarify that $mid in the added_{$meta_type}_meta docblock
 refers to an addition, not an update.

---
 src/wp-includes/meta.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/wp-includes/meta.php b/src/wp-includes/meta.php
index 442fe0556d3b0..12cb518bbeaaa 100644
--- a/src/wp-includes/meta.php
+++ b/src/wp-includes/meta.php
@@ -163,7 +163,7 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
 	 * @since 2.9.0
 	 * @since 7.2.0 The `$unique` parameter was added.
 	 *
-	 * @param int    $mid         The meta ID after successful update.
+	 * @param int    $mid         The meta ID after successful addition.
 	 * @param int    $object_id   ID of the object metadata is for.
 	 * @param string $meta_key    Metadata key.
 	 * @param mixed  $_meta_value Metadata value.