From 3db78d6a24b7d5238de2cd1a0251ad9099a43fd3 Mon Sep 17 00:00:00 2001
From: Boone Gorges <boonebgorges@gmail.com>
Date: Fri, 27 Feb 2015 20:31:26 +0000
Subject: [PATCH] Introduce 'get_object_terms' filter in
 `wp_get_object_terms()`.

The existing 'wp_get_object_terms' filter accepts a parameter `$taxonomies`,
which is a list of taxonomy names formatted for direct use in a MySQL IN clause.
This formatting makes it difficult to make use of the taxonomy list in filter
callbacks. However, changing the parameters passed to the existing filter
raises backward compatibility concerns, so we introduce a new filter that
receives a structured `$taxonomy_array` parameter.

We also take this opportunity to correct and clean up some of the documentation
on the 'wp_get_object_terms' filter.

Props postpostmodern, doublesharp, wonderboymusic, nacin.
Fixes #18828.
Built from https://develop.svn.wordpress.org/trunk@31581


git-svn-id: http://core.svn.wordpress.org/trunk@31562 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/taxonomy.php | 28 +++++++++++++++++++++++-----
 wp-includes/version.php  |  2 +-
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php
index 0c7c0f03ab..4b1c1f1400 100644
--- a/wp-includes/taxonomy.php
+++ b/wp-includes/taxonomy.php
@@ -2693,6 +2693,7 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) {
 	if ( '' !== $order && ! in_array( $order, array( 'ASC', 'DESC' ) ) )
 		$order = 'ASC';
 
+	$taxonomy_array = $taxonomies;
 	$taxonomies = "'" . implode("', '", $taxonomies) . "'";
 	$object_ids = implode(', ', $object_ids);
 
@@ -2762,16 +2763,33 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) {
 	} elseif ( ! $objects ) {
 		$terms = array_values( array_unique( $terms ) );
 	}
+
 	/**
 	 * Filter the terms for a given object or objects.
 	 *
+	 * @since 4.2.0
+	 *
+	 * @param array     $terms          An array of terms for the given object or objects.
+	 * @param int|array $object_ids     Object ID or array of IDs.
+	 * @param array     $taxonomy_array Array of taxonomies from which `$terms` were retrieved.
+	 * @param array     $args           An array of arguments for retrieving terms for the given object(s).
+	 *                                  See {@see wp_get_object_terms()} for details.
+	 */
+	$terms = apply_filters( 'get_object_terms', $terms, $object_ids, $taxonomy_array, $args );
+
+	/**
+	 * Filter the terms for a given object or objects.
+	 *
+	 * The `$taxonomies` parameter passed to this filter is formatted as a SQL fragment. The
+	 * {@see 'get_object_terms'} filter is recommended as an alternative.
+	 *
 	 * @since 2.8.0
 	 *
-	 * @param array        $terms      An array of terms for the given object or objects.
-	 * @param array|int    $object_ids Object ID or array of IDs.
-	 * @param array|string $taxonomies A taxonomy or array of taxonomies.
-	 * @param array        $args       An array of arguments for retrieving terms for
-	 *                                 the given object(s).
+	 * @param array     $terms      An array of terms for the given object or objects.
+	 * @param int|array $object_ids Object ID or array of IDs.
+	 * @param string    $taxonomies SQL-formatted (comma-separated and quoted) list of taxonomy names.
+	 * @param array     $args       An array of arguments for retrieving terms for the given object(s).
+	 *                              See {@see wp_get_object_terms()} for details.
 	 */
 	return apply_filters( 'wp_get_object_terms', $terms, $object_ids, $taxonomies, $args );
 }
diff --git a/wp-includes/version.php b/wp-includes/version.php
index d477bb8e9b..02d1aac434 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.2-alpha-31580';
+$wp_version = '4.2-alpha-31581';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.