wp set object terms vs wp set post terms

Question

Examining the following sample code snippet from the WP codex,

$post = array(
  'ID' => [ <post id> ] //Are you updating an existing post?
  'post_author' => [ <user ID> ] //The user ID number of the author.
  'post_category' => [ array(<category id>, <...>) ] //Add some categories.
  'post_content' => [ <the text of the post> ] //The full text of the post.
  'post_date' => [ Y-m-d H:i:s ] //The time post was made.
  'post_title' => [ <the title> ] //The title of your post.
  'post_type' => 'post'
  'tags_input' => [ '<tag>, <tag>, <...>' ] //For tags.
  'tax_input' => [ array( 'taxonomy_name' => array( 'term', 'term2', 'term3' ) ) 
);  

I see that only the categories take their input by IDs.

For some reason, ( which I'd like to know the history behind it as to why), tags and custom taxonomies takes their input differently.

Here, we are looking at 3 different ways to set the taxonomy terms;

For cats, use

'post_category' => [ array(<category id>, <...>) ]

for tags, use,

'tags_input' => [ '<tag>, <tag>, <...>' ]

and finally for CT's, use

'tax_input' => [ array( 'taxonomy_name' => array( 'term', 'term2', 'term3' ) ) 

With this 3 different ways, I think things are getting complicated. It's not that it cannot be done but programmatically, it seems more complicated than it should be.

I thought why don't I just use the Uncategorized Cat ID of 1 here ( within the post wp_insert_post ) just to get the post in, and then take care of the proper cats , tags and custom taxonomies, all using the same function call.

With that in mind, I have 2 choices; wp set object terms and wp set post terms

I'd like to know if one is better than the other and why we have two different but very similar ( almost like a subset vs superset ) type situation here.

Which one is recommended to use when managing thousands of posts, and cats, tags programmatically - especially in a migration phase?

Answer 1

Right there is no big difference between them, actually wp_set_post_terms() uses wp_set_object_terms() but does few extra check for you. That's also noted on wp_set_object_terms() Codex page:

Perhaps the wp_set_post_terms() is a more useful function, since it checks the values​​, converting taxonomies separated by commas and validating hierarchical terms in integers.

https://developer.wordpress.org/reference/functions/wp_set_object_terms/

Answer 2

I'd like to know if one is better than the other

No matter what happens you will be using wp_set_object_terms either directly or indirectly. The final line of wp_set_post_terms is:

return wp_set_object_terms( $post_id, $tags, $taxonomy, $append );

In this case it would be best to prefer wp_set_post_terms due to the additional checks and processing it performs, but it will have a negligible impact on performance for large migrations, and is a micro-optimisation.

---

why we have two different but very similar ( almost like a subset vs superset ) type situation here.

As for why there are 2 separate functions, it may be useful to know that not all terms and taxonomies are for posts. It is possible to create taxonomies and terms for other objects too, such as user taxonomies, comment taxonomies, etc. Much like how you can have user meta, comment meta etc. WP Admin may not provide UI for these or take advantage of them out of the box, but it is still possible. The only rule is that you can't use the same taxonomy for multiple object types e.g. posts and users at the same time, because the object ID is just a number, and there'd be no way to distinguish between user 1 and post 1.

Likewise there are similar APIs and functions for meta that are not post specific, e.g. get_metadata( 'post', $post_id, 'key-name', true )